Mastering Enterprise JavaBeans™ and the Java 2 Platform, Enterprise Edition - Roman E

The Basics of Stateful Session Beans 117

passivate the bean that has been called the least recently. This is a good algorithm because remote clients have the habit of disconnecting from the network, leaving beans stranded without a client, ready to be passivated. If a bean hasn’t been invoked in a while, the container will write it to disk.

Passivation can occur at any time, so long as a bean is not involved in a method call. It’s up to the container to decide when passivation makes sense. Note that there is one exception to this rule: Any bean involved in a transaction (see Chapter 10) cannot be passivated until the transaction completes.

To activate beans, most containers will usually use a just-in-time algorithm. Just in time means that beans should be activated on demand, as client requests come in. If a client request comes in but that client’s conversation has been passivated, the container will activate the bean on demand, reading the passivated state back into memory.

In general, passivation and activation are not useful for stateless session beans. Stateless beans do not have any state to passivate/activate, and so stateless beans can simply be destroyed arbitrarily by the container. Passivation/activation also applies to entity beans, which we’ll learn about in Chapters 7–9.

The Rules Governing Conversational State

As we have said, stateful session beans hold conversational state on behalf of one client. Let’s define that state a bit more rigorously. It’s important to know the rules for specifying conversational state, so that the container will passivate and activate properly.

The conversational state of a bean follows the rules laid out by Java object serialization (see Appendix A). When a container passivates a bean, it uses object serialization (or an equivalent protocol) to convert the bean’s conversational state into a bit-blob. It can then write that blob out to storage. Once the bean is written to storage, the memory is available to be freed by the garbage collector.

Activation reverses the process—a serialized blob that had been written to storage is read back into memory and converted to in-memory bean data. What makes this whole process work is the javax.ejb.EnterpriseBean interface extends java.io.Serializable, and every enterprise bean class indirectly implements this interface.

More concretely, every member variable in a bean is considered to be part of the bean’s conversational state if the following apply:

■■The member variable is a nontransient primitive type, or

■■The member variable is a nontransient Java object (extends java.lang.Object).

Go back to the first page for a quick link to buy this book online!

118 M A S T E R I N G E N T E R P R I S E J A V A B E A N S

For every Java object that’s part of a bean’s conversational state, the previous algorithm is reapplied recursively on those objects. Thus, object serialization constructs an entire graph of data referred to by the main bean. You should note that while your beans must follow the rules for object serialization, the EJB container itself does not necessarily need to use the default serialization protocol; it could use a custom protocol for this, to allow flexibility and differentiation between container vendors.

Activation/Passivation Callbacks

Let’s now look at what actually happens to your bean during passivation and activation. When an EJB container passivates a bean, the container writes the bean’s conversational state to secondary storage, such as a file or database. The container informs the bean that it’s about to perform passivation by calling the bean’s required ejbPassivate() callback method. ejbPassivate() is a warning to the bean that its held conversational state is about to be swapped out.

It’s important that the container inform the bean using ejbPassivate() so that the bean can relinquish held resources. These held resources include database connections, open sockets, open files, or other resources that do not make sense to be saved to disk or cannot be transparently saved using object serialization. The EJB container calls the ejbPassivate() method to give the bean a chance to release these resources or deal with the resources as the bean sees fit. Once the container’s ejbPassivate() callback method into your bean is complete, your bean must be in a state suitable for passivation. This is shown in Figure 5.1.

The exact opposite process occurs during the activation process. Here, the serialized conversational state is read back into memory, and the container reconstructs the in-memory state using object serialization or the equivalent. The container then calls the bean’s required ejbActivate() method. ejbActivate() gives the bean a chance to restore the open resources it released during ejbPassivate(). This entire process is shown in Figure 5.2.

Do you have to worry about implementing ejbPassivate() and ejbActivate()? Probably not, unless you are using open resources, such as socket connections or database connections, that must be reestablished after activation. In most cases, you can simply leave these methods empty.

A Simple Stateful Session Bean

Let’s put our stateful session bean knowledge to use by programming a simple stateful bean. Our bean will be a counter bean, and it will simply be responsible for counting up one by one. The current count will be stored within the bean, and it will increment as client requests arrive. Thus, our bean will be stateful, and it will hold a multimethod conversation with a particular client.

Go back to the first page for a quick link to buy this book online!

The Basics of Stateful Session Beans 119

Client

1: Invoke business method

2: Pick the least recently used bean

