Managing the session object

An instance of WebSphere Access EJB handles the connection to ICS as well as the initiation of a collaboration within ICS. A client component can manage this EJB instance through the methods of the Access EJB home interface, shown in Table 10.

Table 10. Methods in the EJBHome interface

EJBHome method Description


create()
Creates a session object for WebSphere Access EJB, which obtains an instance of WebSphere Access EJB


getEJBMetaData()
Obtains an instance of the EJBMetaData class, with which a client component can obtain metadata. For more information, see "Obtaining session metadata".


remove()
Removes a session object for WebSphere Access EJB

The interfaces in Table 10 provide the following session-management tasks:

Creating a session object

To create a session object for a WebSphere Access EJB, the client component must obtain an EJBObject instance, which represents an instance of Access EJB. The client component is responsible for requesting that an Access EJB instance be created or removed. However, the EJB container within the application server determines when such activities actually occur. The container creates a pool of Access EJB instances. Because Access EJB is a stateless session bean, all its instances are equivalent. Therefore, the container can delegate the client request to any available instance.

To acquire an instance of WebSphere Access EJB, the client component takes the following steps:

  1. Look up the home interface for a WebSphere Access EJB from the Java Naming and Directory Interface (JNDI).

    When the Access EJB is deployed, the EJB container registers its home interface in the JNDI. The JNDI name for the Access EJB is defined within the application server. This JNDI lookup returns a reference to an EJBHome instance.

  2. Perform type-narrowing of the returned JNDI reference returned from step 1 with the narrow() method of the Java Remote Method Invocation (RMI).

    The Enterprise JavaBeans specification 1.1 recommends the following with respect to type-narrowing:

    "A client component that is intended to be interoperable with all compliant EJB Container implementations must use the javax.rmi.PortableRemoteObject.narrow(...) method to perform type-narrowing of the client-side representations of the home and remote interfaces."

  3. Create a session object for the Access EJB with the EJBHome.create() method.

    The home interface provides a single create() method to create an instance of a Access EJB. This method takes no arguments and returns the EJBObject instance for Access EJB.

The following code fragment shows a client component creating a session object for an Access EJB:

InitialContext ic = getInitialContext();
 
// Look up the home interface for WebSphere Access EJB 
Object ref = context.lookup(
   "com/crossworlds/access/business/cwsample/CwSample");
CwSampleHome cwHome = (CwSampleHome) 
   javax.rmi.PortableRemoteObject.narrow(ref, CwSampleHome.class);
 
// Create a session object
CwSample sample = cwHome.create();
 
// code to request execution of the collaboration goes here
.....
 
// Remove the session
cwHome.remove();

When the client component requests a new session object, the application server checks its pool for an available Access EJB instance. If a session object already exists in one of the application server's pools that can satisfy the session request, the create() method returns a handle to that session. Otherwise, the method requests the creation of a new session object of an Access EJB. If one does not exist, the EJB container obtains a new one with the following steps:

  1. Call the newInstance() method to create the actual instance of an Access EJB.
  2. Call the setSessionContext() method to pass the context object to the Access EJB instance.
  3. Call the ejbCreate() method that corresponds to the create() method that the client component specified.

Note:
If the EJB container cannot create a new Access EJB instance, it throws an appropriate RemoteException exception to notify the client component.

Removing the session object

The EJB package provides two ways in which the client component can remove a session object, as follows:

Important:
Because WebSphere Access EJB is a session bean, you cannot invoke the remove(Object primaryKey) form of the EJBHome.remove() method. An attempt to do so results in the generation of a RemoveException exception.

When the client component is finished using an Access EJB instance, it should explicitly remove it. However, a call to one of these remove() method does not necessarily remove the actual Access EJB instance; it just notifies the EJB container that the instance can be removed if no other client components are currently using it.

Copyright IBM Corp. 1997, 2004