Programmer's Guide

Chapter 23 Calling EJBs

This chapter describes how to access an Enterprise JavaBean deployed on a SilverStream server. It includes the following topics:

Supported EJB clients

You can call an EJB deployed on a SilverStream server from any of the sources listed below. (They can call EJBs running on the same or different SilverStream servers.)

SilverStream Java forms (using SilverJRunner)
SilverStream pages
SilverStream's triggered business objects
Java classes running on the server
Servlets
JSPs
Other EJBs running on the server
Standalone (or external) Java applications

Setting up the client environment

Clients that access EJBs must have access to:

The EJB remote EJB JAR

The remote EJB JAR contains the bean's home and remote interfaces and stubs. The deployment process creates this JAR and places it in the Jars subdirectory of the EJB JARs & Media Store directory on the server.

External Java clients and SilverJRunner clients accessing a secure EJB (that is, EJBs whose deployment plan specifies SSL and a set of valid cipher suites), must also have access to:

agrootca.JAR

The agrootca.JAR file contains the Certificate Authorities (CA) that are supported, by default, on the SilverStream server. This file is installed in the SilverStream installation directory under the \lib subdirectory.

If you need to use a CA that is not already in this file, then you must add it to the file and propagate this change to all SilverJRunner and external clients that require this CA. You can modify this file using any tool that allows you to modify the contents of a JAR file (for example, Sun's JAR utility or Winzip).

SilverJRunner clients can locate this file (located in SilverStream\lib); however, you must specify its location for external Java clients using the AGROOTCA system level Java property.

For more information on setting AGROOTCA, see Writing External Java Clients.

To access the remote EJB JAR from a SilverStream client:

From the appropriate SilverStream Designer (Form, Page or Business Object), choose File>Jar File.
From the left pane of the Select Jar Files dialog, open the database containing the EJB remote JAR.
Choose the EJB remote JAR and add it to the right pane, by choosing the > button.
Close the dialog and save the page, form, or business object.

Tips for JSP clients Once your JSP is built and deployed on the SilverStream server, the code that you write to access the EJB is the same as what you write from any other server-side object. The complicated part of using JSPs is compiling them.To get a JSP that includes a reference to an EJB to compile, you must put the EJB's remote JAR the compiler's classpath. (This is described later.) SilverStream recommends that you do not write calls to the bean directly in the JSP. Instead, you can:

Code the calls to EJBs in a JSP JavaBean

(This is the recommended strategy.)
Code the calls to EJBs in a utility class

To access the remote EJB JAR from external Java clients:

Download the remote EJB JAR to your local disk.

You can use the SilverCmd PublishToFile utility, or the Save to Disk menu item (available on the popup menu from the Main Designer).

For more information, see the JAR Designer in the online Tools Guide or the chapter on SilverCmd in the Facilities Guide of the server's Core Help.
Put the location of the JAR on your classpath.

When the contents of the EJB JAR change Changes to the remote EJB JAR are automatically reflected when the EJB JAR is rebuilt and redeployed. For external Java clients, you must also download the updated version of the EJB JAR.

Accessing EJBs

To access an EJB from any client, you need to:

Access the SilverStream server and establish a session. (The session allows SilverStream to authenticate the user of the EJB. If no session were established before calling it, then the EJB would execute as "anonymous".)
Find the EJB (using JNDI) and create an instance.
Use the bean by calling its remote methods.
Close the session.

Accessing the server

How you access the SilverStream server depends on the type and location of your client.

Accessing the server from an external client

If you are calling an EJB from an external client, you must write the code to:

Initialize the SilverStream runtime environment
Connect to the SilverStream server
Establish a server session

For more information on calling Enterprise Javabeans from a standalone Java application, see Writing External Java Clients.

Accessing the server from a SilverStream client

If you are calling an EJB from a SilverStream client that resides on the same server as the EJB, SilverStream automatically establishes and manages the session for the client. (For forms and views, this is the session obtained by calling com.sssw.rt.form.agGeneral.getServerSession().)

If you are calling an EJB that resides on a remote server, you need to write the code that:

Connects to the remote server
Establishes a server session

Connecting to remote servers To explicitly establish a session, you call one of the variants of com.sssw.rt.util.AgRuntime.connect(), for example:

  AgrServerSession mySess = AgRuntime.connect(otherHost);

This is required for both SilverStream Java-based forms and from server-side clients like SilverStream pages, business objects, and other EJBs.

You must also use a full specification to the other server name in the javax.naming.InitialContext.lookup() (as described later).

Connecting to remote servers inside a firewall If you are calling an EJB that resides on a server inside a firewall that filters out HTTP traffic, use the connectRMI() method of the com.sssw.rt.util AgRuntime class instead of the connect(). This method establishes an RMI/IIOP connection to the server instead of an HTTP connection. Once you are connected, you can follow the other procedures to call an EJB.

Finding EJBHomes and instantiating beans

Before you can call any of the EJB's methods, you must:

Find the EJBHome
Instantiate an EJBObject

Finding the EJBHome

To begin, the client application must find the bean's home (or EJBHome) object. All client types can find the EJBHome using the JNDI name under which it was registered at deployment time. EJB clients (EJBs calling other EJBs) can also find the EJBHome using the environment context.

Using the JNDI name To locate a bean using its JDNI name, follow these steps:

Get the server host and port.

  String beanName = "MyBean"; 
  String host = sess.getServerHost();
  int port = sess.getServerPort();
  if (port != -1)
      host += ":" + Integer.toString(port);

Construct the string that contains the information that you need to do a JNDI lookup.
```
  String fullName = "sssw://" + host + "/RMI/" + beanName;
```
When you do the lookup() on a SilverStream server, you supply the SilverStream keyword ("RMI") so the server can locate the correct namespace in which to search.

If you are on the same server, you can use lookup("RMI/beanname"). On a remote server, you use a fully qualified name as shown earlier.
Create an instance of the javax.naming.InitialContext class.
```
  InitialContext ctx = new InitialContext();
```
The InitialContext provides the starting point for any JNDI lookup. Once you have it, you can use it to locate any object registered with JNDI.
Do an InitialContext.lookup() method to return the EJBHome, then call the javax.rmi.PortableRemoteObject.narrow() to perform type-narrowing of the client-side representations of the home and remote interfaces. Cast the returned object to the appropriate type.
```
  HomeI beanHome
     =(HomeI)PortableRemoteObject.narrow(ctx.lookup(fullName),
            HomeI.class);
```
The type-narrowing ensures that your client program will be interoperable with all EJB-compliant containers and is required.

Using the environment context When the client is another EJB, you can find the EJBHome using a bean reference. This is useful when you do not know the JNDI name of the bean that you want to call.

Rules for using EJB bean references Here are the rules for calling EJBs using bean references and the environment context:

The caller must be an EJB.
Both the caller and the called EJBs must reside in the same EJB JAR.
The deployment descriptor includes a bean reference entry.
The name that you use to lookup the bean (using the contextEnv.lookup() method) must exactly match the name of the bean reference in the deployment descriptor.

Steps for finding a bean using a bean reference: Here's how you do a lookup a bean reference using the environment context:

Create an instance of the javax.naming.InitialContext class.
```
  m_initialContext = new javax.naming.InitialContext();
```

Create an instance of the environment context and call the InitialContext.lookup() method.

  Context contextEnv = (Context)
       m_initialContext.lookup("java:comp/env");

Call the environment context lookup using the bean reference.

  Object objEntityBeanLookup = (Object)
      contextEnv.lookup("ejb/beanrefname");

Call the javax.rmi.PortableRemoteObject.narrow() to perform type-narrowing of the client-side representations of the home and remote interfaces. Then cast the returned object to the appropriate type.
```
  m_myBeanHome = (myBeanHome) 
      PortableRemoteObject.narrow(objEntityBeanLookup,
      com.examples.bankdemo.myBeanHome.class); 
```
Call the create() method or a finder method on the resulting EJBHome to get an EJBObject. This example shows how to call
```
  m_myBean = m_myBeanHome.findByPrimaryKey(pkCompany);
```
or
```
  m_myBean = m_myBeanHome.create();
```

For more information and examples that show how to use the environment context and bean references, see the EJB section of the online Application Techniques.

Calling remote methods

Once your client has a remote reference to the EJB, you can call any of the exposed business methods as though the EJB were local. Your client application can call only methods exposed by the remote interface and the lifecycle methods exposed by the home interface. Clients that access entity beans, can also call methods on the primary key class.

The bean provider must provide some type of written documentation that describes the EJB's the available business methods.

Closing the session

By default, SilverStream automatically closes the when the creating session goes away (either when the form or view exits, or when the session that owns the page/business object/EJB is terminated). You can also explicitly close a session using AgrServerSession.close().

Programmer's Guide