Programmer's Guide

Chapter 21   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 EJB Examples 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() method. The SilverStream container will also remove the bean once the session that it is associated with is gone.

Instance pooling   The SilverStream container maintains a pool of idle/unused stateless session beans. This allows the container to dynamically assign instances of a stateless session bean to different clients, which allows for better performance and scalability. You can define a maximum pool size for each stateless session bean at deployment. The default is 500.

SilverStream does not create the instance pool when you deploy the bean; instead it populates the pool as the need for instances increases. It manages the pool as follows:

• The container returns all instances to the pool (unless the pool has reached max pool size) when clients are finished with them.

• If the pool is at max pool size, SilverStream discards the instances that are freed.

• When the pool is empty, SilverStream does not wait for an instance to be freed; it simply creates a new instance for the caller.

• When the client is finished with that instance, SilverStream discards it instead of putting it back in the pool. This way the maximum pool size is never exceeded.

• To reconfigure the max pool size, you must redeploy the bean.

• It is valid to set the pool size to zero. When it is set to zero, instances are never reused.

    For more information on setting this value, see the chapter on J2EE archive deployment in the Facilities Guide of the server's Core Help.

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 transaction attributes, see the section on EJB deployment descriptors in the JAR Designer chapter of the online Tools Guide.

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.

      For information on creating a deployment descriptor using SilverStream's tools, see the JAR Designer chapter in the online Tools Guide.

• Optionally, assemble the bean into an application and write an EJB client.

• Deploy the EJB JAR to a SilverStream server so that you can test what you have written.

  • In addition to the full deployment described in Session bean deployment cycle, SilverStream also provides a command-line tool, SilverCmd QuickDeployEJB, that allows you to deploy small, incremental changes typical during development.

      For more information on using QuickDeployEJB, see the chapter on SilverCmd in the Facilities Guide of the server's Core Help.

Session bean deployment cycle

The deployment cycle for a session bean includes:

• Creating a SilverStream deployment plan in which you:

  • Add operational information about the bean--for example, the JNDI name

  • Map roles to principals, map interbean references, and so on

• Deploying the EJBs using SilverStream's graphical Deployment Plan Designer or command line tool SilverCmd DeployEJB

    For more information on deploying EJBs, see the chapter on J2EE archive deployment in the Facilities Guide of the server's Core Help.

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 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 EJB Examples database or see 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) 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 bean's 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 javax.ejb.CreateException and java.rmi.RemoteException

  • Return the remote interface type

  • For stateless session beans, have only a single create() method, which 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.

Programmer's Guide

Copyright © 2001, SilverStream Software, Inc. All rights reserved.