The value and importance of session beans come from the communication interface between clients and session beans. Session beans consist of a bean class and two interfaces—the home interface and the remote interface. These interfaces provide the thin client to a bean, whereas the bean class, which implements the javax.ejb.SessionBean interface, carries out the business logic.

This implementation model allows clients to use the remote interface as a proxy to the EJB and, therefore, reduces the resource consumption and complexity that clients have to bear. In addition, the bean developer benefits by being able to focus primarily on coding business logic, while the EJB container provides the environment (bean classes and interfaces) in which the bean is implemented. As shown in Figure 20.1, at a high level, the EJB container transparently intercepts client calls to a bean’s method, injects management and control infrastructure services to the invocation, and then calls the bean’s method.

Figure 20.1. The relationship between the container and session bean.

The infrastructure services that the EJB container provides to a session bean can include the following:

Developers, therefore, do not have to be concerned about implementing these infrastructure services or the underlying details of how the client finds the bean or communicates with the bean. On the whole, bean developers implement business logic via methods in the session bean class, and the EJB container provides functionality for remote access, security, concurrency, transactions, and other infrastructure services the bean requires to achieve its desired behavior.

Stateless session beans contain no conversational state between methods for a specific client. When a client calls a method on a stateless session bean, the bean’s instance variables can contain state, but only for the duration of the call. When the method has completed, the bean instance no longer retains the state. The stateless bean instance can, however, hold state, but its state is not guaranteed to be specific to a calling client. For example, instance variables of a stateless bean instance can include an open database connection or an object reference to an EJB object.

However, when stateless bean instance are not involved in servicing a client-called method, they are all considered identical from the client’s perspective. Hence, there is no fixed mapping between clients and stateless instances. This allows the EJB container to delegate a client-called method to any available stateless bean instance. For example, the EJB container can delegate requests from the same client within the same transaction to different instances of the stateless bean between remote method calls.

In general, an EJB container needs to retain only the number of stateless bean instances required to service the current client load. Because of client “think time,” the number of stateless session beans is usually much smaller than the number of active clients. The EJB container typically tries to minimize the resources needed to support stateless session bean clients by creating and destroying the bean instance on an as-needed basis.

Stateful session beans are similar to stateless session beans, except they contain conversational state on behalf of a specific client; this state must be retained across invoked methods and transactions. A stateful session bean retains a client’s conversational state by storing the state as attributes of the bean. It is the EJB container’s responsibility to ensure that subsequent method calls by a client are routed to the same instance of a stateful bean.

Stateful session beans are memory consumers because state has to be maintained within the bean instance. Therefore, to efficiently manage stateful session beans, the EJB container might need to temporarily transfer the state of an idle stateful session bean instance from memory to disk. This transfer is called instance passivation. The transfer back to memory is called activation. The container can passivate a stateful session bean instance only when the instance is not in a transaction.

Even though the major difference between stateless and stateful sessions beans is based on maintaining conversational state between the client and the bean instance, Table 20.1 compares the primary characteristics of these two bean types.

As shown in Figure 20.3, it’s the bean developer’s responsibility to supply the following class files that constitute a session bean:

Figure 20.3. The elements of a session bean.

To develop a session bean, you provide the Implementation class file plus class files for the remote view or local view interfaces—or even both. However, unless you are packaging the bean’s client in the same JAR or EAR archive file as the session bean, you need to provide only the remote view interfaces for the bean. The remote view interfaces are required to enable a client to remotely access the bean via RMI/IIOP, which is the standard communication mechanism between distributed Java and J2EE objects, for example, Java clients calling methods on Java remote objects, such as EJBs.

Details on using local client view interfaces are discussed later in this chapter in “Using a Local View to Access a Session Bean.” First, to get you better acquainted with the composition of a session bean, the following sections discuss the class files that constitute a simple stateless session bean. This example uses the infamous HelloWorld session bean, and you’ll be creating the following class files:

To make sure this example is practical, you will also deploy the HelloWorld session bean to WebLogic Server and create a simple Java client to test the bean’s operation.

To set up your working environment for this session bean example, create a working directory on your file system (for example, one named Helloworld), and then create the following subdirectories:

A build script, discussed later in “Building a Session Bean Deployment Unit,” uses these subdirectories to compile and package the HelloWorld session bean. However, you can create your own specific working directory and subdirectories and modify the build script accordingly.

package examples;

import java.rmi.*;
import javax.ejb.*;

/* The methods defined in this interface are the public interface of the
 * HelloWorld session bean.
*/

public interface HelloWorld extends EJBObject
{
/**
  * This method is identical to the one defined in the Implementation class of
  * the Session Bean, except this method must throw a java.rmi.RemoteException.
  */
   public String getHelloWorldMsg () throws RemoteException;
}

package examples;

import java.rmi.*;
import javax.ejb.*;

/* Defines the methods for creating an instance of the HelloWorld session
/* bean */

public interface HelloWorldHome extends EJBHome {
/**
 * This create() method corresponds to the ejbCreate() method in the
 * Implementation class of the HelloWorld session bean.
 * The create() method returns the remote interface of the HelloWorld
 * session bean.
 */
  public HelloWorld create() throws CreateException,RemoteException;
}

package examples;

import javax.ejb.*;

/** The Implementation class for the HelloWorld session bean */

public class HelloWorldBean implements SessionBean
{
 /**
  * The session context is provided by the EJB container. A session bean must
  * retain its context.
. */
    private SessionContext ctx;

/** An EJB must have a public, parameterless constructor */
    public HelloWorldBean() {}

/** Implement a simple logging mechanism to stdout */
    private void log(String s) {
      if (true) System.out.println(s);
    }
 /**
  * This method is required by the EJB specification,
  * but is not used in this example. The container uses this method
  * to activate a stateful session bean after the bean has been
  * passivated using the ejbPassivate() method.
  */
    public void ejbActivate() {}
/**
  * This method is required by the EJB specification,
  * but is not used in this example. The container uses this method
  * to passivate an active stateful session bean.
  */
    public void ejbPassivate() {}
 /**
  * This method is called by the EJB container to remove the
  * session bean from the EJB container.
  */
    public void ejbRemove() {
        log("ejbRemove() called");
    }
/** Called by the EJB container to set the bean's session context. */
    public void setSessionContext(SessionContext ctx) {
        log("setSessionContext called");
        this.ctx = ctx;
    }
 /**
  * Called by the EJB container when a client calls the create() method in
  * the home interface. This method corresponds to the create() method
  * in the home interface of the HelloWorld session bean (HelloWorldHome.java).
  */
    public void ejbCreate() throws CreateException {
        log("ejbCreate() called");
    }
    public String getHelloWorldMsg () {
        log("Bean Method called");
        return ("Stateless SessionBean says Hello World");
    }
}

The Stubs and Skeletons of Session Bean Interfaces

When you deploy your session bean, method calls to the bean are never handled directly by the remote or home interfaces. Instead, your remote method call to the bean is performed through the collaboration of two EJB container-generated classes called the stub and the skeleton for each interface you implement. Stubs are client-side objects, and skeletons are server-side objects. These classes are responsible for marshaling parameters and return values across the network connection, as shown in Figure 20.4.

Figure 20.4. The roles of a stub and skeleton in remote communication.

Note

The only restriction for remote methods is that all parameters and return values must be serializable.

A stub is basically a proxy of the remote object and has the same interface as the remote object. The stub is also located on the same machine as a calling client, which enables the client to use its methods in the same manner that it would use methods on the remote object directly. The stub is responsible for marshaling method calls into network messages to a target skeleton object.

Note

Marshal means to serialize parameters so that they can be written to the remote object, which in turn deserializes them back into objects. Marshaling is built into the Java language through the Serializable interface.

The skeleton is an object that deconstructs a network message into its method call. After deconstructing a message, the skeleton handles the logic for calling an equivalent method on the remote object that runs on the same machine as the skeleton.

The skeleton also takes the return value of the method call and converts it to a network message that can be sent back to the stub.

Because a session bean implements two interfaces (remote and home), all remote method calls to a session bean are handled through two sets of stubs and skeletons:

• The home stub and home skeleton

• The remote stub and remote skeleton

These stubs and skeletons are auto-generated and implemented by the EJB container when the session bean is deployed to WebLogic Server.

These home and remote stubs and skeletons work in concert to enable a client to remotely call a method on the session bean (see Figure 20.5).

Figure 20.5. The roles of home and remote stubs and skeletons.

The following list explains the numbered callouts in Figure 20.5:

1. During the startup of WebLogic Server, the home stub of every deployed bean is placed into the JNDI naming service. From here, a client can download the home stub to access a bean’s home interface.

2. The client uses the home stub to communicate with its home skeleton, which is controlled by the EJB container, to perform the following tasks:

   • Create a bean instance.

   • Provide state to the bean.

   • Associate a client context with the bean.

   • Create a remote skeleton and stub.

3. The home skeleton returns the remote stub specific to the client via its associated home stub.

   Note

   The skeleton acts as a listener for calls made on the home interface.

4. After the client has obtained the remote stub, any operations called on the remote stub are communicated to the remote skeleton, which is then delegated to the bean in the container.

package examples;

import javax.ejb.*;
/**
 * This is the HelloWorld bean's local interface.
 */
public interface HelloWorldLocal extends EJBLocalObject
{
 /**
  * This method is identical to the one defined in the remote interface of the
  * session bean, except this method does not throw a java.rmi.RemoteException.
  */

  public String getHelloWorldMsg();
}

package examples;

import javax.ejb.*;

/**
 * This is the local home interface for the HelloWorld bean.
 */
public interface HelloWorldLocalHome extends EJBLocalHome
{
/**
 * This create() method corresponds to the ejbCreate() method in the
 * Implementation class of the HelloWorld session bean.
 * The create() method returns the local interface.of the HelloWorld
 * session bean. As you can see, remote exceptions are not applicable for
 * local home interfaces.
 */
    HelloWorldLocal create() throws CreateException;
}

Unit testing your J2EE components after they’re deployed is always the best practice, and this simple session bean is no exception. Because the HelloWorld session bean has only one business method, getHelloWorldMsg(), a simple Java client is required to test this method’s operation. Listing 20.6 shows the code for this Java client, and it has been fully commented to explain the processes of locating the home and remote interfaces and implementing the session bean’s method.

package examples;

import java.rmi.*;
import javax.rmi.PortableRemoteObject;
import javax.naming.*;
import java.util.*;

/**
 * This class is an example of client code that calls
 * methods on a simple stateless session bean.
 */
public class HelloWorldClient {

        private static Context createJNDIContext()
        throws NamingException, RemoteException {

        Hashtable env = new Hashtable();
        env.put(Context.INITIAL_CONTEXT_FACTORY,
                        "weblogic.jndi.WLInitialContextFactory");
        env.put(Context.PROVIDER_URL,"t3://localhost:7001");

        Context context = new InitialContext( env );
        return context;
    }
     /**
     * Main method to unit test the HelloWorld API
     */

    public static void main(String[] args) {
        try
        {

         // use JNDI to look up the home interface for HelloWorld
        Context context = createJNDIContext();

             // You could use the following statement to retrieve
             // the HelloWorld home

        /* HelloWorldHome home =
            (HelloWorldHome)
                          context.lookup("examples.HelloWorldEJB"); * /

             // However, using javax.rmi.PortableRemoteObject
             // allows you to narrow the scope
             // to the home interface

            HelloWorldHome home = (HelloWorldHome )
                                          PortableRemoteObject.narrow(
                                          context.lookup("examples.HelloWorldEJB"),
                                          examples.HelloWorldHome.class ) ;


            HelloWorld hello = home.create();

            /*
             * The EJBObject will delegate the call to the HelloWorld
             * session bean, receive the result, and return it to this client.
             */

                        System.out.println(hello.getHelloWorldMsg());

            /*
             * Remove the EJBObject.
             * The container will mark the EJBObject for destruction.
             */
            hello.remove();
        }
        catch( Exception err )
        {
            System.err.println( err.toString() );
            }
    }
}

