This chapter describes how to code external Java clients (outside of the SilverStream development environment) to access a SilverStream server and use the objects, data, and services it provides. You'll learn about:
To learn about configuring your external Java development environment to build this kind of client, see
Coding Java for SilverStream Applications.
To design an external Java client, you need to know what's supported and what's required when accessing a SilverStream server.
The following sections outline the kinds of clients you can build, including the basic features a client can or must implement. You'll find the details on these topics later in the chapter.
Your external Java client can be:
To learn about using EJBs as SilverStream Server clients, see
Calling EJBs.
Your external Java client must:
To perform the initialize and connect operations, you'll use the SilverStream API in your Java client source code.
For an overview of the SilverStream API, see
Coding Java for SilverStream Applications.
Your external Java client can access a single SilverStream server or several at a time. It can also access server clusters.
Once connected to a server, your client can use the SilverStream and Java APIs to:
You can implement one or more of these features in any external Java client you code.
When connecting to a SilverStream server, your client determines the communication protocol to be used for that entire session. The choices are:
Which protocol you use will probably depend on several factors, including the architecture of your application and network, the policies and standards of your organization, and certain restrictions that apply to RMI-IIOP.
An external Java client that uses RMI-IIOP to communicate with a SilverStream server cannot:
To access a SilverStream server from any external Java client, write the client code to:
To see some complete client classes that perform all of these steps, go to Application Techniques>Java Client Techniques in the help system: External Java clients.
By default, the SilverStream runtime environment automatically gets initialized on the client machine when required. But you can optionally control this initialization yourself by calling the init() method of the com.sssw.rt.util.AgRuntime class.
The init() method enables you to specify a login handler object to use if the SilverStream server you're accessing requires user authentication. When your client tries to connect, the server will call back this object to obtain a username and password.
To get a login handler object to use:
AgiUserLogin has one method: prompt(). You must code it to obtain the username and password, then return those values to the server (in an instance of the AgoUserLoginInfo class from com.sssw.rt.util).
init() method.
For example, here's how you'd code init() to use a login handler class named LoginHandler:
AgRuntime.init(new LoginHandler());
To see some examples of login handler classes, go to Application Techniques>Java Client Techniques in the help system: Handling User Authentication from External Java Clients.
If the client you're developing is an applet, call the initFromApplet() method of the AgRuntime class to initialize the SilverStream runtime environment on the client machine.
Call one of these methods of the com.sssw.rt.util.AgRuntime class:
Connects to a SilverStream server, using HTTP as the communication protocol | |
Connects to a SilverStream server, using RMI-IIOP as the communication protocol |
For example, you could connect via HTTP to the SilverStream server on the host machine named myserver :
AgrServerSession session;
session = AgRuntime.connect("myserver");
or you could connect via RMI-IIOP:
AgrServerSession session;
session = AgRuntime.connectRMI("myserver");
The AgRuntime class provides several variations of the connect() and connectRMI() methods. They all establish a session on the specified server and return a session object (an instance of the com.sssw.rt.util.AgrServerSession class) for your client code to work with. (If a session is already established, they return the existing session object.)
For guidance on choosing HTTP or RMI-IIOP for your connection, see
Communication protocols.
Login alternative for RMI-IIOP connections
One variation of the connectRMI() method lets you specify a username and password for logging into a SilverStream server. This is useful for server-to-server connections where login handler callbacks aren't supported.
The AgrServerSession object returned to your client automatically starts a heartbeat to keep the session from timing out. It's simply a periodic communication that tells the SilverStream server your client is still there.
Because of this heartbeat, you must explicitly close the session when your client is done with it.
For details, see
Closing your server session.
To connect your client to a server cluster, you still use the connect() or connectRMI() method of the AgRuntime class. The difference is that you specify the host name of the cluster's dispatcher.
AgrServerSession session;
session = AgRuntime.connect("mydispatcher");
Once connected, you can call the getServerHostName() method of the AgrServerSession object to obtain the host name of the actual SilverStream server.
RMI-IIOP restriction for cluster access
If you call the connectRMI() method to establish an RMI-IIOP connection to a cluster, you must be using the SilverStream dispatcher. Third-party dispatchers are not supported in this situation.
For more information on clusters and dispatchers, see the chapter on administering a cluster in the Administrator's Guide.
Once your client is connected to a SilverStream server, it can use the objects, data, and services of that server (security permitting). This includes calling methods of the AgrServerSession object to:
More importantly, your client can:
To learn how, see
Developing the features for your client.
When your client is done accessing the SilverStream server, it should explicitly close the server session. To do that, call the close() method of the AgrServerSession object.
session.close();
It's best to code close() where you're certain it will execute (such as in the finally block of a try/catch/finally statement). Remember that a session won't time out automatically (because of the heartbeat feature of the AgrServerSession object).
For more information, see
Starting the client heartbeat.
To this point, you've learned mostly about the mechanics of connecting your external Java client to a SilverStream server. Now it's time to use the capabilities of that server to do some real application work. Possibilities include:
An external Java client can retrieve and update rows of data from a data source object (DSO) on a SilverStream server. To implement this access, you use the com.sssw.rt.util.AgrData class in your client to represent the cache of rows to work with.
To see some complete client classes that perform all of these steps, go to Application Techniques>Java Client Techniques in the help system:
To learn about the various kinds of DSOs and how to create them, see
Using Data Source Business Objects.
NOTE DSO access requires an HTTP connection to your SilverStream server (RMI-IIOP does not support it). For more information on connections, see Connecting to a SilverStream server.
To set up your client's row cache and enable it to access the appropriate DSO:
AgrData appdata = new AgrData();
init() method of the AgrData object to initialize it with the appropriate SilverStream server session (AgrServerSession object).
appdata.init(session);
setDataSource() method of the AgrData object to specify the location and name (database:package.object) of the DSO to access.
appdata.setDataSource("mydb:com.myorg.data.dsoMyData");
invokeQuery() method of the AgrData object to start accessing that DSO.
appdata.invokeQuery(null);
Now the row cache (AgrData object) is ready to work with rows from the DSO.
You can use the query and data navigation methods of the AgrData object to:
appdata.query(null);
appdata.gotoFirst();
appdata.getProperty("mycolumn");
For more information on using these kinds of AgrData methods, see
Data Access Basics.
You can use the data manipulation and update methods of the AgrData object to:
appdata.setProperty("mycolumn",newvalue);
appdata.updateRows();
For more information on using these kinds of AgrData methods, see
Data Access Basics.
You can access the rows of your client's cache in controls (such as JTables) that use a table model. To do that, use the com.sssw.rt.util.AgoRowCursorTableModel class (which is based on javax.swing.table.AbstractTableModel):
AgoRowCursorTableModel agmodel; agmodel = new AgoRowCursorTableModel(appdata);
JTable table = new JTable(agmodel);
AgoRowCursorTableModel supports both retrieval and update of rows from the control.
An external Java client can call Enterprise JavaBeans (EJBs) that have been deployed on a SilverStream server. This involves:
To see a complete client class that performs these steps, go to Application Techniques>Java Client Techniques in the help system: Calling EJB Session Beans from External Java Clients.
To learn about the various kinds of Enterprise JavaBeans and how to create them, see
Using EJBs with SilverStream Applications.
Before compiling a client that uses EJBs, make sure that:
To learn how to get the remote JAR file for a bean, see
Calling EJBs.
To learn about other (general) setup requirements for your external Java development environment, see
Coding Java for SilverStream Applications.
Before your client can call any methods of an EJB, it must gain access to that bean on the appropriate SilverStream server. To do this, connect to that server (as described earlier in the chapter), then perform these steps:
getServerHostName() and getServerPort() methods of the AgrServerSession object.
String servername = session.getServerHostName();
int portnum = session.getServerPort();
if (portnum != -1) {
servername += ":" + Integer.toString(portnum);
}
String jndiname = "MyBean";
InitialContext context = new InitialContext();
and by calling the lookup() method of the InitialContext object to return the bean's home interface as an Object.
Object sbobj = context.lookup("sssw://" +
servername +
"/RMI/" +
jndiname);
Note that a couple parts of the address (sssw://.../RMI/...) are the same for any EJB deployed on a SilverStream server.
narrow() method of the javax.rmi.PortableRemoteObject class to check that the Object returned by the lookup can be cast to the appropriate type (the class of the bean's home interface)
sbobj = PortableRemoteObject.narrow(sbobj,
MyBeanHome.class);
then cast the Object to that class.
MyBeanHome sbhome = (MyBeanHome)sbobj;
create() method or a finder method of the resulting home object to get an instance of the bean's remote interface.
MyBeanRemote sbremote = sbhome.create();
Your client now has the remote object for the bean and is ready to use it.
Once your client has a bean's remote object, it can call the business methods of that bean (specifically, the methods exposed by the bean's remote interface). For example:
result = sbremote.getTotal();
It can also call any other lifecycle methods of the bean's home interface that it needs to.
An external Java client can invoke triggered business objects on a SilverStream server. This involves:
String bo = "mydb:com.myorg.busobj.boMyBusinessObject";
This business object must have an invoked trigger defined along with an invoked event handler.
invokeBusinessObject() method of the AgrServerSession object to perform the processing defined by that business object (in its invoked event handler)
Object result; result = session.invokeBusinessObject(bo);
The result returned from the business object by the invokeBusinessObject() method can be any Serializable object. (There's also a variation of this method that passes a Serializable object to the business object.)
To see a complete client class that performs these steps, go to Application Techniques>Java Client Techniques in the help system: Invoking Business Objects from External Java Clients.
To learn about creating triggered business objects you can invoke, see
Using Invoked Business Objects.
An external Java client can perform administrative operations on a SilverStream server. This involves using the Server Administration API (the administration portion of the SilverStream API) to:
getServer() method of the com.sssw.rts.adminclient.AgAdmin class, passing the AgrServerSession object as an argument
AgiAdmServer admserver = AgAdmin.getServer(session);
This method returns an object that implements the com.sssw.rts.adminapi.AgiAdmServer interface, representing the server for the purpose of administration.
For example
// Get a reference to the directory of users in the Silver
// Security realm
AgiAdmDirectory userdir;
userdir = (AgiAdmDirectory)admserver.getElement(
AgiAdmDirectory.SILVERUSERS,
AgiAdmDirectory.SILVERUSERS,
null);
// Get a sorted list of the users in that directory
Enumeration users;
users = userdir.getChildren(
AgiAdmContainer.GET_CHILDREN_SORTED);
.
.
.
To see a complete client class that performs these steps, go to Application Techniques>Java Client Techniques in the help system: Administering the Server from External Java Clients.
To learn more about the administrative operations you can perform on a SilverStream server, see the chapter on using the Server Administration API in the Administrator's Guide.
NOTE Use of the Server Administration API requires an HTTP connection to your SilverStream server (RMI-IIOP does not support it). For more information on connections, see Connecting to a SilverStream server.
Once your external Java client is compiled and tested, you can deploy it to user machines. Deployment involves setting up each user machine to access all the files needed to run the client successfully. This includes:
Instructions for installing the runtime environment depend on the platform you're using (Windows, UNIX, or Linux).
In Windows, each user machine must have appropriate versions of the following runtime components:
To install these, use the SilverStream installation (Setup) program.
For details, see the chapter about installing SilverStream on Windows in the Installation Guide.
Coexisting with another runtime environment
Sometimes user machines may already have another JRE that you want to keep as the default instead of the one provided by SilverStream. In that case, follow these steps rather than using the SilverStream installation program:
jre directory from the SilverStream CD into that new directory.
PATH=c:\SilverStream35\jre\bin;c:\Program Files\ JavaSoft\JRE\1.2\bin;c:\WINNT\system32;c:\WINNT
External Java clients that run in this context will be able to access SilverStream servers and their objects (including EJBs). Clients running outside of this context will continue to use whatever JRE they did previously.
In UNIX or Linux, each user machine must have appropriate versions of the following runtime components:
To install these on a supported UNIX or Linux platform:
cd /export/home/sam/SilverApps
/cdrom mount point) and enter this command:
zcat /cdrom/SilverStream/jre.tar.Z | tar xvf -
This creates jre and jbroker subdirectories in your current directory and copies the appropriate files into them.
For detailed information about UNIX or Linux platform support, see the SilverStream Release Notes.
Provide each user machine access to the files you've developed for your client, including:
For EJB clients
If your client calls Enterprise JavaBeans, you must also provide:
To learn how to get the remote JAR file for a bean, see
Calling EJBs.
Each user machine must have access to several ZIP and JAR files from SilverStream that contain:
The recommended way to get these files is to copy them from a development machine that has the SilverStream Server installed. The next sections list the names of the files you need.
For instructions on installing the SilverStream Server, see the Installation Guide.
The following table shows which SilverStream ZIP and JAR files to install, depending on the kinds of client classes you're deploying.
Any client classes that will use SSL (Secure Socket Layer) to access the domestic (U.S.) version of the SilverStream Server | ||
Any client classes that will administer the SilverStream Server |
This table shows the other supporting (Java and third-party) ZIP and JAR files to install. It's recommended that you always provide all of these.
Once you've installed the required files, you need to make sure the Java runtime environment can find them. You can do that by setting the classpath to list these files (such as with the CLASSPATH environment variable).
The classpath on each user machine should include: