Programmer's Guide

Chapter 4 Using Utility Classes, JAR Files, and JavaBeans

This chapter is an overview of how to use Java classes, JAR files, and JavaBeans in the SilverStream environment. It contains the following sections:

About Java utility classes

Utility classes are Java classes that you create in the Business Object Designer. Utility classes are created as triggerless objects, as opposed to triggered business objects. Utility objects can be treated like any standard Java class, with the following exceptions:

Utility classes do not support inner classes.
Utility classes do not support multiple classes in a single file.

Generally, you should organize your utility classes into packages, the standard Java class file directory. After creating your packages you can place them in JAR files as part of your SilverStream application deployment.

You can use utility classes with any code running on the server, such as business objects and pages, as long as they are in the same database. To use utility classes with client-side Java applications such as SilverStream forms, or to use them with objects in another database, you must make them accessible from JAR files.

NOTE It is good coding practice to place commonly used utility classes in JARs. This ensures that all SilverStream objects that reference them are using the same versions.

For instructions on creating a utility class, see the Business Object Designer chapter in the online Tools Guide.

Importing a utility object created externally

You can use a Java class written in an external editor, then import the class or file using the SilverCmd Import utilities.

For information, see the chapter on SilverCmd in the Facilities Guide of the server's Core Help.

Using utility classes

You can use a utility class to encapsulate some general-use code on the server. Here are some applications where you might use utility objects.

Common routines For example, you might have some calculation like a loan mortgage formula that you want to be accessible from a Java and HTML form, and perhaps from a business object as well.

Multithreading Use utility objects to create a separate thread of execution in your program. To do this you implement the Runnable interface and invoke the thread with the run() method.

Accessing data You can pass SilverStream data cache objects (AgxDatas) to utility objects for various purposes. You might do this, for example, to create a validation routine for forms and pages.

There are many examples of utility classes in the sample databases. If you have these databases running on your machine, see the Objects directories in the HTML Examples and Java Examples databases.

Utility objects, ClassLoaders, and session management

Session management with utility objects can be an issue particularly in the development environment, where several developers might be using the same resources. Consider the following scenario:

You have two business objects, A and B, and a utility class foo all in the same package.

Object A instantiates foo and saves the instance to a session object P.
NOTE The session object can be returned using evt.getSession() or any session-persistent storage, such as serialization to the file system.
A developer changes foo and saves the result, using the Business Object Designer.
Object B (or any other business object in the package) gets foo out of the Session object.

In this example, objects A and B got a new ClassLoader when the developer saved the new version of foo. At this point A and B are expecting the new version of foo. Therefore if either object gets the session instance of foo, which is the earlier version, the system will throw an exception, typically a Class cast exception.

To avoid this problem, developers should always clear objects from the current session or start new sessions.

NOTE Normally, to publish any changes in the production in environment, you would quiesce the server to prevent new user sessions, and wait for any existing sessions to finish.

Using JAR files in SilverStream

JAR files are the standard Java mechanism to package and distribute Java classes and supporting resources. SilverStream provides a point-and-click user interface that allows you to create and manipulate JAR files, JavaBeans, and Enterprise JavaBeans (EJBs).

For more information, see the Jar Designer chapter in the online Tools Guide.

Within the SilverStream environment, you must use JAR files in the following cases:

When referencing utility classes from pages or business objects that reside in a different database, you must place the utility classes in a JAR file. Otherwise, the page or object cannot compile. If the user-defined classes referenced by these pages or objects reside in the same database, the JAR file is not necessary. For more information, see About Java utility classes.
When creating forms that reference utility classes or interfaces—for example, a collection of classes that implement a linked-list utility class. Note that SilverStream does not automatically download user-defined classes.
When using JavaBeans. See Using JavaBeans in SilverStream.

Using JAR files to enhance performance

For forms that do not reference user-defined classes, you can optionally create JARs to make subforms, dialogs, and images download faster. If you do not use a JAR, these referenced items still download, one at a time. When placed in a JAR file, the JAR file is downloaded and classes will be loaded locally from the JAR file.

Using JavaBeans in SilverStream

JavaBeans are self-contained reusable software units that can be plugged together to build Java applications. In a SilverStream environment, you can use JavaBeans written by a third-party or you can write your own JavaBeans as visual components (such as icons or buttons) that can be dragged onto forms and pages. JavaBeans must be packaged in JAR files.