Two deployment descriptors are applicable to your session bean example:

The following sections describe these deployment descriptors in the context of the session bean example.

<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise
JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>

<!-- Generated XML! -->

<ejb-jar>
  <enterprise-beans>
    <session>
      <ejb-name>HelloWorldEJB</ejb-name>
      <home>examples.HelloWorldHome</home>
      <remote>examples.HelloWorld</remote>
      <local-home>examples.HelloWorldLocalHome</local-home>
      <local>examples.HelloWorldLocal</local>
      <ejb-class>examples.HelloWorldBean</ejb-class>
      <session-type>Stateless</session-type>
      <transaction-type>Container</transaction-type>
    </session>
  </enterprise-beans>

  <assembly-descriptor>
    <container-transaction>
      <method>
        <ejb-name>HelloWorldEJB</ejb-name>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
    </container-transaction>
  </assembly-descriptor>

</ejb-jar>

<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems,
Inc.//DTD WebLogic 7.0.0 EJB//EN'
'http://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd'>

<!-- Generated XML! -->

<weblogic-ejb-jar>
  <weblogic-enterprise-bean>
    <ejb-name>HelloWorldEJB</ejb-name>
    <stateless-session-descriptor>
      <pool>
        <initial-beans-in-free-pool>5</initial-beans-in-free-pool>
      </pool>

      <stateless-clustering>
        <home-is-clusterable>False</home-is-clusterable>
        <stateless-bean-is-clusterable>False</stateless-bean-is-clusterable>
        <stateless-bean-load-algorithm>RoundRobin</stateless-bean-load-algorithm>
      </stateless-clustering>

    </stateless-session-descriptor>

    <transaction-descriptor>
    </transaction-descriptor>

    <enable-call-by-reference>True</enable-call-by-reference>
    <jndi-name>examples.HelloWorldEJB</jndi-name>
    <local-jndi-name>examples.HelloWorldEJBLocal</local-jndi-name>
  </weblogic-enterprise-bean>
</weblogic-ejb-jar>

Now that you have created your HelloWorld session bean class files and deployment descriptors, the next step is to build your deployment unit (JAR file), which requires you to do the following:

This task is performed with the weblogic.ejbc utility, which generates container classes and implementation classes by inspecting the bean’s Implementation class file and remote and home interfaces and by examining the session bean’s deployment descriptors (see Figure 20.6).

Figure 20.6. Use weblogic.ejbc to generate the WebLogic container classes.

To perform these tasks, it is a good practice to create a build/make script that can automate the whole build process for you. The build script (build.cmd) for compiling, packaging, and generating the container classes is shown in Listing 20.9.

@rem *******************************************************
@rem Cleaning working area
@rem *******************************************************

echo y | rmdir /s classes
echo y | rmdir /s lib
mkdir classes
mkdir lib

@rem *******************************************************
@rem Compiling the session bean files
@rem *******************************************************

javac -d classes src*.java

@rem *******************************************************
@rem Copy deployment descriptors into the META-INF directory
@rem *******************************************************

mkdir classesMETA-INF
copy deployment*.xml classesMETA-INF

@rem *******************************************************
@rem Create the temporary .jar file
@rem *******************************************************

cd classes
jar cf ..lib	emp.jar *
cd ..

@rem *******************************************************
@rem Generating the container classes and creating the deployment
@rem unit
@rem *******************************************************

cd lib
java weblogic.ejbc -keepgenerated temp.jar HelloWorld.jar
del temp.jar
cd ..

You can use two techniques to deploy your HelloWorld session bean. The easiest is simply copying the HelloWorld.jar file into the applications directory within your WebLogic Server domain directory. If your WebLogic Server is started in development mode, which is the default, WebLogic Server auto-deploys the JAR file.

