EJB.6.8 Stateless Session Beans

Stateless session beans are session beans whose instances have no conversational state. This means that all bean instances are equivalent when they are not involved in serving a client-invoked method.

The term "stateless" signifies that an instance has no state for a specific client. However, the instance variables of the instance can contain the state across client-invoked method calls. Examples of such states include an open database connection and an object reference to an EJB object.

The home interface of a stateless session bean must have one create method that takes no arguments and returns the session bean's remote interface. There can be no other create methods in the home interface. The session bean class must define a single ejbCreate method that takes no arguments.

Because all instances of a stateless session bean are equivalent, the container can choose to delegate a client-invoked method to any available instance. This means, for example, that the container may delegate the requests from the same client within the same transaction to different instances, and that the container may interleave requests from multiple transactions to the same instance.

A container only needs to retain the number of instances required to service the current client load. Due to client "think time," this number is typically much smaller than the number of active clients . Passivation is not needed for stateless sessions. The container creates another stateless session bean instance if one is needed to handle an increase in client work load. If a stateless session bean is not needed to handle the current client work load, the container can destroy it.

Because stateless session beans minimize the resources needed to support a large population of clients, depending on the implementation of the container, applications that use stateless session beans may scale somewhat better than those using stateful session beans. However, this benefit may be offset by the increased complexity of the client application that uses the stateless beans.

Clients use the create and remove methods on the home interface of a stateless session bean in the same way as on a stateful session bean. To the client, it appears as if the client controls the life cycle of the session object. However, the container handles the create and remove calls without necessarily creating and removing an EJB instance.

There is no fixed mapping between clients and stateless instances. The container simply delegates a client's work to any available instance that is method-ready.

A stateless session bean must not implement the javax.ejb.SessionSynchronization interface.

EJB.6.8.1 Stateless Session Bean State Diagram

When a client calls a method on a stateless session object, the container selects one of its method-ready instances and delegates the method invocation to it.

Figure EJB.6-7 illustrates the life cycle of a stateless session bean instance.

Figure EJB.6-7. Life Cycle of a Stateless Session Bean

The following steps describe the life cyle of a session bean instance:

• A stateless session bean instance's life starts when the container invokes newInstance() on the session bean class to create a new instance. Next, the container calls setSessionContext() followed by ejbCreate() on the instance. The container can perform the instance creation at any timethere is no relationship to a client's invocation of the create() method.

• The session bean instance is now ready to be delegated a business method call from any client.

• When the container no longer needs the instance (usually when the container wants to reduce the number of instances in the method-ready pool), the container invokes ejbRemove() on it. This ends the life of the stateless session bean instance.

EJB.6.8.2 Operations Allowed in the Methods of a Stateless Session Bean Class

Table EJB.6-2 defines the methods of a stateless session bean class in which the session bean instances can access the methods of the javax.ejb.SessionContext interface, the java:comp/env environment naming context, resource managers, and other enterprise beans.

If a session bean instance attempts to invoke a method of the SessionContext interface, and the access is not allowed in Table EJB.6-2, the container must throw the java.lang.IllegalStateException.

If a session bean instance attempts to access a resource manager or an enterprise bean and the access is not allowed in Table EJB.6-2, the behavior is undefined by the EJB architecture.

Table EJB.6-2. Operations Allowed in the Methods of a Stateless Session Bean

Bean Method	Bean Method Can Perform the Following Operations
	Container-Managed Transaction Demarcation	Bean-Managed Transaction Demarcation
constructor
setSessionContext	SessionContext methods: getEJBHome JNDI access to java:comp/env	SessionContext methods: getEJBHome JNDI access to java:comp/env
ejbCreate ejbRemove	SessionContext methods: getEJBHome, getEJBObject JNDI access to java:comp/env	SessionContext methods: getEJBHome, getEJBObject, getUserTransaction UserTransaction methods JNDI access to java:comp/env
business method from remote interface	SessionContext methods: getEJBHome, getCallerPrincipal, getRollbackOnly, isCallerInRole, setRollbackOnly, getEJBObject JNDI access to java:comp/env Resource manager access Enterprise bean access	SessionContext methods: getEJBHome, getCallerPrincipal, isCallerInRole, getEJBObject, getUserTransaction UserTransaction methods JNDI access to java:comp/env Resource manager access Enterprise bean access

Additional restrictions:

• The getRollbackOnly and setRollbackOnly methods of the SessionContext interface should be used only in the session bean methods that execute in the context of a transaction. The container must throw the java.lang.IllegalStateException if the methods are invoked while the instance is not associated with a transaction.

The reasons for disallowing operations in Table EJB.6-2:

• Invoking the getEJBObject method is disallowed in the session bean methods in which there is no session object identity associated with the instance.

• Invoking the getCallerPrincipal and isCallerInRole methods is disallowed in the session bean methods for which the container does not have a client security context.

• Invoking the getRollbackOnly and setRollbackOnly methods is disallowed in the session bean methods for which the container does not have a meaningful transaction context, and for all session beans with bean-managed transaction demarcation.

• Accessing resource managers and enterprise beans is disallowed in the session bean methods for which the container does not have a meaningful transaction context or client security context.

• The UserTransaction interface is unavailable to session beans with container-managed transaction demarcation.

EJB.6.8.3 Dealing with Exceptions

A RuntimeException thrown from any method of the enterprise bean class (including the business methods and the callbacks invoked by the container) results in the transition to the "does not exist" state. Exception handling is described in detail in Chapter EJB.12.

From the client perspective, the session object continues to exist. The client can continue accessing the session object because the container can delegate the client's requests to another instance.