JavaBeans for pages are generally different from JavaBeans used on forms. When a page JavaBean is activated, the JavaBean generates HTML, which is inserted into the page. For example, a sophisticated JavaBean could be constructed to generate JavaScript that interacts with user input or even with other HTML data downloaded from the server.

JavaBeans created for use on forms can be used both in SilverStream and in non-SilverStream applications. JavaBean usage on pages is limited to SilverStream applications.

Importing a third-party JavaBean

JavaBeans reside in JAR files. To use a third-party JavaBean (a JavaBean created outside your SilverStream environment) you must import the JAR file into your SilverStream database.

Some JavaBeans use the JDK 1.0 event model. SilverStream only supports JavaBeans that use the newer 1.1 or 1.2 event model. Most existing third-party JavaBeans are visual JavaBeans, and you probably wouldn't want to use them on a SilverStream page. Instead, you would use a SilverStream Page JavaBean.

Follow these steps to import a JAR containing a third-party JavaBean:

Make sure the JAR file containing the JavaBean is on a disk that is accessible from the SilverStream Designer.
Choose the EJB, JARS & Media icon in the left pane of the Designer window for the database.
Click the New button and select Upload JAR, ZIP, or EJB from the dropdown list. The Open File dialog box appears.
Select the directory, select the JAR file you want to import, and click Open. SilverStream saves the JAR file in the JARs directory of your database under Media.

Specifying JavaBeans in a Manifest file

A JAR file can contain many kinds of files, such as Java classes, JavaBeans, image files, forms, views, and so on. Sometimes JAR files include a Manifest file describing the JAR contents.

If the JAR file contains any JavaBeans, the JAR file must include a Manifest file containing the name of each JavaBean class and specifying that it is a JavaBean.

For information about creating Manifest files, see the Jar Designer chapter in the online Tools Guide.

Using a JavaBean in your application

Once a JavaBean is loaded into the SilverStream environment, you can use the JavaBean in your SilverStream application. The JavaBeans appear in the Media directory in the Form Designer and Page Designer galleries. Graphical JavaBeans can be dragged from these galleries onto the form or page.

SilverStream applications can use three kinds of JavaBeans:

SilverStream Page JavaBeans. These generate HTML and are specific to SilverStream.
NOTE You can drop only Page JavaBeans on a page. The JavaBean must be designed specifically to run on a SilverStream page.
Component JavaBeans that extend java.awt.Component. These are typically used only on forms but (on a rare occasion) can be used on a page to get at some methods. They do not display in the generated HTML page.
Nonvisual JavaBeans. The rest of the JavaBeans fall into this category. They are typically encapsulations of logic that can be used either on a form or a page.

Creating your own JavaBean

Once you have decided you need a JavaBean, use the SilverStream Business Object Designer to write it. Information about writing JavaBeans is outside the scope of this guide (see Sun Java documentation for more information about JavaBeans). When you save your JavaBean, it resides in the Objects portion of your database.

To enable the JavaBean for use in an application, specify your JavaBean in a Manifest file and include the manifest file along with your JavaBean in a JAR file.

Including your JavaBean in a JAR file

Follow these steps to include your JavaBean in a JAR file.

Choose the EJB JARS & Media icon in the left pane of the SilverStream Designer for the database.
Select Jars from the right panel of the Designer.
Click the New button in the right pane and click Create JAR.
Expand the Objects tree in the left pane of the JAR Designer and select the package contents (denoted by an asterisk) of the JavaBean you want to include in the JAR file.
- Click on Package contents when you want to restrict your selection to the chosen package contents. This avoids including sub-packages along with the chosen package.
- Click on Package and subpackages when you want to include all sub-packages in the hierarchy along with the chosen package.
Double-click the package or press the > button to add the package to the JAR file list. Repeat this step for each component you want to add to the list.
Expand the General directory under EJB JARS & Media in the left pane of the Designer Wizard and select the Manifest file to include in the JAR file. Double-click the manifest file or press the > button to add the file to the JAR file list.
Select File/Save to save the JAR.

SilverStream automatically reads the Manifest file and adds any JavaBeans to the list of available JavaBeans.

Programmer's Guide