The other deployment technique is a more formal procedure using WebLogic Builder or the Administration Console. Follow these steps to deploy your HelloWorld.jar file to WebLogic Server using the Administration Console:

After your session bean has been deployed to WebLogic Server, the EJB container creates five instances of the bean in the free pool, as specified by the <initial-beans-in-free-pool> element in weblogic-ejb-jar.xml. Because logging was enabled in each method of the HelloWorld bean (see Listing 20.6), the methods called to instantiate the bean into the free pool are displayed in WebLogic Server’s stdout.

To test your HelloWorld session bean, follow these steps:

In the Does Not Exist state, a stateless session bean literally does not exist and has not been instantiated. Also, the stateless bean has no identity. For example, by default, no stateless bean instance exists in WebLogic Server during its boot process.

If the container decides to instantiate a stateless session bean, it does the following:

The stateless session bean instance is now in the Method Ready Pool state, ready for any client to delegate a method call. While the bean is in this state, it exists within the EJB container’s free pool, which is a repository for stateless beans instantiated by the EJB container. The free pool stores unbound stateless beans that are not active and are processing a method call. WebLogic Server uses the free pool to improve performance and throughput for stateless beans, including message-driven beans.

When WebLogic Server starts, if stateless session beans have been deployed to the server, the WebLogic EJB container automatically instantiates multiple instances of the beans, as specified by the value of the <initial-beans-in-free-pool> element in weblogic-ejb-jar.xml. These bean instances are placed in the free pool, ready to service incoming remote method calls. Populating the free pool in this manner improves the initial response time for activating a stateless bean instance because initial requests for the bean can be satisfied without generating a new bean instance.

The EJB container creates new instances of stateless beans as needed for concurrent and parallel method processing. However, the maximum number of stateless session bean instances that can be accommodated in the free pool depends on two factors:

Typically, the EJB container no longer needs the bean instance when it needs to reduce the number of stateless bean instances in the method-ready pool. When this happens, the container calls ejbRemove() on the bean, which transitions the bean to the Does Not Exist state. Also, if a RuntimeException occurs within a stateless session bean’s life cycle, the bean instance transitions to the Does Not Exist state. This does not affect the client because the EJB container delegates another bean instance from the pool to service the client.

When a client calls a create() method on the home interface, the container does not necessarily create an instance of the bean. It just returns a remote interface. Only when method calls are made against a bean’s remote interface does the container find a stateless bean instance in the free pool or create an instance to delegate the method call. The stateless bean then remains active throughout the duration of the client’s method call. When that call is completed, the EJB container detaches the bean instance from the client and returns the bean instance to the container’s free pool.

A container serializes calls to each session bean instance. For this reason, if incoming method requests surpass the number of stateless beans, the method requests must wait until the EJB container can create additional stateless bean instances or the active beans have been unbound from their clients and placed back in the free pool.

When WebLogic Server is first booted, no stateful session bean instances exist.

As clients look up and obtain references to individual beans by calling Create<Method> on the home stub, WebLogic Server initializes the new stateful bean instances by calling newInstance(), setSessionContext(), and, finally, ejbCreate() on the bean, returning the EJBobject reference to the client. After the bean is created, it is immediately considered to be in a Method Ready state and placed in the cache. Hence, the number of stateful beans that can exist in a Method Ready state is client driven, not controlled by the EJB container. In the Method Ready state, the stateful bean instance serves its client’s method calls and remains in this state until one of the following occurs:

Immediately before passivation, the EJB container calls the ejbPassivate() method on the stateful bean, which allows the developer to provide code to deallocate open resources, such as JDBC connections, gracefully. The container passivates the bean only after the ejbPassivate() method has been called.

The resources and information that can be preserved for a stateful bean in a Passivated state include the following:

