Using VisualCafe for SilverStream Development

This page describes SilverStream support for WebGain's VisualCafe Expert Edition, a third-party integrated development environment (IDE) for creating Java applications. SilverStream provides a plug-in to VisualCafe that allows you to develop SilverStream business objects in VisualCafe Expert edition 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.

This page includes the following topics:

Configuring VisualCafe to work with SilverStream

To use the SilverStream plug-in for VisualCafe, you need to install SilverStream's VisualCafe integration software and update your classpath with the appropriate SilverStream JAR and ZIP files.

Installing the VisualCafe integration software

To install the VisualCafe integration software:

Run the SilverStream install program and select the VisualCafe integration option.

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

NOTE You can also install the VisualCafe integration software by selecting Custom Install. To do this, select Café integration in the list of options available for the Integration Packages component.
Specify the VisualCafe installation directory in the Choose Destination Location dialog.

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

Puts SilverCafe.jar in the <VisualCafe installation directory>\bin\components directory.

SilverCafe.jar contains all of the classes required for the VisualCafe integration.
Modifies VisualCafe's sc.ini file to use SilverCafe.jar.
Installs several help files in the <VisualCafe installation directory>\Documentation\SilverStream\books directory.

Updating your classpath

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

To develop additional SilverStream classes--both server and client--in VisualCafe, you may need to add other SilverStream ZIP and JAR files to your classpath to give VisualCafe 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"

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

You can update your classpath either from Windows NT, by modifying the VisualCafe configuration file, or from inside VisualCafe, as described in the following procedures.

To update your classpath from Windows NT:

Add the necessary files to your classpath environment variable in Windows NT System Properties.

Open the VisualCafe configuration file:

  VisualCafe installation directory\bin\sc.ini

Set VCAFE_USEBOOTCLASSPATH = 1.
Restart VisualCafe.

To update your classpath by modifying the VisualCafe configuration file:

Open the VisualCafe configuration file:

  VisualCafe installation directory\bin\sc.ini

Add the necessary files to CLASSPATH.
Restart VisualCafe.

To update your classpath from inside VisualCafe:

Select Tools>Environment Options.
Select the Virtual Machines tab.
Add the necessary files to the Classpath for the Compiler and click OK.

Deploying business objects to SilverStream from VisualCafe

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

There are two categories of business objects that you can create in VisualCafe 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:

To create these objects in VisualCafe, you must implement specific 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. Note that these examples do not include constructor methods. If you choose to add a constructor, you must define a public constructor that takes no arguments.

After meeting these basic requirements, you can add the necessary business logic to write the methods and complete your business object.

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 that 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

cjavax.servlet.*

Interface 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 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

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 VisualCafe:

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

Add the following JAR file to your classpath:

  SilverStream installation directory\lib\ejb.jar

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:

How to deploy business objects from VisualCafe

To deploy business objects to SilverStream from VisualCafe:

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
Start VisualCafe.
Configure your VisualCafe environment appropriately as described in Configuring VisualCafe to work with SilverStream.
Create a new project.
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.
Compile the object and fix any errors that occur.

NOTE If your project contains objects that have compile errors, you will not be able to deploy any object from that project, even an object that compiles cleanly. Either fix the compile errors or remove the offending object(s) from the project.
Specify the target server and database you started up in step 1 by performing these actions:
- Select Options from the Project menu, then select the SilverStream tab.
- Specify the host name for the server in the Server field.
- Specify the target database in the Database field.
- Enter the user name and password defined for the database.
- Click OK.
Start the Business Object Deployer.
- Select the Objects tab in the Project window and right-click the object you wish to deploy.
- Select Deploy to SilverStream from the popup menu.
  
  The SilverStream Environment dialog appears, with fields filled in based on what you entered in the Project Options dialog.
- Change any settings as needed and click OK.
  
  Any changes you make to server and database here are automatically reflected in the Project Options parameters for the SilverStream environment.
  
  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.
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.

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 VisualCafe, you can learn how to access comprehensive SilverStream help by selecting Accessing SilverStream Help from the VisualCafe Help menu.