Chapter 20   Writing Session Beans

This chapter describes the category of Enterprise JavaBean known as session beans. It specifically includes these sections:

• About session beans

• Session beans and transactions

• Session beans and data

• Developing a session bean

About session beans   

A session bean is a server-side object that implements the javax.ejb.SessionBean interface. Like a SilverStream invoked triggered object, you use a session bean as a means for implementing your business logic. You might use a session bean as a client shopping cart application, as a class that performs some type of business logic, or as a class that accesses and manipulates your enterprise data.

Session bean state

Session beans can be stateful or stateless. A stateful session bean is one whose member variables can maintain their state between method calls. The CalculatorDemo, in the Examples3_EJB database is an example of a stateful session bean. It contains business methods that add, subtract, multiply and divide the numbers entered by the user. It keeps a running total based on the operations that you have performed on it. You could not implement a calculator using a stateless session bean. A stateless session bean is simply a collection of related public methods. Any values in the bean's member variables are lost once the bean exits the method in which the member variable gets its value. As a result stateless beans are lighter weight and more efficient, but are not useful for certain types of applications.

You specify the session bean's state in the deployment descriptor.

Session bean access

Session beans residing on a SilverStream Server can access:

• Other session beans

  Session beans running on a server can locate and call other session beans on the same or a different SilverStream Server.

• An external data source such as a relational database (using JDBC)

• An AgaData

Session bean components

Session beans include the following components:

Component	Description
Session bean class	The Java class that implements the javax.ejb.SessionBean interface. It can optionally implement the javax.ejb.SessionSynchronization interface. This class includes the methods that implement the business logic you need the bean to perform.     For more information about either interface, see the online API Reference.
Home interface	A Java interface that extends the javax.ejb.EJBHome interface. This interface includes the methods that allow clients to create the session bean. At deployment time, the container constructs the class that implements this interface.     For more information about the javax.ejb.EJBHome interface, see the online API Reference.
Remote interface	A Java interface that extends the javax.ejb.EJBObject interface. The remote interface exposes the bean's business methods to any clients. This interface makes the session bean's business methods available to clients. At deployment time, the container constructs the class that implements this interface.     For more information about the java.ejb.EJBObject, see the online API Reference.

Session bean lifecycle

Session beans have a simple lifecycle. They are created when a client calls the create() method on the session bean's EJBHome object. They can be explicitly removed when a client calls the remove(). The SilverStream container will also remove the bean once the session that it is associated with is gone.

Session beans and transactions   

Session beans can participate in either global transactions or transactions with an unspecified context (sometimes called local transactions). You must specify the transaction management type in the deployment descriptor. The transaction management type can be:

• Bean-managed (also called bean-demarcated)

  Bean-managed session beans use the Java Transaction API for global transactions.Session beans that use bean-demarcated transaction management have complete control over a transaction's scope and how it commits or rolls back.

• Container-managed (also called container-demarcated)

  Container-managed session beans specify transaction attributes (per method) declaratively in the deployment descriptor.

    For more information on setting the transaction type and transaction attributes, see Understanding Deployment Descriptors.

Using session beans to manage entity bean transactions

There might be some situations when you want to use a session bean to control transactions for entity beans.

    For more information on using this technique, see the EJB section of the online Application Techniques guide.

Session beans and data   

Session beans can smoothly integrate with the SilverStream data architecture as a data consumer in one of the following ways:

• Using an AgaData

• Using accessor objects

    For more information on using AgaDatas, see Using AgaDatas.

They can also access data in a standard and portable way using one of the following:

• Using JDBC

• Using an entity bean

Developing a session bean   

Before you begin your session bean development, you should decide:

• Does the application require stateful or stateless beans?

• Does the application require bean-demarcated or container-demarcated transactions?

• What environment variables, other beans, other resources and security does my bean need?

• What kind of data does the application need to access?

• Do the beans have to be portable?

Session bean development cycle   

Here's the development cycle for a session bean:

• Determine the APIs required for your bean.

• Write the home interface (extending javax.ejb.EJBHome) and remote interface (extending javax.ejb.EJBObject).

• Write the session bean which is a Java class that implements javax.ejb.SessionBean.

• Add the session bean to an EJB JAR file.

• Create a deployment descriptor for the EJB JAR file.
  • Add structural information about the bean, such as its name and state type, and so on.

  • Determine the bean's transaction behavior, security roles, environment properties, bean references, and so on and add them to the deployment descriptor.

• Optionally, assemble the bean into an application.

    For more information on creating a deployment descriptor, see Understanding Deployment Descriptors in the Programmer's Guide.

