Session Beans

What are Session Beans?

Session beans are used to execute business tasks for a client on the server. A session bean typically implements a certain kind of activity, such as ordering products or signing up for courses, and in executing the business rules typically invokes entity beans. For instance, ordering products is likely to involve stored information about products, customers, and credit cards, while signing up for courses is likely going to require invoking entity beans representing students and courses.

Stateful and Stateless

There are two types of session beans, stateful and stateless. A stateful session bean maintains conversational state. In other words, a stateful session bean remembers the calling client application from one method to the next. For a stateful session bean, the results produced by one method might be co-dependent on the results of its prior methods invoked by the same client. A stateful session bean maintains this conversation with the client until the conversation times out or the client explicitly ends the conversation by invoking the bean's remove method.

In contrast, a stateless session bean does not maintain any conversational state, that is, it does not remember which client invoked one of its methods, and does not maintain an internal state between methods. Each session bean method is independent, and the only client input is the data passed in its parameters.

Stateful session beans are tied to a particular client for the duration of the conversation, while stateless session beans are only tied to a particular client for the duration of a method execution. After method execution completes, a stateless session bean is ready to serve another client application. Consequently, a small number of stateless session beans can be used to serve a large number of client applications. Stateless session beans tend to be more commonly preferred over stateful session beans for this reason. When the client application is a page flow or a conversational web service, conversational state is remembered by the client application itself, making it possible to use a stateless session bean while maintaining a continuous session with the user of the client application. When you develop a new session bean in WebLogic, by default a stateless session bean is defined.

Home and Business Interfaces

Like an entity bean, a session bean can have four different interfaces, called the local home interface, the local business interface (or simply, the local interface), the remote home interface, and the remote business interface (or simply, the remote interface). The local interfaces define the bean's methods that can be used by other EJBs, EJB controls, web services and page flows defined within the same application. That is, if you define a session bean and only plan to use it within that application, you can use local interfaces. In contrast, the remote interfaces define the bean's methods that be invoked by EJBs, EJB controls, web services and page flows defined in other applications.

To determine what interfaces are defined for a session bean, ensure you are in Design View and go to the Naming section in the Property Editor. The Remote EJB and Local EJB sections refer to the remote and local interfaces; within each section the Home class name refers to the home interface, and the Bean class name refers to the business interface. In Source View, the attributes are part of the @ejbgen:file-generation Annotation. When you define a new session bean, by default only the remote interfaces are defined.

A session bean's (remote or local) home interface contains the create methods used to obtain a reference to the bean instance. Its (remote or local) business interface contains the component methods that are used to encapsulate a particular piece of business logic.

The Create Methods

For a stateless session bean, you must define exactly one ejbCreate() method with no parameters. This method must be invoked to obtain to a reference to a session bean instance. Once you have obtained a reference, you can invoke the session bean's component methods. If you call a stateless session bean via an EJB control, you do not need to call the create method explicitly; the EJB control will create a reference for you when you call a component method.

A stateful session bean must have at least one ejbCreate method and, like entity beans, can have multiple ejbCreate methods. One of these methods must be invoked to obtain a reference to the session bean instance before you can invoke the session bean's component methods. If you call a stateful session bean via an EJB control, you must first call (one of) its create methods to obtain a reference.

Unlike with stateless session beans, when you can call a stateful session bean's create method to obtain a reference and subsequently invoke several component methods, each method is guaranteed to be handled by the same bean instance on the server. For more information, see The Life Cycle of a Session Bean.

Component Methods

Component methods are the business methods that are invoked on a session bean instance. A simple example of a business method is reserveTickets(customer, movieName, date), which is used to reserve tickets for a movie. For more information, see How Do I: Add a Component Method to an Entity or Session Bean?

In principle there is no difference between component methods for a stateful and a stateless session bean. However, the component methods of a stateless session bean must be passed all the necessary data to execute business logic as parameters, while this is not necessary for the component methods of a stateful session bean. For instance, for a stateful session bean the component method reserveTickets() can be used to make ticket reservations for a movie, after the component method setCustomer(customer) is called to set the customer data, setMovie(name) is called to make the movie selection, and setDate(date) is called to set the movie time. For a stateless session bean, these parameters must be passed to the component method making the actual reservations, as in reserveTickets(customer, movieName, date).

Other Methods

