Programmer's Guide



Chapter 2   Coding Java for SilverStream Applications

Much of the work in developing SilverStream applications involves coding Java. This chapter presents some key things you need to know about Java in this context, including:

Using Java   Top of page

Java is a standard language for Web applications and you'll use it in a standard way when developing Web applications to run on the SilverStream Server. For instance, you'll:

Java platform support   Top of page

SilverStream supports the Java 2 platform, including:

These encompass the core Java language and a variety of Java APIs.

About the core language   Top of page

The core Java language is the syntax you use to perform basic programming chores. It includes:

Much of this syntax is modeled after C and C++. JavaScript programmers will find some similarities too (although Java and JavaScript differ in other significant ways).

About APIs   Top of page

API is short for application programming interface. In Java, an API is a collection of public classes (in one or more packages) that:

For business programming, where productivity is especially important, you'll always access one or more APIs. For example, the Java standard (J2SE) API provides many of the most fundamental capabilities you'd want to build into any application (including support for: graphical user interfaces, input/output, data type manipulation, threading, networking, security, SQL, internationalization, and a lot more). There's no need to develop these capabilities yourself.

Other Java and vendor APIs (such as the SilverStream API) take you beyond generic application services to fulfill higher level system and business needs.

Resources for learning Java   Top of page

If you're new to Java or just need to explore a specific Java topic, try the following recommended learning resources.

Resource

Description

The Java Tutorial

A practical programming guide covering all the basics of Java, with many working examples

    Available on the Sun Java Web site: www.javasoft.com

Java 2 SDK, Standard Edition Documentation

An index to Java learning and reference materials from Sun, with links to many documents and Web sites

    See this page in the API Reference book in SilverStream help: Java 2 Standard SDK

Java techniques

Code examples of basic Java techniques you'll commonly use in your SilverStream applications

    See this page in the Application Techniques book in SilverStream help: Core Programming Techniques

Other books

There are many other Java books available, but some good ones are:

Other Web sites

There are many other Java sites on the Web, but some good ones are:

Using the Java APIs   Top of page

When building an application, you'll use particular Java APIs depending on the features or services that application requires. To help you choose which APIs you need, Sun has grouped them in different editions of the Java 2 platform:

Java API support   Top of page

SilverStream supports the Java APIs as follows.

API

Version

See this API Reference page in SilverStream help

Java 2 Platform, Standard Edition

1.2.2

Java 2 Standard API

Enterprise JavaBeans

1.1

Java 2 Enterprise APIs>EJB API

Java Servlet

2.1

Java 2 Enterprise APIs>Servlet & JSP API

JavaServer Pages

1.0

Java 2 Enterprise APIs>Servlet & JSP API

JavaMail

1.1.3

Java 2 Enterprise APIs>JavaMail API

JavaBeans Activation Framework

1.0.1

Java 2 Enterprise APIs>JAF API

Java Transaction

1.0

Java 2 Enterprise APIs>Transaction API

JDBC Optional Package

2.0

Java 2 Enterprise APIs>JDBC Optional API

Java Naming and Directory Interface

1.2

Java 2 Enterprise APIs>JNDI API

RMI-IIOP

1.0

Java 2 Enterprise APIs>RMI-IIOP API

Using the SilverStream API   Top of page

To implement SilverStream features and services in your application, you can use SilverStream API classes in your Java code and call their methods. The SilverStream API provides public classes (and interfaces) for both the client and server portions of an application, organized into several packages.

The SilverStream API is based on the Java 2 APIs (J2SE and J2EE). That means it includes classes that inherit from Java 2 classes and implement Java 2 interfaces. If you're familiar with the Java 2 APIs, you'll have a good foundation for understanding and using the SilverStream API.

SilverStream API packages   Top of page

Given the number of packages in the SilverStream API and their various uses, it's helpful to look at them in a couple of different ways:

That way, you can choose the appropriate packages to fulfill your application requirements.

Packages by function

Use the following table to find the packages that provide the major SilverStream features or services you want in your application.

Functional area

Feature or service

Packages

SilverStream HTML clients (visual servlets)

Pages, page controls, HTML-based views

com.sssw.shr.page

SilverStream Java clients

Forms, AWT-based controls, Java-based views

com.sssw.rt.form

Swing-based controls

com.sssw.rt.jform

Dynamically constructed Java-based views

com.sssw.rt.tview

Font support

com.sssw.rt.gui

Enterprise JavaBeans

Entity bean support

com.sssw.srv.ejb

Triggered business objects

