Using JBuilder for SilverStream Development

This page describes SilverStream support for Borland's JBuilder Foundation and Enterprise editions, both third-party integrated development environments (IDEs) for creating Java applications. The SilverStream integration with JBuilder allows you to develop Enterprise JavaBeans (EJBs) and business objects in JBuilder and deploy them to the SilverStream Application Server for execution in the SilverStream runtime environment.

A SilverStream business object is a specific type of Java class that resides on a SilverStream server and, in some cases, responds to one or more events (or triggers) produced by the server.

The EJBs and business objects can be created in JBuilder or imported into JBuilder from another external IDE.

JBuilder Enterprise Edition provides a visual development environment for creating EJBs; with the Foundation Edition, you must create your EJB JAR files by hand.

This page includes the following topics:

• Configuring JBuilder to work with SilverStream

• Deploying EJBs to SilverStream from JBuilder

• Deploying business objects to SilverStream from JBuilder

• Accessing SilverStream help

Configuring JBuilder to work with SilverStream   

To use JBuilder with SilverStream, you need to install SilverStream's JBuilder integration software and update your classpath with the appropriate SilverStream JAR and ZIP files.

If you are using JBuilder Enterprise Edition, you must also install the J2EE libraries from the Sun Microsystems Web site as described in JBuilder 3.5 Hints and Tips, which you can access from the JBuilder Help menu.

Installing the JBuilder integration software   

To install the JBuilder integration software:

1. Run the SilverStream install program and select the JBuilder integration option.

   

   The dialog box you see above appears automatically when you select Typical Install as your installation type.

   NOTE   You can also install the JBuilder integration software by selecting Custom Install. To do this, select JBuilder integration in the list of options available for the Integration Packages component.

2. Specify the JBuilder installation directory in the Choose Destination Location dialog.

When you install the JBuilder integration software, the install program performs these steps:

• Modifies the JBuilder.config file to find the root SilverStream installation directory and add SilverDesignerAll.zip to the classpath.

  SilverDesignerAll.zip contains SilverStream classes required by the integration software.

• Puts the following JAR files in the <JBuilder installation directory>\lib\ext directory:
  • SilverJBuilder.jar, which contains all of the classes required for the JBuilder integration.

  • xerces.jar and xml4j.jar, which contain classes that provide support for XML parsing.

• Installs several help files in the <JBuilder installation directory>\doc\SilverStream\books directory.

Updating your classpath   

After you install the JBuilder integration software, you must add SilverServerAll.zip to the classpath for your JBuilder project so that you can build and compile SilverStream EJBs and business objects in JBuilder and then deploy them to run on the SilverStream Application Server.

To develop additional SilverStream classes--both server and client--in JBuilder, you may need to add other SilverStream ZIP and JAR files to your classpath to give JBuilder access to the necessary packages of the SilverStream API.

SilverStream help provides comprehensive information about how to update your classpath for developing specific types of SilverStream applications in external IDEs. Here is the reference:

Book	Programmer's Guide
Major topic	Core Programming
Chapter	Coding Java for SilverStream Applications
Search for	"Setting your classpath"

To update the classpath for your JBuilder project:

1. Open the project that will contain the SilverStream EJBs or business objects you plan to build and deploy.

2. Choose Project>Project properties.

   The Project Properties dialog opens.

   NOTE   To update the classpath for all projects, select Project>Default project properties instead.

3. Select the Paths tab.

4. Select the Required Libraries tab.

5. Click the Add button.

   The Select one or more libraries dialog opens.

6. If you have defined a SilverStream library that contains the appropriate SilverStream API classes, select it and click OK; otherwise, create a new library by following these steps:
   • Click the New button.

     The Edit library dialog opens.

   • Click Add in the Class pane.

   • Browse to SilverServerAll.zip at the following location:

       SilverStream installation directory\lib\SilverServerAll.zip 
     

   • Select SilverServerAll.zip and click OK to return to the Edit library dialog.

   • Enter a name for the library and click OK to dismiss the Edit library dialog.

   • Click OK to dismiss the Select one or more libraries dialog.

7. Click OK to dismiss the Project Properties dialog.

Deploying EJBs to SilverStream from JBuilder   

The SilverStream integration with JBuilder allows you to deploy EJBs created in JBuilder--or imported into JBuilder--to a SilverStream server. The integration software uses the information in the deployment descriptor, along with additional information provided during deployment, to ensure that the beans execute properly in the SilverStream runtime environment.

This section includes the following topics:

• What you can deploy