Session bean deployment cycle   

The deployment cycle for a session bean includes:

• Installing the EJB JAR on the server

  If you have used SilverStream to develop the bean, it's already available to the server. If you developed the bean in a different IDE, then you must import the EJB JAR before you can install it on the server.

• Creating a deployment plan which can include:
  • Adding operational information about the bean, for example, the JNDI name

  • Mapping roles to principals, mapping inter-bean references, and so on

    For more information on deploying EJBs, see Deploying EJBs in the Programmer's Guide.

Writing a session bean class   

Writing the session bean's Java class is like developing any standard Java class. You can develop it using the SilverStream IDE, or an external IDE.

Regardless of the tool used to build it, the bean must meet the following requirements:

• It must implement javax.ejb.SessionBean interface.

• The class must include at least one ejbCreate() method.

  It can include as many of ejbCreate() methods (with different arguments) as you need.

• It also includes any additional methods that you want for your business logic.

For a brief tutorial on writing and deploying session beans using the SilverStream IDE, see the EJB Session Bean Quick Start in the online Getting Started book.

For code examples, see the Examples3_EJB database, or the EJB section of the online Application Techniques.

Implementing the javax.ejb.SessionBean methods

The javax.ejb.SessionBean interface includes the methods listed below. They are used by the container to manage the bean's lifecycle and to provide information to the bean about its environment. They are not called by the bean's clients.

Method	Description
ejbActivate() and ejbPassivate()	Used by the container to manage bean instances. The implementation can be empty. SilverStream (Version 3.0) does not passivate session beans so ejbPassivate() is never called. SilverStream calls ejbActivate() once, just after creating an instance of the bean.
ejbRemove()	The container calls this method when the remove() method on the EJBObject is called.
setSessionContext()	The container calls this method after it creates an instance of a session bean, but before it calls the create() method. You can save the reference to the SessionContext object and use it to obtain information that might be useful later, for example, a userTransaction.

    For more information about these methods, see the Java2 Enterprise APIs in the online API Reference.

Writing the setSessionContext() method body

The setSessionContext() method is called by the container in the early stages of the beans lifecycle. It is called after creating the bean instance, but before calling the create method. The container uses it to pass information about the container-provided runtime context of the session bean instance. You can use this at any time to obtain transaction and security-related information.

To make this information available to your session bean instance, you have to save the context in a member variable. First, create a member variable:

  protected SessionContext m_context; 

Then, in the setSessionContext() method, save it:

  m_context = sessionContext1; 

Writing method bodies for activate() and passivate()

If you are writing a portable session bean, then you probably want to write method bodies for activate() and passivate(). For example, you might use activate() methods to obtain resources, like JDBC connections or a JNDI context, and passivate() to free them.

Writing ejbCreate() methods

The ejbCreate() methods in a bean are written by you. These methods are similar to constructors. They must also be represented on the bean's home interface as create() methods. The only requirement is that the ejbCreate() method returns void.

About the business methods

Like the ejbCreate() methods, the methods that perform your business logic, data access routines, or utility function are written by you. The only requirement is that return types and parameters are Serializable.

Writing the remote interface   

The remote interface makes the bean's business methods available to clients. You do not need to write the code that implements this interface. Instead, at deployment time, the container generates a class that implements this interface. The container then uses this class to respond to business method calls from clients.

Here are the requirements for the remote interface:

• It must extend javax.ejb.EJBObject.

• It must declare the business methods that you want to expose to clients. Further, these business methods must:
  • Throw the same exceptions as the method declared in the bean

  • Throw java.rmi.RemoteException

For more information about the methods on the remote interface, see the Java2 Enterprise APIs in the online API Reference.

Writing the home interface   

The home interface makes the bean's create methods available to clients. It extends the javax.ejb.EJBHome interface. At deployment time, the container takes this interface and generates a class. The container then uses this class as the factory for creating all instances of the session bean.

Here are the requirements for writing the bean's home interface.

• It must extend javax.ejb.EJBHome.

• It must declare a create() method for each ejbCreate() method in your session bean. Further, these create() methods must:
  • Have a signature that includes the same parameters as the bean class's ejbCreate() method

  • Throw the javax.ejb.CreateException and the javax.ejb.RemoteException

  • Return the remote interface type

  • For stateless session beans, there can be only a single create() method, and it cannot take any arguments

    For more information about the methods on the home interface, see the Java2 Enterprise APIs in the online API Reference. For examples of session beans, see the EJB section of the online Application Techniques.