A session bean has several predefined methods, as well as a number of callback methods, invoked by the EJB container during certain operations, that a session bean must implement. In WebLogic these callback methods are by default automatically implemented. In many cases you will find it unnecessary to use these methods. To learn more about these methods, see Defining a Session Bean and The Life Cycle of a Session Bean.

• Create a session bean from scratch. If you are designing a new session bean in EJB project, you can define a new session bean. To find out exactly how to do this, see How Do I: Create an Enterprise JavaBean? When you create a new session bean, by default the remote interfaces and various other defaults are defined. For more details, see @ejbgen:file-generation Annotation.
• Import a session bean. If you have developed session beans in another development environment, you can import these into WebLogic. To import an EJB, you need the EJB Jar file as well as the source files. You can import multiple EJBs at the same time. For more information, see How Do I: Import an Enterprise JavaBean? After you have imported a session bean, you can enhance its definition.

  Note. If you have existing session beans that you plan to invoke in the application, for instance via another EJB or an EJB control, but you do not intend to change their definitions, you can suffice by adding the EJB Jar to the application. For more information, see How Do I: Add an Existing Enterprise JavaBean to an Application?

package myBeans;

import javax.ejb.*;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import weblogic.ejb.*;

/**
 * @ejbgen:session
 *   ejb-name = "PriceChecker"
 *
 * @ejbgen:jndi-name local="ejb.PriceCheckerLocalHome"
 *
 * @ejbgen:file-generation remote-class="false" remote-home="false" local-class="true" 
 *   local-class-name = "PriceCheckerLocal" local-home="true" local-home-name = "PriceCheckerLocalHome"
 *
 * @ejbgen:ejb-local-ref link="Product"
 */
public class PriceCheckerBean extends GenericSessionBean implements SessionBean
{
  private ProductHome productHome;
  
  public void ejbCreate() {
     try {
        javax.naming.Context ic = new InitialContext();
        productHome = (ProductHome)ic.lookup("java:comp/env/ejb/Product");
     } 
     catch (NamingException ne) {
        throw new EJBException(ne);
     }
  }

  /**
   * @ejbgen:local-method
   */
  public String returnPrice(String product)
  {
     Product theProduct;
     int visitNumber;

     try {
        theProduct = productHome.findByPrimaryKey(product);
     }
     catch(FinderException fe) {
        return "Product not known";
     }
     return "The price of this product is " + theProduct.getPrice(); 
  }
}

The @ejbgen:session annotation contains the actual name of the session bean. For stateful session beans this tag will contain the attribute type="Stateful". In the ejbCreate method a reference to the Product entity bean's local home interface is obtained. The JNDI reference Product used in the lookup method to look up the Product bean, is mapped to this bean's local interface using an @ejbgen:ejb-local-ref Annotation, which is defined at the top of the PriceChecker bean class definition. To learn more about JNDI naming, consult your favorite J2EE documentation or go to http://java.sun.com.

The method returnPrice implements the business logic for this class. It finds a particular product using the Product bean and returns its price. If the product cannot be found in the database, it returns a Product not known message instead.

In WebLogic, all the information needed to make a session bean are stored in a single file, instead of separate JAVA files for the bean class, the local business interface, the local home interface, and so forth. When you build a session bean, these classes are auto-generated. Various ejbgen annotations are used to hold the information required to make this generation possible. Specifically, the @ejbgen:file-generation annotation specifies the names of the local home and business interface for the PriceChecker bean, and the @ejbgen:local-method annotation on the component method specifies that the method should be defined in the local business interface. To verify that these JAVA and corresponding CLASS files are generated, expand the JAR file created during a build (located in the Modules folder in the Application pane), and locate and open the generated files in the folder reflecting the package name. For the PriceCheckerBean, the PriceCheckerBean.java (bean definition), PriceCheckerLocal.java (local interface definition), and PriceCheckerLocalHome.java (local home interface definition) files are auto-generated.

The Life Cycle of a Stateless Session Bean

• Does Not Exist. In this state, the bean instance simply does not exist.
• Ready. When WebLogic server is first started, several bean instances are created and placed in the Ready pool. More instances might be created by the container as needed by the EJB container.

Moving from the Does Not Exist to the Ready State

When the EJB container creates a stateless session bean instance to be placed in the ready pool, it calls the callback method public void setSessionContext(SessionContext ctx). This method has the parameter javax.ejb.SessionContext, which contains a reference to the session context, that is, the interface to the EJB container, and can be used to self-reference the session bean object. Complete details about the javax.ejb.SessionContext can be found in your favorite J2EE documentation and the API reference at http://java.sun.com.