• About the deployment plan

• What happens when you deploy

• How to deploy EJBs from JBuilder

SilverStream help provides additional information about deploying EJBs in SilverStream. See the chapter on deploying EJBs in the Programmer's Guide.

What you can deploy   

You can deploy any EJB JAR that conforms to the EJB 1.1 specification to SilverStream. The JAR must contain the following components:

• Enterprise JavaBean classes

• Home and remote interfaces for each EJB in the JAR

• A deployment descriptor that uses the EJB 1.1 DTE (ejb-jar_1_1.dtd)

• Any supporting components, such as utility classes and images

You can create the EJB JAR in JBuilder or in another third-party tool.

About the deployment plan   

You specify all additional information required for deployment in a deployment plan. The Deployment Plan Designer provides a simple user interface for specifying the deployment plan. The deployment plan is stored in XML format in a file on disk. It is not uploaded to the server.

Required information for deployment

The information required for the deployment plan varies depending on what's in the EJB JAR.

For all EJB deployments

You must:

• Enable or disable the deployed object

• Map roles to security principals

For each EJB contained in the EJB JAR

You must:

• Specify a JNDI name

For container-managed entity beans

You must:

• Map each entity bean to a data source (such as a database table)

• Map each entity bean's persistent fields to database columns

• Specify finder methods

• Specify whether to delay instantiation of the EJB

You can deploy the same EJB JAR multiple times with different deployment plans.

    For complete details about specifying this information in the Deployment Plan Designer, see Deploying EJBs.

What happens when you deploy   

When you deploy EJBs to a SilverStream server, SilverStream creates the runtime classes that implement the bean's home and remote interfaces, and any other environment-specific classes that the container needs to run the bean(s) supplied in the EJB JAR.

At deployment time, the SilverStream server constructs a deployed object and a remote EJB JAR in the SilverStream database. The original EJB JAR is not actually deployed; it just provides the raw materials for the construction of the deployed object and remote JAR.

The deployed object includes the implementation classes for the bean's remote and home interfaces. It is used only by the SilverStream server.

The remote JAR file includes stub or reference classes that you can use to call the server-side implementation classes. All clients should use the remote JAR. This includes SilverStream clients within the same server, forms served to JRunner by the same server, SilverStream clients within another SilverStream server, and standalone Java programs. You need to include this remote JAR in SilverStream forms, pages, and business objects. You need to add this JAR to your path if you are accessing EJBs from an external client.

For convenience, the remote JAR also includes each bean's home and remote interface and any classes directly referenced by them. For example, it includes any classes referenced as parameters or return values. In general, the remote JAR includes any of the classes a caller needs to use the bean.

How to deploy EJBs from JBuilder   

To deploy EJBs to SilverStream from JBuilder:

1. Start the SilverStream Application Server and add the database where you want to deploy your EJB.

   For instructions, see the following in SilverStream help:

   • Chapter on running the server in the Administrator's Guide

   • Section on adding a database to use with SilverStream in the chapter on the Main Designer in the Tools Guide

2. Start JBuilder.

3. Create a new JBuilder project.

4. As part of the project, create your EJB components, compile them, and package them in an EJB JAR.

5. Save the EJB JAR to a file on disk.

6. Specify the target server and database you started up in step 1.
   • Select Tools>SilverStream Setup.

     The SilverStream Server and Database Setup dialog appears.

     

   • Specify the host name for the server in the Server Name field.

   • Specify the target database in the Database Name field.

   • Click OK.

7. Start the Deployment Plan Designer.
   • Select File>New.

   • Select SilverStream EJB Deployment Plan from the Object Gallery.

     The SilverStream EJB Deployment Plan Wizard appears.

     

   • In the Plan Name field, specify the path to an XML file that will contain the deployment plan.

   • In the EJB JAR File field, enter the path for the EJB JAR file you wish to deploy or click the Browse button to navigate to the file and select it.

   • Click OK.

     The Deployment Plan Designer opens in the JBuilder Content pane, incorporating the deployment information specified in the EJB JAR.

     You can select two views of your deployment plan using the tabs at the bottom of the Content pane:

   • Design view, which displays the content using a GUI interface. This is the default view.

     

   • Source view, which displays the content in XML format.

     

8. In either view, edit the deployment plan as needed to specify additional details.

   Before you can deploy your EJB, you must specify certain information depending on what's in your EJB JAR, as described in Required information for deployment.