Remote

4: Serialize the bean state

Interface

Other Enterprise

Beans

5: Store passivated

bean state

A typical stateful bean passivation scenario. The client has invoked a method on an EJB object which does not have a bean tied to it in memory. The container's pool size of beans has been reached. Thus, the container needs to passivate a bean before handling this client's request.

Storage

Figure 5.1 Passivation of a stateful bean.

The Count Bean’s Remote Interface

First, let’s define our bean’s remote interface. The code is shown in Source 5.1.

Our remote interface defines a single business method—count()—which we will implement in the enterprise bean class.

The Count Bean

Our bean implementation has one business method, count(), which is responsible for incrementing an integer member variable, called val. The conversational state is the val member variable. We show the code for our counter bean in Source 5.2.

Go back to the first page for a quick link to buy this book online!

120 M A S T E R I N G E N T E R P R I S E J A V A B E A N S

Client

1: Invoke business method

Other Enterprise

Beans

2: Retrieve passivated bean state

A typical just-in-time stateful bean activation scenario. The client has invoked a method on an EJB object whose stateful bean had been passivated.

Storage

Figure 5.2 Activation of a stateful bean.

package com.wiley.compBooks.roman.session.count;

import javax.ejb.*;

import java.rmi.RemoteException;

/**

*These are CountBean's business logic methods.

*This interface is what clients operate on when they

*interact with EJB objects. The container vendor will

*implement this interface; the implemented object is

Source 5.1 Count.java (continues).

Go back to the first page for a quick link to buy this book online!

The Basics of Stateful Session Beans 121

*the EJB Object, which delegates invocations to the

*actual bean.

*/

public interface Count extends EJBObject {

/**

* Increments the int stored as conversational state */

public int count() throws RemoteException;

}

Source 5.1 Count.java (continued).

package com.wiley.compBooks.roman.session.count;

import javax.ejb.*;

/**

*Demonstration Stateful Session Bean. This bean is

*initialized to some integer value and has a business

*method that increments the value.

*

*This example shows the basics of how to write a stateful

*session bean and how passivation/activation works.

*/

public class CountBean implements SessionBean {

private SessionContext ctx;

// The current counter is our conversational state. public int val;

//

// Business methods

//

/**

* Counts up */

public int count() { System.out.println("count()"); return ++val;

}

//

// EJB-required methods

//

Source 5.2 CountBean.java (continues).

Go back to the first page for a quick link to buy this book online!

122 M A S T E R I N G E N T E R P R I S E J A V A B E A N S

public void ejbCreate(int val) throws CreateException { this.val = val;

System.out.println("ejbCreate()");

}

public void ejbRemove() { System.out.println("ejbRemove()");

}

public void ejbActivate() { System.out.println("ejbActivate()");

}

public void ejbPassivate() { System.out.println("ejbPassivate()");

}

public void setSessionContext(SessionContext ctx) {

}

}

Source 5.2 CountBean.java (continued).

Here are some things to notice about our bean:

■■The bean implements javax.ejb.SessionBean (defined in Chapter 3). This means the bean must define all methods in the SessionBean interface. Indeed, by looking at the bean, you can see we’ve defined them but kept them fairly trivial.

■■Our ejbCreate() initialization method takes a parameter, val. This is in stark contrast to stateless session beans, which never take parameters in ejbCreate(). Our initialization method is responsible for beginning a conversation with the client. It uses val as the starting state of the counter.

■■The val member variable obeys the rules for conversational state because it is serializable. Thus, it will last across method calls, and it will automatically be preserved during passivation/activation.

The Count Bean’s Home Interface

To complete our stateful bean code, we must define a home interface. The home interface will detail how to create and destroy our Count EJB object. The code for our home interface is in Source 5.3.

Because we implement javax.ejb.EJBHome, our home interface gets the remove() destroy method for free.

Go back to the first page for a quick link to buy this book online!

The Basics of Stateful Session Beans 123

package com.wiley.compBooks.roman.session.count;

import javax.ejb.*;

import java.rmi.RemoteException;

/**

*This is the home interface for CountBean. This interface

*is implemented by the EJB Server's glue-code tools - the

*implemented object is called the Home Object and serves

*as a factory for EJB Objects.

*One create() method is in this Home Interface, which

*corresponds to the ejbCreate() method in the CountBean file. */

public interface CountHome extends EJBHome {

/*

*This method creates the EJB Object.

*@param val Value to initialize counter to

*@return The newly created EJB Object.

*/

Count create(int val) throws RemoteException, CreateException;

}