Listeners, events, and data sources for triggered business objects

com.sssw.srv.busobj

E-mail processing (reading, creating, sending)

com.sssw.srv.mail

Full text search support

com.sssw.srv.agents

Business object invocation

com.sssw.rt.util

Data access

Data source access, row cursor processing, transaction handling

com.sssw.rt.util

JDBC data source and connection pool support

com.sssw.srv.dbpool

Server access and failover

Remote connection to SilverStream Server, user login

com.sssw.rt.util

Persistent session-level failover for HTML applications

com.sssw.atg.persist

Server administration

Management of SilverStream Server (resources, performance, configuration)

com.sssw.rts.acl

com.sssw.rts.adminapi

com.sssw.rts.adminclient

com.sssw.srv.api

Utility services

Data type conversion, formatting, and parsing

com.sssw.rt.util

Expression evaluation

com.sssw.rt.expr

Runtime event support

com.sssw.rt.event

Request and response support for HTTP servlets

com.sssw.shr.http

COM object and DLL access

com.sssw.rt.com

Packages by tier

The following table shows which SilverStream packages run on the client tier of an application, which run on the server tier, and which may run on either tier (depending on their use).

Tier

Packages

Client (Java clients)

com.sssw.rt.form

com.sssw.rt.gui

com.sssw.rt.jform

com.sssw.rt.tview

com.sssw.rts.adminclient

Server (the SilverStream Server)

com.sssw.atg.persist

com.sssw.shr.http

com.sssw.shr.page

com.sssw.srv.agents

com.sssw.srv.api

com.sssw.srv.busobj

com.sssw.srv.dbpool

com.sssw.srv.ejb

com.sssw.srv.mail

Common (client or server)

com.sssw.rt.com

com.sssw.rt.event

com.sssw.rt.expr

com.sssw.rt.util

com.sssw.rts.acl

com.sssw.rts.adminapi

NOTE   This table reflects the public use of SilverStream API packages. Internally, SilverStream may use some packages in additional ways.

SilverStream API terminology   Top of page

The name SilverStream API refers to all of the public packages. You'll also see the term API applied to certain subsets of these packages. For instance, the name Server Administration API is typically used to refer to this group of packages:

Just remember that these other APIs are simply convenient labels for talking about specific portions of the full API.

SilverStream API reference documentation   Top of page

SilverStream provides a complete API specification in javadoc format. This specification details all of the packages, classes, interfaces, and members in the public SilverStream API, and includes links into the Java 2 API documentation. It's an indispensable reference for all the SilverStream programming you do in Java.

    See this page in the API Reference book in online help: SilverStream API.

Coding in the SilverStream development environment   Top of page

You can use the Java development tools of your choice to build SilverStream applications, ranging from code editors to complete IDEs (integrated development environments). If you're using the SilverStream Designer as your IDE, read this section to learn about Java coding in that environment.

SilverStream API support   Top of page

The SilverStream Designer supports the full SilverStream API. That means you can use any packages, classes, interfaces, and members from the API when you work in the Designer to build your application.

In addition, the Designer makes it easy to access the SilverStream API. It:

How you'll work   Top of page

Programming in the SilverStream Designer involves:

The Java coding portion of your work includes editing, compiling, testing, and packaging.

Editing

You'll use the Programming Editor to write Java code in the Page Designer, Form Designer, and Business Object Designer. It enables you to use the full Java language, Java APIs, and SilverStream API to write:

The Programming Editor also lets you compile your edited code and save it to the SilverStream Server.

    For all the details on working in the SilverStream Programming Editor, see the Programming Editor chapter in the online Tools Guide.

Using an external editor

If you have a favorite editor (such as Codewright) that you prefer to use, you can tell the SilverStream Programming Editor to take you there for your Java code editing:

Then you can return to the SilverStream Programming Editor to compile your edited code and save it to the SilverStream Server.

    To learn about setting preferences for the external editor to use, see the Main Designer chapter in the online Tools Guide. For details on launching and accepting changes from your external editor, see the Programming Editor chapter in the Tools Guide.

Importing Java packages

The Programming Editor automatically generates import statements for the most common Java API packages you need in your code. For example, you might see these imports in the code for a page:

  import java.awt.*; 
  import java.util.*; 
  import java.math.*; 
  import java.awt.event.*; 
  import java.io.*; 
  import javax.servlet.*; 
  import javax.servlet.http.*; 

The specific imports you get depend on the kind of object you're developing. You can add imports yourself for any additional packages you access.

Importing SilverStream packages