9. After specifying the required information, click the Deploy to SilverStream Server button.

   NOTE   This button is only available in Design view.

   The deployed object and the remote JAR are uploaded to the designated server. In the SilverStream Designer, you can see the deployed object and the remote JAR in the Jars folder under EJB JARs & Media.

    For complete details about using the Deployment Plan Designer, see Deploying EJBs.

Deploying business objects to SilverStream from JBuilder   

SilverStream provides an API for developing business objects that run on a SilverStream server. This section describes how to create and deploy these objects. It includes the following topics:

• About business objects

• Creating triggered business objects

• Creating utility objects

• Accessing data from your business object

• How to deploy business objects from JBuilder

About business objects   

There are two categories of business objects that you can create in JBuilder using the SilverStream API and then deploy to a SilverStream server:

• Triggered business objects: Java classes that run on a SilverStream Server and respond to a specific set of server-produced events, or triggers.

• Utility objects: General-purpose Java classes that run on a SilverStream server, but are not triggered by server-produced events.

Creating triggered business objects   

SilverStream supports different types of business objects, each of which is activated by a unique trigger event on the server:

• Scheduled

• Mail

• Table-modified

• Server events

• Invoked

• Data source

• Servlet (HTTP request)

• Cluster events

To create these objects in JBuilder, you must implement specific listener interfaces from the SilverStream API--or in the case of servlet business objects, the standard javax.servlet.Servlet interface. A single business object class definition can implement more than one of these interfaces.

This section describes the requirements for creating each type of triggered business object. Each section also contains an example of how the Java source file should look with the minimal required set of import statements, interfaces, and method stubs. After meeting these basic requirements, you can add the necessary business logic to write the methods and complete your business object.

Here is a procedure to use for setting up the class file for triggered business objects using the SilverStream API:

To set up the class file in JBuilder for triggered objects:

1. Select New Class from the File menu.

   The Class Wizard opens.

2. Enter a package name and class name.

3. Select the ellipsis next to the Base class combo box.

   The Select a base class dialog opens.

4. Navigate to com.sssw.srv.busobj in the class list. For servlet business objects, navigate to javax.servlet.Servlet.

5. Select the appropriate interface and click OK.

   The interface is entered as the base class. The interfaces required for each type of triggered business object are described in the next sections.

6. Leave other settings at their defaults in the Class Wizard and click OK.

   The class file is created, including the proper import statements, listener interface, and method stubs.

Scheduled business object

This object is scheduled to run at a certain time. You can specify particular time intervals or dates for triggering this object.

Packages to import

com.sssw.srv.busobj.*

Interface to implement

AgiScheduledListener

Methods to define

public void scheduleReached (AgoScheduledEvent evt)

Example

Here is the minimal code required for compiling a scheduled business object class:

For more information

To learn more about scheduled business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using server, cluster, and scheduled business objects in the Programmer's Guide

Mail business object

This object is triggered when the application server is notified of the receipt of Post Office Protocol 3 (POP3) mail for a particular mailbox address. Before you can run a mail business object, you must configure the SilverStream Server to poll for e-mail in one or more mail accounts from one or more POP3 servers.

Packages to import

com.sssw.srv.busobj.*

Interface to implement

AgiMailListener

Methods to define

• public void afterMailReceived(AgoMailEvent evt)

• public void beforeMailReceived(AgoMailEvent evt)

• public void mailReceived(AgoMailEvent evt)

Example

Here is the minimal code required for compiling a mail business object class:

For more information

To learn more about mail business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using mail business objects in the Programmer's Guide

• Section that describes setting up mail on the server in the chapter on maintaining the server in the Administrator's Guide.

Table-modified business object

This object is triggered by modifications to a database table, such as updating, inserting, or deleting rows. To run on the SilverStream server, your table-modified business object must meet the following requirements:

• The object must be associated with a single database table.

• You must trigger the object by updating data through AgaData, SilverStream's data cache object which binds a data set to a triggered business object.

  Table-modified business objects do not respond to changes in database structure or to data modified by external database applications.

Packages to import

com.sssw.srv.busobj.*

Interface to implement

AgiTableListener

Methods to define

• public void aborted(AgoTransactionAbortEvent evt)

• public void afterTableChange(AgoTableEvent evt)

• public void beforeTableChange(AgoTableEvent evt)

• public void rowDeleted(AgoRowDeleteEvent evt)

• public void rowInserted(AgoRowInsertEvent evt)

