This chapter is an overview of how to use Java classes, JAR files, and JavaBeans in the SilverStream environment. It contains the following sections:
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.
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.
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.
Multi-threading
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.
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.
NOTE The session object can be returned using evt.getSession() or any session-persistent storage, such as serialization to the file system.
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.
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:
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.
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.
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:
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.
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:
NOTE You can drop only Page JavaBeans on a page. The JavaBean must be a designed specifically to run on a SilverStream 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.
Follow these steps to include your JavaBean in a JAR file.
SilverStream automatically reads the Manifest file and adds any JavaBeans to the list of available JavaBeans.