Besides generating import statements for Java API packages, the Programming Editor automatically generates imports for SilverStream API packages you need in your code. For example, you might see these imports in the code for a page:

  import com.sssw.rt.gui.*; 
  import com.sssw.rt.util.*; 
  import com.sssw.rt.event.*; 
  import com.sssw.rt.expr.*; 
  import com.sssw.shr.page.*; 
  import com.sssw.shr.http.AgiHttpServletRequest; 
  import com.sssw.shr.http.AgiHttpServletResponse; 
  import com.sssw.shr.http.AgoServletException; 
  import com.sssw.srv.api.*; 
  import com.sssw.srv.busobj.*; 
  import com.sssw.srv.mail.*; 

Again, the specific imports you get depend on the kind of object you're developing. And, you can add imports yourself for any additional packages you access.

About Simple Actions

Within the Form Designer, the Programming Editor provides a supplementary, high-level coding facility called Simple Actions. This feature is especially for newer programmers who want a quick way to generate application logic without writing detailed syntax.

Under the covers, Simple Actions produce Java code. In fact, you can start with Simple Actions and switch to examine and edit the Java code at any time. Just note that once you alter the Java, you can't switch that code back to Simple Actions.

    For more information on switching between Simple Actions mode and Java mode, see the Programming Editor chapter in the online Tools Guide.

Compiling

To compile any Java code you write in the Programming Editor (or in an external editor), you just need to save your work to the SilverStream Server. You can ask to save directly in the Programming Editor or in the corresponding Designer. The Programming Editor also has a Check Syntax command that looks for compile errors without saving anything.

Compile errors display at the bottom of the Programming Editor window:

    For more information on compiling Java code in the SilverStream Designer, see the Programming Editor chapter in the online Tools Guide.

Changing compiler settings

The SilverStream Main Designer lets you edit preferences for several compiler settings. You can specify the Java compiler you want to use, flag and debug options, and the location of the compile cache:

    For more information on changing compiler settings, see the Main Designer chapter in the online Tools Guide.

About the compile cache

The compile cache is a local directory where the SilverStream Designer stores source and class files when compiling your Java code. It is typically named compilecache and located in your SilverStream install directory.

The compile cache contains trees of subdirectories for each SilverStream server and database you work on. For instance, here's what was in someone's compile cache for the database Examples3_EJB on the server localhost:

Within the compile cache, you'll find the JAVA and CLASS files for different kinds of objects organized by the packages they're in:

The compile cache also includes a source subdirectory named agEditor where the SilverStream Designer stores temporary JAVA files while you're working in an external editor. Whenever you tell the SilverStream Programming Editor to retrieve your externally edited code, it gets that code from here.

Using the compile cache

You can explore the compile cache and read any of the JAVA files it contains. This may be useful when you want more of an inside look into how your application is implemented in SilverStream.

CAUTION!   The compile cache is not intended for you to edit. Changes you make there may either be lost or cause unpredictable results.

Compiling multiple files

Sometimes you'll need to compile several files at once. The SilverStream Main Designer provides a Build command that enables you to compile multiple selected files, an entire directory of files, or all files in your application (database). For example, if you use source control to get files edited by someone else, you'll need to build those files.

    For more information on doing builds, see the Main Designer chapter in the online Tools Guide.

Testing

The most basic way to test the Java code you write is to run particular pages or forms and see if they work as intended. You can do that from the Page, Form, or Main Designer. If you discover or suspect any kind of problem, you can try solving it with one of these additional tools:

Using the SilverStream Debugger

The Debugger helps you find runtime bugs by controlling and monitoring the execution of your Java code. You can debug both client-side code (forms) and server-side code (pages and business objects), either on a local host machine or remotely on distributed machines.

Here's an example of debugging a page on the SilverStream Server that shows how you can:

    For more information on debugging, see the SilverStream Debugger chapter in the online Tools Guide.

Using the Java Console

You can use the Java Console to help with your form debugging. It displays System.out and System.err output, including AgfForm.debugPrint() and println() methods, from your client-side code:

The Java Console also displays compile messages. You can start it from the SilverStream Main Designer.

    For more information on using the Java Console, see the Main Designer chapter in the online Tools Guide.

Using the Server Console

You can use the Server Console to help with your page and business object debugging. It displays System.out and System.err output, including println() methods, from your server-side code:

The Server Console also displays server debug messages for client requests, business object execution, and database SQL statements (according to what you turn on in the SilverStream Management Console). You can start it from the SilverStream Main Designer.

    For more information on using the Server Console, see the Main Designer chapter in the online Tools Guide.

