Client View of a Session Bean Overview
For a client, a session object is a non-persistent object that implements some business logic running on the server. One way to think of a session object is as a logical extension of the client program that runs on the server. A session object is not shared among multiple clients.
A client NEVER directly accesses instances of the session bean's class. A client accesses a session object through the session bean's client view interface(s).
The client of a session bean may be a local client, a remote client, or a web service client, depending on the interface provided by the bean and used by the client.
A remote client of an session bean can be another enterprise bean deployed in the same or different container; or it can be an arbitrary Java program, such as an application, applet, or servlet. The client view of a session bean can also be mapped to non-Java client environments, such as CORBA clients that are not written in the Java programming language.
The interface used by a remote client of a session bean is implemented by the container as a remote business interface (or a remote EJBObject interface), and the remote client view of a session bean is location-independent. A client running in the same JVM as the session object uses the same API as a client running in a different JVM on the same or different machine.
Use of a session bean's local business interface(s) or local interface entails the collocation of the local client and the session. The local client of an enterprise bean must be collocated in the same container as the bean. The local client view IS NOT location-independent.
The client of a stateless session bean may be a web service client. Only a STATELESS session bean may provide a web service client view. A web service client makes use of the enterprise bean's web service client view, as described by a WSDL document. The bean's client view web service endpoint is in terms of a JAX-WS endpoint or JAX-RPC endpoint interface.
While it is possible to provide more than one client view for a session bean, typically only one will be provided.
From its creation until destruction, a session object lives in a container. The container provides security, concurrency, transactions, swapping to secondary storage, and other services for the session object transparently to the client.
Each session object has an identity which, in general, does not survive a crash and restart of the container, although a high-end container implementation can mask container and server crashes to a remote or web service client.
Multiple enterprise beans can be installed in a container. The container allows the clients of session beans that provide local or remote client views to obtain the business interfaces and/or home interfaces of the installed enterprise beans through dependency injection or to look them up via JNDI.
The client view of a session object is independent of the implementation of the session bean and the container.
Session Bean Component Contract Overview
A session bean instance is an instance of the session bean class. It holds the session object's state.
A session bean instance is an extension of the client that creates it:
In the case of a stateful session bean, its fields contain a conversational state on behalf of the session object's client. This state describes the conversation represented by a specific client/ session object pair.
It typically reads and updates data in a database on behalf of the client.
In the case of a STATEFUL session bean, its lifetime is controlled by the CLIENT.
A container may also terminate a session bean instance's life after a deployer-specified timeout or as a result of the failure of the server on which the bean instance is running. For this reason, a client should be prepared to recreate a new session object if it loses the one it is using.
Typically, a session object's conversational state is not written to the database. A session bean developer simply stores it in the session bean instance's fields and assumes its value is retained for the lifetime of the instance. A developer may use an extended persistence context to store a stateful session bean's persistent conversational state.
A session bean that does not make use of the Java Persistence API must explicitly manage cached database data. A session bean instance must write any cached database updates prior to a transaction completion, and it must refresh its copy of any potentially stale database data at the beginning of the next transaction. A session bean must also refresh any java.sql Statement objects before they are used in a new transaction context. Use of the Java Persistence API provides a session bean with automatic management of database data, including the automatic flushing of cached database updates upon transaction commit.
The container manages the life cycle of the session bean instances. It notifies the instances when bean action may be necessary, and it provides a full range of services to ensure that the session bean implementation is scalable and can support a large number of clients.
A session bean may be either:
stateless - the session bean instances contain NO conversational STATE between methods; ANY instance can be used for any client.
stateful - the session bean instances CONTAIN conversational STATE which must be retained across methods and transactions.
Conversational State of a Stateful Session Bean
The conversational state of a STATEFUL session object is defined as the session bean instance's field values, its associated interceptors and their instance field values, plus the transitive closure of the objects from these instances' fields reached by following Java object references.
To efficiently manage the size of its working set, a session bean container may need to temporarily transfer the state of an idle STATEFUL session bean instance to some form of secondary storage. The transfer from the working set to secondary storage is called instance passivation. The transfer back is called activation.
In advanced cases, a session object's conversational state may contain open resources, such as open sockets and open database cursors. A container cannot retain such open resources when a session bean instance is passivated. A developer of a stateful session bean must close and open the resources in the PrePassivate and PostActivate lifecycle callback interceptor methods.
A container may only passivate a stateful session bean instance when the instance is NOT in a transaction.
A container must not passivate a stateful session bean with an extended persistence context unless the following conditions are met:
All the entities in the persistence context are serializable.
The EntityManager is serializable.
A STATELESS session bean is NEVER passivated.
Instance Passivation and Conversational State
The Bean Provider is required to ensure that the PrePassivate method leaves the instance fields and the fields of its associated interceptors ready to be serialized by the container. The objects that are assigned to the instance's non-transient fields and the non-transient fields of its interceptors after the PrePassivate method completes must be one of the following.
A serializable object.
A reference to an enterprise bean's business interface.
A reference to an enterprise bean's remote interface, even if the stub class is not serializable.
A reference to an enterprise bean's remote home interface, even if the stub class is not serializable.
A reference to an entity bean's local interface, even if it is not serializable.
A reference to an entity bean's local home interface, even if it is not serializable.
A reference to the SessionContext object, even if it is not serializable.
A reference to the environment naming context (that is, the java:comp/env JNDI context) or any of its subcontexts.
A reference to the UserTransaction interface.
A reference to a resource manager connection factory.
A reference to a container-managed EntityManager object, even if it is not serializable.
A reference to an EntityManagerFactory object obtained via injection or JNDI lookup, even if it is not serializable.
A reference to a javax.ejb.Timer object.
An object that is not directly serializable, but becomes serializable by replacing the references to an enterprise bean's business interface, an enterprise bean's home and component interfaces, the references to the SessionContext object, the references to the java:comp/env JNDI context and its subcontexts, the references to the UserTransaction interface, and the references to the EntityManager and/or EntityManagerFactory by serializable objects during the object's serialization.
This means, for example, that the Bean Provider must close all JDBC connections in the PrePassivate method and assign the instance's fields storing the connections to null.
The Bean Provider must assume that the content of transient fields may be lost between the PrePassivate and PostActivate notifications. Therefore, the Bean Provider should not store in a transient field a reference to any of the following objects: SessionContext object; environment JNDI naming context and any its subcontexts; business interfaces; home and component interfaces; EntityManager interface; EntityManagerFactory interface; UserTransaction interface.