After the callback method setSessionContext is called, the EJB container calls the callback method ejbCreate. You can implement this callback method to for instance obtain the home interfaces of other EJBs invoked by the session bean, as shown in Defining a Session Bean. The ejbCreate method is only called once during the lifetime of a session bean, and is not tied to the calling of the create method by a client application. For a stateless session bean, calling the create method returns a reference to a bean instance already in the ready pool; it does not create a new bean instance. The management of stateless session bean instances is fully done by the EJB container.

The Ready State

When a bean instance is in the ready state, it can service client request, that is, execute component methods. When a client invokes a business method, the EJB container assign an available bean instance to execute the business method. Once executed, the session bean instance is ready to execute another business method.

Moving from the Ready to the Does Not Exist State

When the EJB container decides to reduce the number of session bean instances in the ready pool, it makes the bean instance ready for garbage collection. Just prior to doing this, it calls the callback method ejbRemove. If your session bean needs to execute some cleanup action prior to garbage collection, you can implement it using this callback method. The callback method is not tied to the remove method invoked by a client. For a stateless session bean, calling the remove method invalidates the reference to the bean instance already in the ready pool, but it does not move a bean instance from the ready to the does not exist state, as the management of stateless session bean instances is fully done by the EJB container.

The Life Cycle of a Stateful Session Bean

• Does Not Exist. In this state, the bean instance simply does not exist.
• Ready. A bean instance in the ready state is tied to particular client and engaged in a conversation.
• Passive. A bean instance in the passive state is passivated to conserve resource.

Moving from the Does Not Exist to the Ready State

When a client invokes a create method on a stateful session bean, the EJB container creates a new instance and invokes the callback method public void setSessionContext(SessionContext ctx). This method has the parameter javax.ejb.SessionContext, which contains a reference to the session context, that is, the interface to the EJB container, and can be used to self-reference the session bean object. Complete details about the javax.ejb.SessionContext can be found in your favorite J2EE documentation and the API reference at http://java.sun.com. After the callback method setSessionContext is called, the EJB container calls the callback method ejbCreate that matches the signature of the create method.

The Ready State

A stateful bean instance in the ready state is tied to a particular client for the duration of their conversation. During this conversation the instance can the execute component methods invoked by the client.

Activation and Passivation

To more optimally manage resources, the EJB container might passivate an inactive stateful session bean instance by moving it from the ready state to the passive state. When a session bean instance is passivated, its (non-transient) data is serialized and written to disk, after which the the bean instance is purged from memory. Just prior to serialization, the callback method ejbPassivate is invoked. If your session bean needs to execute some custom logic prior to passivation, you can implement it using this callback method.

If after passivation a client application continues the conversation by invoking a business method, the passivated bean instance is reactivated; its data stored on disk is used to restore the bean instance state. Right after the state has been restored, the callback method ejbActivate is invoked. If your session bean needs to execute some custom logic after activation, you can implement it using this callback method.The caller (a client application or another EJB) of the session bean instance will be unaware of passivation (and reactivation) having taken place.

If a stateful session bean is set up to use the NRU (not recently used) cache-type algorithm, the session bean can time out while in passivated state. When this happens, it moves to the does not exist state, that is, it is removed. Prior to removal the EJB container will call the callback method ejbRemove. If a stateful session bean is set up to use the LRU (least recently used) algorithm, it cannot time out while in passivated state. Instead this session bean is always moved from the ready state to the passivated state when it times out.

The exact timeout can be set using the idle-timeout-seconds attribute on the @ejbgen:session annotation. The cache-type algorithm can be set using the cache-type attribute on the same annotation.

Moving from the Ready to the Does Not Exist State

When a client application invokes a remove method on the stateful session bean, it terminates the conversation and tells the EJB container to remove the instance. Just prior to deleting the instance, the EJB container will call the callback method ejbRemove. If your session bean needs to execute some custom logic prior to deletion, you can implement it using this callback method.

An inactive stateful session bean that is set up to use the NRU (not recently used) cache-type algorithm can time out, which moves it to the does not exist state, that is, it is removed. Prior to removal the EJB container will call the callback method ejbRemove. If a stateful session bean set up to use the LRU (least recently used) algorithm times out, it always moves to the passivated state, and is not removed.

The exact timeout can be set using the idle-timeout-seconds attribute on the @ejbgen:session annotation. The cache-type algorithm can be set using the cache-type attribute on the same annotation.