Using the SilverStream Profiler

The Profiler helps you identify and analyze performance bottlenecks in your code caused by inefficient methods, memory leaks, and contended monitors in synchronized processes. You can invoke the Profiler by supplying a command-line option when starting a SilverStream executable (such as SilverServer.exe), then use it to study processes running in that context.

    For more information on profiling, see the SilverStream Profiler chapter in the online Tools Guide.

Packaging

To organize the business objects and utility classes you develop, you typically put them into packages. The Main Designer enables you to create packages and create objects in them (by going to the Business Object Designer).

The following example shows classes and interfaces that someone has created in their own package hierarchy:

  com.examples.companydemo 

While editing the code for an object, you can alter its package statement (and then save) to copy that object to a different package:

    For more information on creating packages, see the Business Object Designer chapter in the online Tools Guide. To learn more about editing package statements, see the Programming Editor chapter in that guide.

NOTE   Packaging for forms, pages, and views is controlled by the SilverStream Designer. You don't specify your own packages for them.

Using JAR files

It's also common to bundle packages, classes, and other application files into JAR files. JARs are standard Java archive files used to support deployment (for JavaBeans, Enterprise JavaBeans, and JavaServer Pages), downloading (for files used by forms on the client), and dynamic references (to classes from other SilverStream databases).

The Main Designer enables you to create JARs and go to the JAR Designer to edit their details. It also lets you upload externally created JARs that you want to use on the SilverStream Server for your applications.

Here's a JAR named CompanyDemo.jar that someone has defined in the JAR Designer to contain the package com.examples.companydemo:

    For more information on working with JAR files, see the JAR Designer chapter in the online Tools Guide and Using Utility Classes, JAR Files, and JavaBeans in the Programmer's Guide.

Coding in external development environments   Top of page

You might already have a Java development environment that you like to work in--either a third-party code editor (such as Codewright) or complete IDE (such as JBuilder or Cafe). In that case, you may choose to build your SilverStream applications there, without using the SilverStream Designer.

Read this section to learn about accessing the SilverStream API and writing SilverStream classes when working in an external Java development environment.

SilverStream API support   Top of page

From an external development environment, you have access to a large subset of the SilverStream API. You can use the packages, classes, interfaces, and members that the API provides for coding:

What's not supported

Not supported in external development are the parts of the API used exclusively for SilverStream pages, forms, and views. This is mainly because the API itself doesn't include everything required to completely define these objects. You need to use the SilverStream Designers to do that before you can start writing API code.

Supported packages by function

The following table lists the SilverStream API packages supported for external development, organized by the function each performs. Use it to find the packages that provide the major SilverStream features or services you want in your application.

Functional area

Feature or service

Packages

Enterprise JavaBeans

Entity bean support

com.sssw.srv.ejb

Triggered business objects

Listeners, events, and data sources for triggered business objects

com.sssw.srv.busobj

E-mail processing (reading, creating, sending)

com.sssw.srv.mail

Full text search support

com.sssw.srv.agents

Business object invocation

com.sssw.rt.util

Data access

Data source access, row cursor processing, transaction handling

com.sssw.rt.util

JDBC data source and connection pool support

com.sssw.srv.dbpool

Server access and failover

Remote connection to SilverStream Server, user login

com.sssw.rt.util

Persistent session-level failover for HTML applications

com.sssw.atg.persist

Server administration

Management of SilverStream Server (resources, performance, configuration)

com.sssw.rts.acl

com.sssw.rts.adminapi

com.sssw.rts.adminclient

com.sssw.srv.api

Utility services

Data type conversion, formatting, and parsing

com.sssw.rt.util

Expression evaluation

com.sssw.rt.expr

Runtime event support

com.sssw.rt.event

Request and response support for HTTP servlets

com.sssw.shr.http

COM object and DLL access

com.sssw.rt.com

Supported packages by tier

For those SilverStream packages supported for external development, the following table shows which ones run on the client tier of an application, which run on the server tier, and which may run on either tier (depending on their use).

Tier

Packages

Client (Java clients)

com.sssw.rts.adminclient

Server (the SilverStream Server)

com.sssw.atg.persist

com.sssw.shr.http

com.sssw.srv.agents

com.sssw.srv.api

com.sssw.srv.busobj

com.sssw.srv.dbpool

com.sssw.srv.ejb

com.sssw.srv.mail

Common (client or server)

com.sssw.rt.com

com.sssw.rt.event

