Application Assembler's Guide

Target audience

The target audience for this guide is the application assembler. The role of the application assembler is to develop a complete application using existing Enterprise Beans. This includes development of the client application and the eventual development of additional Enterprise Beans.

Assembling server components

The application assembler works with the client's view of the Enterprise Beans (i.e. the Home and Remote interfaces) and does not require any knowledge of their implementation. On the server side, the application assembler may define new Enterprise Beans that make use of the existing ones. Generally, these new Enterprise Beans are session beans, which may be needed for several reasons.

Existing Enterprise Beans expect a certain client behaviour from these session beans. They must be developed as described in the Programmer's Guide. The following section, Developing a client application, explains how to develop the code of the business methods that invoke the existing Enterprise Beans.

Note also that a client application may use several EJB servers, distributed transactions being automatically handled. However, until XA-aware JDBC drivers are available (JDBC 2.0 Standard Extension), it is not possible to perform a two-phase commit on several databases.

Developing a client application

Depending on the architecture of the application, the client part may be

each one communicating with one or several EJB servers via RMI.

A client application invokes methods on EJB Home and Remote objects. There are several ways for a client application to get an EJB object:

  1. The client has the JNDI name of the EJB object. This name is used to get the EJB object.
  2. The client has the JNDI name of the Home object, which is a more usual case. This name is used to get the Home object, then a finder method is invoked on this Home to obtain one or several entity bean objects. The client may also invoke a "create" method on the Home object to create a new EJB object (session or entity).
  3. The client has obtained a handle on an EJB object. A handle is an object that identifies an EJB object; it may be serialized, stored, and later used by a client to obtain a reference to the EJB Object, using the getEJBObject method(). Refer to the section titled "Enterprise Bean's handle" for more details.
  4. The client has obtained a reference to an EJB object, and some of the methods defined on the remote interface of this Enterprise Bean return EJB objects.

In the following example, the different phases of a typical client application will be illustrated by the corresponding code. The example is based on the entity bean sample delivered with the platform.

Get a reference to the Home object, having its JNDI name ("AccountHome1") and the initial JNDI context (initialContext):

AccountHome home = (AccountHome)
                        PortableRemoteObject.narrow(
                                initialContext.lookup("AccountHome1"),
                                AccountHome.class);

Get a reference to the account number 102:

Account a2 = home.findByNumber(102);

On this account EJB object, set the balance attribute to 100.00:

a2.setBalance(100.00);

Create a new account EJB object:

Account a1 = home.create(109, "John Smith", 0);

To start and close a transaction from the client application:

UserTransaction utx = (UserTransaction) initialContext.lookup("javax.transaction.UserTransaction"); 
utx.begin();
...                // code of the transaction
utx.commit();      // or utx.rollback();

Note: Neither the EJB specification nor the Java Transaction API specification specify how to obtain the object utx, implementing the UserTransaction interface on the EJB server from a client application which is not a bean. Therefore, the way it is done in the above example is specific to JOnAS.

The technique for having a Session bean demarcate transaction boundaries is specifically described in the "Transactional Behaviour" section of the Bean Programmer's Guide.



Enterprise Bean's handle and Enterprise Bean Home's handle

The handle mechanism allows a client application to maintain a reference to an EJB object. A handle object can be obtained by calling the getHandle() method on the reference to an EJB object. The main point is that the handle class implements java.io.serializable interface, which means that a handle may be serialized. This allows the client to store the handle or to pass it to another process. The handle may then be deserialized and used to obtain the reference to the EJB object by calling the getEJBObject() method.

Handles on session bean objects are valid until the session bean object exits, i.e. their lifetime is limited to that of the client. Handles on entity bean objects are valid during the complete lifetime of the entity bean object. This means that such handles may be used by different clients and stored for a long time; the handle will still be valid, even if the the EJB server holding the entity bean objects is stopped and restarted.

Using the entity bean object from the example above (a2), the way to obtain a handle on the object is as follows (the handle class is defined in the javax.ejb package):

Handle h = a2.getHandle();

The handle object can then be serialized and stored in a file:

ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream("handlefile"));
out.writeObject(h);
out.close();

Then, a client can read the handle and retrieve the referenced object:

ObjectInputStream in = new ObjectInputStream(new FileInputStream("handlefile"));
Handle h  = (Handle) in.readObject();
Account a = (Account)PortableRemoteObject.narrow(h.getEJBObject(), 
                                                 Account.class);

The EJB Specification permits the client to obtain a handle for the home interface. This allows the client to store a reference to an entity bean's home interface in stable storage. The client code must use the javax.rmi.PortableRemoteObject.narrow(...) method to convert the result of the getEJBHome() method invoked on a handle to the home interface type