Programmer's Guide

Chapter 24   Calling EJBs

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

Supported EJB clients   Top of page

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.)

Setting up the client environment   Top of page

All clients that need access to an EJB must have access to the remote EJB JAR that contains the bean's home and remote interfaces and stubs. (The remote EJB JAR is created during deployment of an EJB JAR.)

To access the remote EJB JAR from a SilverStream client:

  1. From the appropriate SilverStream Designer (Form, Page or Business Object), choose File>Jar File...

  2. From the left pane of the Select Jar Files dialog, open the database containing the EJB remote JAR.

  3. Choose the EJB remote JAR and add it to the right pane, by choosing the > button.

  4. 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:

To access the remote EJB JAR from external Java clients:

  1. 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 chapter on SilverCmd or the JAR Designer in the online Tools Guide.

  2. 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   Top of page

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

  1. 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'.)

  2. Find the EJB (using JNDI) and create an instance.

  3. Use the bean by calling its remote methods.

  4. Close the session.

Accessing the server   Top of page

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:

    For more information on calling Enterprise Javabeans from a stand-alone 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:

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   Top of page

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

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:

  1. Get the server host and port.

      String beanName = "MyBean";  
    String host = sess.getServerHost();
    int port = sess.getServerPort();
    if (port != -1)
        host += ":" + Integer.toString(port);
  2. 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.

  3. 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.

  4. 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 

    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:

Steps for finding a bean using a bean reference:

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

  1. Create an instance of the javax.naming.InitialContext class.

      m_initialContext = new javax.naming.InitialContext(); 
  2. Create an instance of the environment context and call the InitialContext.lookup() method.

      Context contextEnv = (Context) 
  3. Call the environment context lookup using the bean reference.

      Object objEntityBeanLookup = (Object) 
  4. 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)  
  5. 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); 


      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   Top of page

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   Top of page

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().

Copyright © 2000, SilverStream Software, Inc. All rights reserved.