com.sssw.rt.expr

com.sssw.rt.util

com.sssw.rts.acl

com.sssw.rts.adminapi

NOTE   This table reflects the public use of SilverStream API packages. Internally, SilverStream may use some packages in additional ways.

Setup requirements   Top of page

Before you can code and compile a SilverStream application in an external Java development environment, you must set up that environment to access the SilverStream API packages. This involves:

    To learn how to set up if you're using one of the SilverStream integrations for external IDEs, see the online Using External IDEs book.

    To learn about setting up deployed Java client applications to access the SilverStream packages they need, see Writing External Java Clients.

Installing SilverStream files

To access the SilverStream packages, your development environment requires the ZIP and JAR files from SilverStream that contain those packages as well as some supporting Java and third-party packages (including JBroker).

The recommended way to get all of these files is to install the SilverStream Server on your local development machine. (You'll typically want to have a local server anyway, for testing and debugging your externally written SilverStream applications.)

    For instructions on installing the SilverStream Server, see the Installation Guide.

Setting your classpath

Once you've installed, you need to make sure your development environment can find the ZIP and JAR files that contain the SilverStream and supporting packages. You can do that by setting your classpath to list these files.

There are several ways to set the classpath, including:

Choose the way that's most appropriate for how you work and the tools you use.

Listing the SilverStream files

The following table shows the SilverStream ZIP and JAR files you need to list on your classpath. You'll list one or more of these, depending on the kinds of classes you're developing.

If you're developing

Add this file to your classpath

Typical location (may be different on your system)

Any client classes that will access the SilverStream Server

SilverRuntime.zip

C:\SilverStream35\lib

SilverClientObjectEra_Jbroker.zip

C:\SilverStream35\Resources\
Orbs

Any client classes that will use SSL (Secure Socket Layer) to access the domestic (U.S.) version of the SilverStream Server

SilverDomestic.zip

C:\SilverStream35\lib

Any client classes that will administer the SilverStream Server

SilverAdmin.jar

C:\SilverStream35\lib

Any server classes that will run on the SilverStream Server

SilverServerAll.zip

C:\SilverStream35\lib

Any server classes that will use the com.sssw.atg.persist package to implement persistent session-level failover

SilverPersist.jar

C:\SilverStream35\lib

Listing the Java and third-party files

The following table shows the other supporting ZIP and JAR files you need to list on your classpath. It's recommended that you always list all of these.

Category

Functional area

File name

Typical location (may be different on your system)

Java

EJB

ejb.jar

C:\SilverStream35\lib

ejb_1_0.zip

C:\SilverStream35\lib

JavaBeans activation

activation.jar

C:\SilverStream35\lib

JavaMail

mail.jar

C:\SilverStream35\lib

pop3.jar

C:\SilverStream35\lib

JNDI and RMI

ldap.jar

C:\SilverStream35\lib

nisplus.jar

C:\SilverStream35\lib

cosnaming.jar

C:\SilverStream35\jre\lib\ext

jndi.jar

C:\SilverStream35\jre\lib\ext

providerutil.jar

C:\SilverStream35\jre\lib\ext

rmiregistry.jar

C:\SilverStream35\jre\lib\ext

Servlets and JSP

servlet.jar

C:\SilverStream35\lib

SQL and transactions

javax_sql.zip

C:\SilverStream35\lib

javax_trans.zip

C:\SilverStream35\lib

Third-party

CORBA and RMI-IIOP

jbroker.jar

C:\SilverStream35\jre\lib\ext

Debugging

debug.jar

C:\SilverStream35\lib

XML

xml4j.jar

C:\SilverStream35\lib

Compiler troubleshooting

If you have trouble compiling classes for your SilverStream application, you should check that:

Importing SilverStream packages

You'll generally want to include import statements for the SilverStream packages you use in your code. For example:

  import com.sssw.rt.util.*; 

That way, you won't need to fully qualify the names of SilverStream API classes you reference. Almost all of those classes follow a unique naming convention (beginning with Ag), so you shouldn't normally encounter naming conflicts when omitting package qualifiers.

How you'll work   Top of page

No matter which external Java development environment you use, you'll perform the following steps to build SilverStream applications.

Step 1: Code classes

To code your classes, you'll use:

Step 2: Compile your classes

To compile your classes, you'll use:

Step 3: Import your classes to the SilverStream Server

To import your server classes, you'll use:

Step 4: Test your application

To test how your classes work when the application runs, you'll use:






Copyright © 2000, SilverStream Software, Inc. All rights reserved.