• public void rowModified(AgoRowModifyEvent evt

Example

Here is the minimal code required for compiling a table-modified business object class:

For more information

To learn more about table-modified business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using table-modified business objects in the Programmer's Guide

Server events business object

This object is triggered by server-wide events such as starting and stopping the server, issuing server errors, and user login and logout.

Packages to import

com.sssw.srv.busobj.*

Interface to implement

AgiServerListener

Methods to define

• public boolean httpError(AgoHttpErrorEvent evt)

• public void serverDeactivated(AgoServerDeactivatedEvent evt)

• public void serverDeactivating(AgoServerDeactivatingEvent evt)

• public void serverError(AgoServerErrorEvent evt)

• public void serverStarted(AgoServerStartEvent evt)

• public void serverStopped(AgoServerStopEvent evt)

• public boolean userLogin(AgoUserLoginEvent evt)

• public void userLogout(AgoUserLogoutEvent evt)

Example

Here is the minimal code required for compiling a server events business object class:

For more information

To learn more about server events business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using server, cluster, and scheduled business objects in the Programmer's Guide

Invoked business object

This object is triggered by calls to the SilverStream method invokeBusinessObject() from an object on the server.

Packages to import

com.sssw.srv.busobj.*

Interface to implement

AgiInvokedListener

Methods to define

public void invoked(AgoInvokedEvent evt)

Example

Here is the minimal code required for compiling an invoked business object class:

For more information

To learn more about invoked business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using invoked business objects in the Programmer's Guide

• Chapter on triggered business object techniques in Application Techniques

Data source business object

In the SilverStream data access model, the role of the data source object is to connect a data cache object AgaData to a data provider, which in turn connects to an external data source. This model allows Java client applications to access raw data from an external source by interacting with the data cache object and its methods.

The data source object is triggered when a client calls its invokeQuery() method, which you must program to connect the data provider to the data cache, as described in Accessing data from your business object.

    For more information about the SilverStream data model, see the following in SilverStream help:

• Chapter on data access basics in the Programmer's Guide

• Chapter on using data source business objects in the Programmer's Guide

Packages to import

com.sssw.srv.busobj.*

Interface to implement

AgiDataSourceListener

Methods to define

public void invokeQuery(AgoDataSourceEvent evt)

Example

Here is the minimal code required for compiling a data source business object class:

Beyond this basic code, you must add programming logic to the invokeQuery() method to connect a data provider to the client's data cache, as described in Accessing data from your business object.

For more information

To learn more about data source business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using data source business objects in the Programmer's Guide

• Chapter on data access techniques in Application Techniques

Servlet business object

This object is triggered when a SilverStream application performs an operation on an URL that has been associated with the servlet. These operations can include requesting, updating, and removing an URL.

Packages to import

javax.servlet.*

Interfaces to implement

• javax.servlet.Servlet

• javax.servlet.SingleThreadModel

Methods to define

• public void service(javax.servlet.ServletRequest req, javax.servlet.ServletResponse res) throws javax.servlet.ServletException, java.io.IOException

• public void init(javax.servlet.ServletConfig config) throws javax.servlet.ServletException

• public String getServletInfo()

• public javax.servlet.ServletConfig getServletConfig()

• public void destroy()

Example

Here is the minimal code required for compiling a servlet business object class:

NOTE   getServletConfig() must return a javax.servlet.ServletConfig object--in this case, ag_servletConfig, declared as a private javax.servlet.ServletConfig object.

For more information

To learn more about servlet business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using servlet business objects in the Programmer's Guide

• Chapter on triggered business object techniques in Application Techniques

Cluster events business object

This object is triggered by cluster events, such as when a SilverStream server in a cluster starts up, stops, or can no longer be reached by the Cache Manager.

Packages to import

com.sssw.srv.busobj.*

Interface to implement

• AgiClusterListener

Methods to define

• public void clusterServerStarted(AgoClusterServerStartEvent evt)

• public void clusterServerStopped(AgoClusterServerStopEvent evt)

Example

Here is the minimal code required for compiling a cluster events business object class:

For more information

To learn more about cluster events business objects, see the following in SilverStream help:

• Chapter on triggered object basics in the Programmer's Guide

• Chapter on using server, cluster, and scheduled business objects in the Programmer's Guide

Creating utility objects   

SilverStream utility classes are used to encapsulate general-purpose Java code on the server, such as for providing a financial calculation that is shared by multiple business applications.

You develop SilverStream utility classes like any standard Java class except for the following restrictions:

• Utility classes do not support inner classes.

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

If your utility object uses custom classes, you must add the associated ZIP and JAR files to your classpath. Depending on what type of utility object you develop, you might also need to include additional SilverStream ZIP and JAR files to your classpath. For more information, see Updating your classpath.

In the SilverStream runtime environment, you can use utility classes with any code running on the server--such as business objects--as long as they reside in the same database.

For more information about creating utility classes, see the following in the SilverStream help:

• Chapter on using utility classes, JAR files, and JavaBeans in the Programmer's Guide

• Section on using utility-class methods in Application Techniques

Accessing data from your business object   

When you create a data source object (DSO), you must program its invokeQuery() method to perform the following functions:

• Create the data provider

• Initialize the data provider

• Connect the data provider to the client's data cache

SilverStream provides utility objects to help you produce commonly used data providers:

Utility object	Data provider
ExecuteSQL DSO	Returns results of SQL queries
SetResultSet DSO	Obtains its data from a java.sql.ResultSet
Pass-through DSO	Dynamically connects data cache of non-SilverStream client to standard SilverStream data set at runtime

The next section provides an example of a pass-through DSO.

    For more information about creating and using each of these DSOs, see the following in SilverStream help:

• Chapter on using data source business objects in the Programmer's Guide

• Section on data access techniques in Application Techniques

Example: Pass-through data source object

The pass-through DSO helps you create a data provider commonly required by clients developed in third-party IDEs--a provider that connects the data cache of a non-SilverStream client to a SilverStream data set.

To create a pass-through DSO in JBuilder:

1. Create a class that meets the requirements for a data source business object, as described in Data source business object.

2. Program the invokeQuery() method to:
   • Define one or more AgaData data cache objects. For example:

       AgaData db = evt.getAgaData("db"); 
     

   • Define the data set for each AgaData object you create. For example:

       db.initialize("db", evt.getDatabase()); 
     

   • Allow the data source object to return one of its own AgaData objects as its data source. For example:

       evt.setDataSource(db.detachDataSource()); 
     

Here is what the code looks like for this example:

    For more information, see the chapter on using data source business objects in the Programmer's Guide in SilverStream help.

How to deploy business objects from JBuilder   

To deploy business objects to SilverStream from JBuilder:

1. Start the SilverStream Application Server and add the database where you want to deploy your business object.

   For instructions, see the following in SilverStream help:

   • Chapter on running the server in the Administrator's Guide

   • Section on adding a database to use with SilverStream in the chapter on the main designer in the Tools Guide

2. Start JBuilder.

3. Configure your JBuilder environment appropriately as described in Configuring JBuilder to work with SilverStream.

4. Create a new project.

5. As part of the project, create your triggered business object or utility object, according to the guidelines in Creating triggered business objects and Creating utility objects.

6. Compile the object and fix any errors.

7. Specify the target server and database you started up in step 1 by performing these actions:
   • Select Tools>SilverStream Setup.

     The SilverStream Server and Database Setup dialog appears.

     

   • Specify the host name for the server in the Server Name field.

   • Specify the target database in the Database Name field.

   • Click OK.

8. Start the Business Object Deployer.
   • Select Deploy Business Object from the Tools menu.

     The SilverStream Business Object Deployment dialog appears, with fields filled in based on what you entered in the Server and Database Setup dialog.

     

   • In the Object Selection pane, enter the path to the class file of the object you wish to deploy.

     You can browse the file hierarchy by selecting the Choose object to deploy button.

   • In the Object Destination pane, change any settings as needed and click OK.

     Any changes you make to server and database here are automatically reflected in the setup parameters.

     If the destination is protected, you must enter a user name and password.

     The Business Object Deployer dialog appears.

     

     One or more trigger check boxes are selected, based on the interfaces implemented by your business object. In this example, the object is a Data Source Business Object that implements only the AgiDataSourceListener interface. Note that you must specify additional deployment information for each object type--in this case, whether the object is a pass-through data source object. For utility objects, no triggers are checked.

9. In the Business Object Deployer, enter additional deployment information as necessary and click OK.

   The object is uploaded to the designated server. In the SilverStream Designer, you can see the deployed business object under Objects in a folder that bears the same name as the package you specified for the object. By default, JBuilder specifies a package name that is the same as the project name.

   NOTE   If you deploy an object with the same name as one that already exists in the same location on the server, the new object overwrites the existing object.

   For complete details about using the Business Object Deployer, see Deploying Business Objects.

Accessing SilverStream help   

If you are working in JBuilder, you can learn how to access comprehensive SilverStream help by selecting Accessing SilverStream Help from the JBuilder Help menu.