Source 5.3 CountHome.java.

The Count Bean’s Deployment Descriptor

Now that we’ve got all our Java files for our bean, we need to define the deployment descriptor to identify the bean’s settings to the container. The deployment descriptor settings we use are listed in Table 5.1.

Notice that we’ve added a container-specific deployment descriptor setting, “Max beans loaded at any time.” Not all containers will support this (the BEA WebLogic server we tested against does). We are restricting the maximum number of beans loaded so that we can force the EJB container to passivate and activate our beans. Our strategy will be to load three beans at once, thus forcing the container to passivate in order to reduce the number of beans in memory.

Also notice that our bean’s stateful nature is defined declaratively in the deployment descriptor. We never introduce the notion of a bean being stateful in the bean code itself. This allows us to easily switch from the stateful to stateless paradigm and back.

Go back to the first page for a quick link to buy this book online!

The Count Bean’s Environment Properties

This demonstration bean is quite simple, so we do not use environment properties to customize the bean on deployment. Chapter 6 demonstrates beans with properties files.

The Count Bean’s Manifest File, Ejb-jar File, and Deployment

To complete our component, we need to write a manifest file for the Ejb-jar file. The jar’s manifest is straightforward and no different really from the one we used for our “Hello, World!” bean in Chapter 4. The generation of an Ejb-jar file is similar to our “Hello, World!” example.

Once we generate the Ejb-jar file, we must deploy our bean in an EJB container to test it out. This step varies widely from container to container. If you’re using the BEA’s WebLogic server, take a look at the makefile on the included CD-ROM for this deployment step. If you have a different preferred container vendor, consult your vendor’s product documentation.

To save space, in future examples we’ll consider that manifest generation, Ejbjar file generation, and bean deployment are implied steps.

The Count Bean’s Client Code

Now that our bean is deployed, we can write some Java code to test our beans. Our client code performs the following steps:

Go back to the first page for a quick link to buy this book online!

The Basics of Stateful Session Beans 125

1.We acquire a JNDI initial context.

2.We locate the home object using JNDI.

3.We use the home object to create three different Count EJB objects. Thus, we are creating three different conversations and are simulating three different clients.

4.Our deployment descriptor limits the bean pool size to two beans, so during the previous step some of the three beans must have been passivated. We print out a message during the ejbPassivate() callback to illustrate this.

5.Next, we call count() on each EJB object. This forces the container to activate the instances, restoring the conversations to memory once again. We print out a mesasge during the ejbActivate() callback to illustrate this.

6.Finally, all the EJB objects are removed.

The code appears in Source 5.4.

package com.wiley.compBooks.roman.session.count;

import javax.ejb.*; import javax.naming.*;

import java.util.Properties;

/**

* This class is a simple example of client code that invokes

*methods on a simple Stateless Enterprise Bean.

*We create 3 EJB Objects in this example, but we allow

*the container to have only 2 in memory. This illustrates how

*beans are passivated to storage.

*/

public class CountClient {

public static void main(String[] args) {

try { /*

* Get System properties for JNDI initialization */

Properties props = System.getProperties();

/*

*Get a reference to the Home Object - the

*factory for EJB Objects

*/

Source 5.4 CountClient.java (continues).

Go back to the first page for a quick link to buy this book online!

126 M A S T E R I N G E N T E R P R I S E J A V A B E A N S

Context ctx = new InitialContext(props);

CountHome home = (CountHome) ctx.lookup("CountHome");

/*

* An array to hold 3 Count EJB Objects */

Count count[] = new Count[3];

int countVal = 0;

/*

* Create and count() on each member of array */

System.out.println("Instantiating beans..."); for (int i=0; i < 3; i++) {

/*

*Create an EJB Object and initialize

*it to the current count value.

*/

count[i] = home.create(countVal);

/*

* Add 1 and print */

countVal = count[i].count();

System.out.println(countVal);

/*

* Sleep for 1/2 second */

Thread.sleep(500);

}

/*

*Let's call count() on each EJB Object to

*make sure the beans were passivated and

*activated properly.

*/

System.out.println("Calling count() on beans..."); for (int i=0; i < 3; i++) {

/*

* Add 1 and print */

countVal = count[i].count();

System.out.println(countVal);

Source 5.4 CountClient.java (continues).

Go back to the first page for a quick link to buy this book online!