Only the WebLogic EJB container can transition a stateful bean into the Passivated state. Therefore, to maintain continuous high performance, WebLogic Server reserves the cache for active and recently used stateful session beans. When a stateful bean no longer meets this criteria, it becomes eligible for passivation. This does not imply that a bean meeting this criteria will be passivated; the EJB container takes other factors, such as constraints on server resources, into consideration before a stateful bean is passivated. However, you can influence passivation of stateful session beans through the weblogic-ejb-jar.xml deployment descriptor elements described in the following sections.

<max-bean-in-cache>

This element specifies the maximum number of stateful beans of a specific class that are allowed in memory. When <max-bean-in-cache> is reached, WebLogic Server begins to passivate some beans that have not been recently used (Least Recently Used [LRU]) by the client. The default value of <max-beans-in-cache> is 100. If <max-beans-in-cache> is reached and all EJBs in the cache are being used by clients, WebLogic Server throws a CacheFullException.

When analyzing ways to increase performance through the <max-bean-in-cache> element, you should analyze the operation of your stateful bean application and include answers to the following questions:

Based on these statistics, you can reach a suitable value for the <max-beans-in-cache> element. Ideally, the setting you select should not exceed the available JVM heap memory or bring WebLogic Server to a halt by competing for memory.

<idle-timeout-seconds>

This element defines the maximum length of time a stateful bean should remain in the cache, after which WebLogic Server can remove the bean instance if the number of beans in the cache approaches the limit of <max-beans-in-cache>.

You can specify explicit passivation of stateful EJBs that have reached <idle-timeout-seconds> by setting the <cache-type> element in the weblogic-ejb-jar.xml file, which specifies the order in which stateful beans are removed from the cache. This setting has two values—Least Recently Used (LRU) and Not Recently Used (NRU):

After a stateful session bean instance is passivated, a client must use the EJB instance before <idle-timeout-seconds> is reached. Otherwise, WebLogic Server removes the passivated instance from disk (Does Not Exist state).

When Container-Managed Transactions (CMT) are used, the EJB container requires additional information on how and when to start transactions. This information is also provided in the deployment descriptor in the <container-transaction> element. Six keywords define the transaction attribute (see Table 20.7). The transaction attribute can be applied on a per-bean basis or to individual methods within the bean.

If no <container-transaction> element is provided in the deployment descriptor, the WebLogic EJB container defaults to Supports for all methods in the EJB. An example of the <container-transaction> element from the ejb-jar.xml file is shown in Listing 20.16.

<container-transaction>
    <method>
        <ejb-name>MySessionBean</ejb-name>
        <method-name>*</method-name>
    </method>
    <trans-attribute>Required</trans-attribute>
</container-transaction>

Listing 20.16 sets the Required transaction attribute for all methods in the MySessionBean bean.

The <method> tag section can have specific method names. To support method overloading, a list of method parameters can be supplied to select a specific method signature. An example of a <container-transaction> element that specifies the Mandatory transaction attribute for the getBalance( String account ) method is shown in Listing 20.17.

<container-transaction>
    <method>
        <ejb-name>MySessionBean</ejb-name>
        <method-name>getBalance</method-name>
        <method-params>java.lang.String</method-params>
    </method>
    <trans-attribute>Mandatory</trans-attribute>
</container-transaction>

Bean-Managed Transactions (BMT) are indicated when the <transaction-type> element in the deployment descriptor is set to Bean. The EJB must then directly call methods on the UserTransaction object. With CMT, transaction boundaries are set by the client or EJB container. With BMT, the EJB gets a reference to the UserTransaction object by calling getUserTransaction() on the SessionContext object. The SessionContext object is passed to the EJB through the setSessionContext() method. The EJB can call the begin, commit, and rollback methods on the UserTransaction object. A stateless session bean must commit or roll back every transaction before returning from the method call. A stateful session bean can keep a transaction active across multiple method calls.

Keep in mind that although the stateful session bean is caching the client’s conversational state, the state is not considered transactional. Therefore, it is not automatically rolled back to some initial state when the transaction it participates in is rolled back. The bean developer needs to provide logic to accomplish this task.