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   Top of page

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

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 in the online Tools Guide.

Importing a utility object created externally   Top of page

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 SilverCmd Reference in the online Tools Guide.

Using utility classes   Top of page

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.


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 Examples3 databases. If you have these databases running on your machine, see the Objects directories in Examples3_HTML and Examples3_Java.

Utility objects, ClassLoaders, and session management   Top of page

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.

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   Top of page

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 in the online Tools Guide.

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

Using JAR files to enhance performance   Top of page

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    Top of page

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   Top of page

JavaBeans reside in JAR files. To use a third-party JavaBean (a JavaBean created outside of 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:

  1. Make sure the JAR file containing the JavaBean is on a disk that is accessible from the SilverStream Designer.

  2. Choose the EJB, JARS & Media icon in the left pane of the Designer window for the database.

  3. Click on the New button and select Upload JAR, ZIP, or EJB from the drop-down list. The Open File dialog box appears.

  4. 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   Top of page

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, Jar Designer in the online Tools Guide.

Using a JavaBean in your application   Top of page

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:

Creating your own JavaBean   Top of page

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 (refer to JavaSoft 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.

  1. Choose the EJB JARS & Media icon in the left pane of the SilverStream Designer for the database.

  2. Select Jars from the right panel of the Designer.

  3. Click the New button in the right pane and click Create JAR. The JAR Builder wizard appears.

  4. Expand the Object: tree view in the left pane of the Designer Wizard and select the package contents (denoted by an asterisk) of the JavaBean you want to include in the JAR file.

  5. 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.

  6. 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.

  7. Select File/Save to save the JAR.

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

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