Jakarta® Enterprise Beans, Core Features

THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of the copyright holders or the Eclipse Foundation may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

The Enterprise JavaBeans 3.0 [29] architecture extended Enterprise JavaBeans to include the following new functionality and simplifications to the earlier Enterprise JavaBeans APIs:

The Enterprise Bean Provider (Bean Provider for short) is the producer of enterprise beans. His or her output is a set of one or more enterprise beans. These beans may be contained in a ejb-jar or may be contained directly in a .war file. The Bean Provider is responsible for the Java classes that implement the enterprise beans’ business methods; the definition of the beans’ client view interfaces, if any; and the declarative specification of the beans’ metadata. The beans’ metadata may take the form of metadata annotations applied to the bean classes and/or an external XML deployment descriptor. The beans’ metadata—whether expressed in metadata annotations or in the deployment descriptor—includes the structural information of the enterprise beans and declares all the enterprise beans’ external dependencies (e.g. the names and types of resources that the enterprise beans use).

The Enterprise Bean Provider is typically an application domain expert. The Bean Provider develops reusable enterprise beans that typically implement business tasks or business entities.

The Bean Provider is not required to be an expert at system-level programming. Therefore, the Bean Provider usually does not program transactions, concurrency, security, distribution, or other services into the enterprise beans. The Bean Provider relies on the container for these services.

A Bean Provider of multiple enterprise beans often performs the role of the Application Assembler.

The Application Assembler combines enterprise beans into larger deployable application units. The input to the Application Assembler is a set of enterprise beans, their interfaces, and metadata, as produced by the Bean Provider(s). The Bean Provider’s output may also simply be un-assembled enterprise beans that must be packaged in an ejb-jar file or .war file. The Application Assembler may insert the application assembly instructions into the deployment descriptors. The Application Assembler will create one or more ejb-jar and/or .war files from the input artifacts together with their application assembly instructions as needed.

All of the input could be combined into a single output ejb-jar file or .war file. Similarly, the input could also be split into multiple output ejb-jar and/or .war files. For example, the Application Assembler could combine ejb1.jar and ejb2.jar into ejb3.jar, combine ejb1.jar and web1.war into web2.war, split ejb1.jar into ejb2.jar and ejb3.jar, split web1.war into ejb1.jar and web2.jar, and so forth. Each output ejb-jar file or .war file is either a deployment unit intended for the Deployer or a partially assembled application that is intended for another Application Assembler.

The Application Assembler can also combine enterprise beans with other types of application components when composing an application.

The Enterprise Beans specification describes the case in which the application assembly step occurs before the deployment of the enterprise beans. However, the Enterprise Beans architecture does not preclude the case that application assembly is performed after the deployment of all or some of the enterprise beans.

The Application Assembler is a domain expert who composes applications that use enterprise beans. The Application Assembler works with the enterprise beans’ metadata annotations and/or deployment descriptor and the enterprise beans’ client-view contract. Although the Assembler must be familiar with the functionality provided by the enterprise beans’ client-view, he or she does not need to have any knowledge of the enterprise beans’ implementation.

The Deployer takes one or more ejb-jar files and/or .war file produced by a Bean Provider or Application Assembler and deploys the enterprise beans contained in the ejb-jar files or .war files in a specific operational environment. The operational environment includes an Enterprise Beans container and server.

The Deployer must resolve all the external dependencies declared by the Bean Provider (e.g. the Deployer must ensure that all resource manager connection factories used by the enterprise beans are present in the operational environment, and he or she must bind them to the resource manager connection factory references declared in the metadata annotations or deployment descriptor), and must follow the application assembly instructions defined by the Application Assembler. To perform his or her role, the Deployer uses tools provided by the Container Provider.

The Deployer’s output is a set of enterprise beans (or an assembled application that includes enterprise beans) that have been customized for the target operational environment, and that are deployed in a specific Enterprise Beans container.

The Deployer is an expert at a specific operational environment and is responsible for the deployment of enterprise beans. For example, the Deployer is responsible for mapping the security roles defined by the Bean Provider or Application Assembler to the user groups and accounts that exist in the operational environment in which the enterprise beans are deployed.

The Deployer uses tools supplied by the Container Provider to perform the deployment tasks. The deployment process is typically two-stage:

In some cases, a qualified Deployer may customize the business logic of the enterprise beans at their deployment. Such a Deployer would typically use the Container Provider’s tools to write relatively simple application code that wraps the enterprise beans’ business methods.

The Enterprise Beans Server Provider (Server Provider for short) is a specialist in the area of distributed transaction management, distributed objects, and other lower-level system-level services.

The current Enterprise Beans architecture assumes that the Server Provider and the Container Provider roles are the same vendor. Therefore, it does not define any interface requirements for the Server Provider.

The Enterprise Beans Container Provider (Container Provider for short) provides:

From the perspective of the enterprise beans, the container is a part of the target operational environment. The container runtime provides the deployed enterprise beans with transaction and security management, network distribution of remote clients, scalable management of resources, and other services that are generally required as part of a manageable server platform.

The "Enterprise Beans Container Provider’s responsibilities" defined by the Enterprise Beans architecture are meant to be requirements for the implementation of the Enterprise Beans container and server. Since the Enterprise Beans specification does not architect the interface between the Enterprise Beans container and server, it is left up to the vendor how to split the implementation of the required functionality between the Enterprise Beans container and server.

The expertise of the Container Provider is system-level programming, possibly combined with some application-domain expertise. The focus of a Container Provider is on the development of a scalable, secure, transaction-enabled container that is integrated with an Enterprise Beans server. The Container Provider insulates the enterprise bean from the specifics of an underlying Enterprise Beans server by providing a simple, standard API between the enterprise bean and the container. This API is the Enterprise Beans component contract.

The Container Provider typically provides support for versioning the installed enterprise bean components. For example, the Container Provider may allow enterprise bean classes to be upgraded without invalidating existing clients or losing existing enterprise bean objects.

The Container Provider typically provides tools that allow the System Administrator to monitor and manage the container and the beans running in the container at runtime.

The System Administrator is responsible for the configuration and administration of the enterprise’s computing and networking infrastructure that includes the Enterprise Beans server and container. The System Administrator is also responsible for overseeing the well-being of the deployed enterprise beans applications at runtime.

The essential characteristics of an enterprise bean are:

The enterprise bean architecture is flexible enough to implement the following:

Enterprise beans that are remotely accessible components are intended to be relatively coarse-grained business objects or services (e.g. shopping cart, stock quote service). In general, fine-grained objects should not be modeled as remotely accessible components.

Although the state management protocol defined by the Enterprise Beans architecture is simple, it provides an enterprise bean developer great flexibility in managing a bean’s state.

A typical session object has the following characteristics:

A typical Enterprise Beans container provides a scalable runtime environment to execute a large number of session objects concurrently.

The Enterprise Beans specification defines stateful, stateless, and singleton session beans. There are differences in the API between stateful session beans, stateless session beans, and singleton session beans.

A typical message-driven object has the following characteristics:

A typical Enterprise Beans container provides a scalable runtime environment to execute a large number of message-driven objects concurrently.

A typical entity object has the following characteristics:

See the Enterprise Beans Optional Features [2] document for details.

The remote client view of an enterprise bean is location independent. A client running in the same JVM as a bean instance uses the same API to access the bean as a client running in a different JVM on the same or different machine.

The arguments and results of the methods of the remote interfaces are passed by value.

For a session bean client and component written to the Enterprise Beans 3.x API, a remote client accesses a session bean through the bean’s remote business interface. For a session bean client and component written to the Enterprise Beans 2.1 and earlier APIs, the remote client accesses the session bean through the session bean’s remote home and remote component interfaces.

Compatibility Note: The Enterprise Beans 2.1 and earlier API required that a remote client access the stateful or stateless session bean by means of the session bean’s remote home and remote component interfaces. These interfaces remain available for use with Enterprise Beans 3.x beans, and are described in Remote and Local Client View of Session Beans Written to the Enterprise Beans 2.1 Client View API.

Session beans may have local clients. A local client is a client that is collocated in the same JVM with the session bean that provides the local client view and which may be tightly coupled to the bean. A local client of a session bean may be another enterprise bean or a web component.

Access to an enterprise bean through the local client view requires the collocation in the same JVM of both the local client and the enterprise bean that provides the local client view. The local client view therefore does not provide the location transparency provided by the remote client view.

Access to an enterprise bean through the local client view is only required to be supported for local clients packaged within the same application as the enterprise bean that provides the local client view. Compliant implementations of this specification may optionally support access to the local client view of an enterprise bean from a local client packaged in a different application. The configuration requirements for inter-application access to the local client view are vendor-specific and are outside the scope of this specification. Applications relying on inter-application access to the local client view are non-portable.

The arguments and results of the methods of the local client view are passed "by reference".^[2] Enterprise beans that provide a local client view should therefore be coded to assume that the state of any Java object that is passed as an argument or result is potentially shared by caller and callee.

For a session bean client and component written to the Enterprise Beans 3.x API, a local client accesses a session bean through the bean’s local business interface or through a no-interface client view representing all non-static public methods of the bean class. For a session bean client and component written to the Enterprise Beans 2.1 and earlier APIs, the local client accesses the enterprise bean through the bean’s local home and local component interfaces. The container object that implements a local interface or the no-interface local view is a local Java object.

Compatibility Note: The Enterprise Beans 2.1 and earlier API required that a local client access a stateful or stateless session bean by means of the session bean’s local home and local component interfaces. These interfaces remain available for use with Enterprise Beans 3.x beans, and are described in Remote and Local Client View of Session Beans Written to the Enterprise Beans 2.1 Client View API.

The following considerations should be taken into account in determining whether a local or remote access should be used for an enterprise bean.

The choice between the local and the remote programming model is a design decision that the Bean Provider makes when developing the enterprise bean.

While it is possible to provide both a remote client view and a local client view for an enterprise bean, more typically only one or the other will be provided.

Stateless session beans and singleton session beans may have web service clients.

A web service client accesses a session bean through the web service client view. The web service client view is described by the WSDL document for the web service that the bean implements. WSDL is an XML format for describing a web service as a set of endpoints operating on messages. The abstract description of the service is bound to an XML based protocol (SOAP [11]) and underlying transport (HTTP or HTTPS) by means of which the messages are conveyed between client and server. (See references [12], [6], [5], [4]).

The web service methods of a session bean provide the basis of the web service client view of the bean that is exported through WSDL. See reference [6] for a description of how Java language metadata annotations may be used to specify a session bean’s web services client view.

A bean’s web service client view may be initially defined by a WSDL document and then mapped to a web service endpoint that conforms to this, or an existing bean may be adapted to provide a web service client view. Reference [5] describes various design-time scenarios that may be used for Enterprise Beans web service endpoints.

Compatibility Note: Enterprise Beans 2.1 required the Bean Provider to define a web service endpoint interface for a stateless session bean when he or she wished to expose the functionality of the bean as a web service endpoint through WSDL. This requirement to define the web service endpoint interface is removed in Enterprise Beans 3.0 and later. See [6].

The web service client view of an enterprise bean is location independent and remotable.

Web service clients may be Java clients and/or clients not written in the Java programming language. A web service client that is a Java client accesses the web service by means of the Jakarta XML Web Services client APIs. Access through web service clients occurs through SOAP 1.1, SOAP 1.2 or plain XML over HTTP(S).

While it is possible to provide a web service client view in addition to other client views for an enterprise bean, more typically only one will be provided. There is no prohibition against using the same interface as both a remote business interface and a web service endpoint interface. In that case it is the Bean Provider’s responsibility to ensure that the interface conforms to the type requirements of each client view through which it is exposed.

A client can obtain a session bean’s business interface through dependency injection or lookup in the JNDI namespace.

For example, the business interface Cart for the CartBean session bean may be obtained using dependency injection as follows:

The Cart business interface could also be looked up using JNDI as shown in the following code segment using the lookup method provided by the EJBContext interface. In this example, a reference to the client bean’s SessionContext object is obtained through dependency injection:

In both cases, the syntax used in obtaining the reference to the Cart business interface is independent of whether the business interface is local or remote. In the case of remote access, the actual location of a referenced enterprise bean and Enterprise Beans container are, in general, transparent to the client using the remote business interface of the bean.

A client can obtain a reference to a session bean’s no-interface view through dependency injection or lookup in the JNDI namespace.

For example, the no-interface view of the CartBean session bean with bean class com.acme.CartBean may be obtained using dependency injection as follows:

The CartBean no-interface view could also be looked up via JNDI as shown in the following code segment using the lookup method provided by the EJBContext interface. In this example, a reference to the client bean’s SessionContext object is obtained through dependency injection:

Despite the fact that the client reference for the no-interface view has the type of the bean class, the client never directly uses the new operator to acquire the reference.

The session bean’s business interface is an ordinary Java interface. It contains the business methods of the session bean.

A reference to a session bean’s business interface may be passed as a parameter or return value of a business interface method. If the reference is to a session bean’s local business interface, the reference may only be passed as a parameter or return value of a local business interface method or a no-interface view method.

The business interface of a stateful session bean typically contains a method to initialize the state of the session object and a method to indicate that the client has finished using the session object and that it can be removed. See Session Bean Component Contract.

It is invalid to reference a session object that does not exist. If a stateful session bean has been removed, attempted invocations on the stateful session bean business interface result in the jakarta.ejb.NoSuchEJBException.^[3] If a singleton session bean did not successfully initialize, attempted invocations on the singleton session bean business interface result in the jakarta.ejb.NoSuchEJBException.

The container provides an implementation of a session bean’s business interface such that when the client invokes a method on the instance of the business interface, the business method on the session bean instance and any interceptor methods are invoked as needed.

The container makes the session bean’s business interface available to the Enterprise Beans 3.x client through dependency injection and through lookup in the JNDI namespace. Enterprise Bean References describes in further detail how clients can obtain references to Enterprise Beans business interfaces.

A session bean’s no-interface view is a variation of the local view that exposes the non-static public methods of the bean class without the use of a separate business interface.

A reference to the no-interface view may be passed as a parameter or return value of any local business interface or no-interface view method.

The container provides an implementation of a reference to a no-interface view such that when the client invokes a method on the reference, the business method on the session bean instance and any interceptor methods are invoked as needed. As with the session bean remote and local views, a client acquires a no-interface view reference via lookup or injection only. A client does not directly instantiate (use the new operator on) the bean class to acquire a reference to the no-interface view.

Only public methods of the bean class and of any superclasses except java.lang.Object may be invoked through the no-interface view. Attempted invocations of methods with any other access modifiers via the no-interface view reference must result in the jakarta.ejb.EJBException.

When interacting with a reference to the no-interface view, the client must not make any assumptions regarding the internal implementation of the reference, such as any instance-specific state that may be present in the reference. Although the reference object is type-compatible with the corresponding bean class type, there is no prescribed relationship between the internal implementation of the reference and the implementation of the bean instance.

The developer of an enterprise bean that exposes a no-interface view must not make any assumptions about the number of times the bean class no-arg constructor will be called. For example, it is possible that the acquisition of a client reference to the no-interface view will result in the invocation of the bean class constructor. It is recommended that the Bean Provider place component initialization logic in a PostConstruct method instead of the bean class no-arg constructor.

It is invalid to reference a session object that does not exist. If a stateful session bean has been removed, attempted invocations on the no-interface view reference must result in the jakarta.ejb.NoSuchEJBException. If a singleton session bean did not successfully initialize, attempted invocations on the singleton session bean’s no-interface view reference result in the jakarta.ejb.NoSuchEJBException.

From the point of view of the client, a session object exists once the client has obtained a reference to its business interface—whether through dependency injection or from lookup of the business interface in JNDI.

A client that has a reference to a session object’s business interface can then invoke business methods on the interface and/or pass the reference as a parameter or return value of a business interface method.^[4]

A client may remove a stateful session bean by invoking a method of its business interface designated as a Remove method.

The lifecycle of a stateless session bean does not require that it be removed by the client. Removal of a stateless session bean instance is performed by the container, transparently to the client.

The lifecycle of a singleton session bean does not require that it be removed by the client. Removal of a singleton session bean instance is performed by the container, transparently to the client.

The contracts for session bean lifecycle are described in Session Bean Component Contract.

An example of the session bean runtime objects is illustrated by the following diagram:

A client obtains a reference to a Cart session object, which provides a shopping service, by means of dependency injection or using JNDI lookup. The client then uses this session object to fill the cart with items and to purchase its contents. Cart is a stateful session.

In this example, the client obtains a reference to the Cart’s business interface through dependency injection. The client then uses the business interface to initialize the session object and add a few items to it. The startShopping method is a business method that is provided for the initialization of the session object.

Finally the client purchases the contents of the shopping cart, and finishes the shopping activity.^[5]

A client can test two Enterprise Beans 3.x remote or local view references for identity by means of the Object.equals and Object.hashCode methods.

By default, session bean invocations through the remote, local, and no-interface views are synchronous. The client blocks for the duration of the invocation and is returned control only after all invocation processing has completed. Clients can achieve asynchronous invocation behavior by invoking session bean methods that have been designed to support asynchrony.

When a client invokes an asynchronous method, the container returns control to the client immediately and continues processing the invocation on a separate thread of execution.

The client should expect to receive a system exception (in the form of the jakarta.ejb.EJBException) on the client thread if the container has problems allocating the internal resources required to support the asynchronous method.^[6] If a system exception is received on the client thread, the client can expect that the container will not be able to dispatch the asynchronous method. The client may wish to retry the asynchronous method at a later time.

If no system exception is received, the client can expect that the container will make an attempt to dispatch the asynchronous method. An exception resulting from the asynchronous method execution (e.g. an authorization failure, transaction commit failure, application exception, etc.) will be available via the Future<V> object.

It is permissible to acquire a session bean reference and attempt to invoke the same reference object concurrently from multiple threads. However, the resulting client behavior on each thread depends on the concurrency semantics of the target bean. See Serializing Session Bean Methods and Singleton Session Bean Concurrency for details of the concurrency behavior for session beans.

The Jakarta XML Web Services client obtains a reference to the service instance of the jakarta.xml.ws.Service class through dependency injection or using JNDI. The service class can be a generic jakarta.xml.ws.Service class or a generated service class which extends the jakarta.xml.ws.Service class. The service instance is then used to obtain a port object for the web service endpoint. The mechanisms and APIs for client web service access are described in the Jakarta XML Web Services [4] specification and in the Jakarta Enterprise Web Services [5] specification.

The following example illustrates how a Jakarta XML Web Services client obtains a reference to a web service endpoint, obtains a port object for the web service endpoint, and invokes a method on that endpoint.

The use of service references and the WebServiceRef annotation are described in further detail in [4].

The Enterprise Beans 2.1 and earlier specifications required that the client first obtain a reference to a session bean’s home interface, and then use the home interface to obtain a reference to the bean’s component interface. This earlier programming model continues to be supported by this specification. Both dependency injection and use of the EJBContext lookup method may be used as an alternative to the JNDI APIs to obtain a reference to the home interface.

For example, an Enterprise Beans 3.x client, com.acme.example.MySessionBean, might obtain a reference to a bean’s home interface as follows:

This home interface could be looked up in JNDI using the EJBContext lookup method as shown in the following code segment:

When the EJBContext lookup method is used to look up a home interface, the use of javax.rmi.PortableRemoteObject.narrow is not required.

The following code segments illustrate how the home interface is obtained when the JNDI APIs are used directly, as was required in the Enterprise Beans 2.1 programming model. For example, the remote home interface for the Cart session bean can be located using the following code segment:

If the Cart session bean provides a local client view instead of a remote client view and CartHome is a local home interface, this lookup might be as follows:

This section is specific to session beans that provide a remote client view using the remote component interface and remote home interface.

The container provides the implementation of the remote home interface for each session bean that defines a remote home interface that is deployed in the container. The object that implements a session bean’s remote home interface is called a session EJBHome object. The container makes the session bean’s remote home interface available to the client through dependency injection or through lookup in the JNDI namespace.

The remote home interface allows a client to do the following:

The life cycle of the distributed object implementing the remote home interface (the EJBHome object) or the local Java object implementing the local home interface (the EJBLocalHome object) is container-specific. A client application should be able to obtain a home interface, and then use it multiple times, during the client application’s lifetime.

A client can pass a remote home object reference to another application. The receiving application can use the home interface in the same way that it would use a remote home object reference obtained via JNDI.

This section is specific to session beans that provide a local client view using the local component interface and local home interface.

The container provides the implementation of the local home interface for each session bean that defines a local home interface that is deployed in the container. The object that implements a session bean’s local home interface is called a session EJBLocalHome object. The container makes the session bean’s local home interface available to the client through JNDI.

The local home interface allows a local client to do the following:

A client can pass a local home object reference to another application through its local component interface. A local home object reference cannot be passed as an argument or result of a method on an enterprise bean’s remote home or remote component interface.

A remote or local client that uses the Enterprise Beans 2.1 client view APIs uses the session bean’s component interface to access a session bean instance. The class that implements the session bean’s component interface is provided by the container. Instances of a session bean’s remote component interface are called session EJBObjects. Instances of a session bean’s local component interface are called session EJBLocalObjects.

A session EJBObject supports:

A session EJBLocalObject supports:

The implementation of the methods defined in the jakarta.ejb.EJBObject and jakarta.ejb.EJBLocalObject interfaces is provided by the container. They are not delegated to the instances of the session bean class.

From the point of view of a local or remote client using the Enterprise Beans 2.1 and earlier client view API, the life cycle of a session object is illustrated below.

A session object does not exist until it is created. When a client creates a session object, the client has a reference to the newly created session object’s component interface.

An example of the session bean runtime objects is illustrated by the following diagram:

A client creates a remote Cart session object, which provides a shopping service, using a create<METHOD> method of the Cart’s remote home interface. The client then uses this session object to fill the cart with items and to purchase its contents.

Suppose that the end-user wishes to start the shopping session, suspend the shopping session temporarily for a day or two, and later complete the session. The client might implement this feature by getting the session object’s handle, saving the serialized handle in persistent storage, and using it later to reestablish access to the original Cart.

For the following example, we start by looking up the Cart’s remote home interface in JNDI. We then use the remote home interface to create a Cart session object and add a few items to it:

Next we decide to complete this shopping session at a later time so we serialize a handle to this cart session object and store it in a file:

Finally we deserialize the handle at a later time, re-create the reference to the cart session object, and purchase the contents of the shopping cart:

Session objects are intended to be private resources used only by the client that created them. For this reason, session objects, from the client’s perspective, appear anonymous. Session objects do not expose their identity as a primary key, on the opposite, they hide their identity. As a result, the EJBObject.getPrimaryKey() method results in a java.rmi.RemoteException and the EJBLocalObject.getPrimaryKey() method results in a jakarta.ejb.EJBException, and the EJBHome.remove(Object primaryKey) and the EJBLocalHome.remove(Object primaryKey) methods result in a jakarta.ejb.RemoveException if called on a session bean. If the EJBMetaData.getPrimaryKeyClass() method is invoked on a EJBMetaData object for a session bean, the method throws the java.lang.RuntimeException.Since all session objects hide their identity, there is no need to provide a finder for them. The home interface of a session bean must not define any finder methods.

A session object handle can be held beyond the life of a client process by serializing the handle to persistent storage. When the handle is later deserialized, the session object it returns will work as long as the session object still exists on the server. (An earlier timeout or server crash may have destroyed the session object.) A handle is not a capability, in the security sense, that would automatically grant its holder the right to invoke methods on the object. When a reference to a session object is obtained from a handle, and then a method on the session object is invoked, the container performs the usual access checks based on the caller’s principal.

A client program that is intended to be interoperable with all compliant Enterprise Beans container implementations must use the javax.rmi.PortableRemoteObject.narrow method to perform type-narrowing of the client-side representations of the remote home and remote component interfaces.^[9]

Note: Programs using the cast operator for narrowing the remote component interface and remote home interface are likely to fail if the container implementation uses RMI-IIOP as the underlying communication transport.

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.

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 last bulleted item covers cases such as storing Collections of component interfaces in the conversational state.

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.

The restrictions on the use of transient fields ensure that containers can use Java Serialization during passivation and activation.

The following are the requirements for the container.

The container performs the Java programming language Serialization (or its equivalent) of the instance’s state (and its interceptors’ state) after it invokes the PrePassivate method on the instance and its interceptors.

The container must be able to properly save and restore the reference to the business interfaces and home and component interfaces of the enterprise beans stored in the instance’s state even if the classes that implement the object references are not serializable.

The container may use, for example, the object replacement technique that is part of the java.io.ObjectOutputStream and java.io.ObjectInputStream protocol to externalize the home and component references.

The container must be able to properly save and restore references to timers stored in the instance’s state even if the classes that implement the timers are not serializable.

If the session bean instance stores in its conversational state an object reference to the jakarta.ejb.SessionContext interface, the container must be able to save and restore the reference across the instance’s passivation. The container can replace the original SessionContext object with a different and functionally equivalent SessionContext object during activation.

If the session bean instance stores in its conversational state an object reference to the java:comp/env JNDI context or its subcontext, the container must be able to save and restore the object reference across the instance’s passivation. The container can replace the original object with a different and functionally equivalent object during activation.

If the session bean instance stores in its conversational state an object reference to the UserTransaction interface, the container must be able to save and restore the object reference across the instance’s passivation. The container can replace the original object with a different and functionally equivalent object during activation.

If the session bean instance stores in its conversational state an object reference to a container-managed EntityManager or to an EntityManagerFactory obtained via injection or JNDI lookup, the container must be able to save and restore the object reference across the instance’s passivation.

The container may destroy a session bean instance if the instance does not meet the requirements for serialization after PrePassivate.

While the container is not required to use the Serialization protocol for the Java programming language to store the state of a passivated session instance, it must achieve the equivalent result. The one exception is that containers are not required to reset the value of transient fields during activation.^[15] Declaring the session bean’s fields as transient is, in general, discouraged.

A session object’s conversational state is not transactional. It is not automatically rolled back to its initial state if the transaction in which the object has participated rolls back.

If a rollback could result in an inconsistency between a session object’s conversational state and the state of the underlying database, the bean developer (or the application development tools used by the developer) must use the afterCompletion notification to manually reset its state.

A session bean must be annotated or denoted in the deployment descriptor as a stateless, stateful, or singleton session bean. A stateless session bean must be annotated with the Stateless annotation or denoted in the deployment descriptor as a stateless session bean. A stateful session bean must be annotated with the Stateful annotation or denoted in the deployment descriptor as a stateful session bean. A singleton session bean must be annotated with the Singleton annotation or denoted in the deployment descriptor as a singleton session bean. The Stateful, Singleton, and Stateless annotations are component-defining annotations and are applied to the bean class.

A session bean may use dependency injection mechanisms to acquire references to resources or other objects in its environment (see Enterprise Bean Environment). If a session bean makes use of dependency injection, the container injects these references after the bean instance is created, and before any business methods are invoked on the bean instance. If a dependency on the SessionContext is declared, or if the bean class implements the optional SessionBean interface (see The SessionBean Interface), the SessionContext is also injected at this time. If dependency injection fails, the bean instance is discarded.

If the bean specifies a dependency on the SessionContext interface (or if the bean class implements the SessionBean interface), the container must provide the session bean instance with a SessionContext object. This gives the session bean instance access to the instance’s context maintained by the container. The SessionContext interface has the following methods:

The following lifecycle event callbacks are supported for session beans. With the exception of AroundConstruct lifecycle callback interceptors (see [15]), all interceptor methods may be defined directly on the bean class or on a separate interceptor class. See Lifecycle Callback Interceptor Methods and Interceptors.

The PostConstruct callback invocations occur before the first business method invocation on the bean instance. This is at a point after which any dependency injection has been performed by the container.

The PostConstruct lifecycle callback interceptor methods execute in an unspecified security context.

The PostConstruct lifecycle callback interceptor methods for a stateless session bean execute in an unspecified transaction context. The PostConstruct lifecycle callback interceptor methods for a singleton session bean execute in a transaction context determined by the bean’s transaction management type and any applicable transaction attribute. The PostConstruct lifecycle callback interceptor methods for a stateful session bean execute in a transaction context determined by the lifecycle callback method’s transaction attribute.

The PreDestroy callback notification signals that the instance is in the process of being removed by the container. In the PreDestroy lifecycle callback interceptor methods, the instance typically releases the resources that it has been holding.

The PreDestroy lifecycle callback interceptor methods execute in an unspecified security context.

The PreDestroy lifecycle callback interceptor methods for a stateless session bean execute in an unspecified transaction context. The PreDestroy lifecycle callback interceptor methods for a singleton session bean execute in a transaction context determined by the bean’s transaction management type and any applicable transaction attribute. The PreDestroy lifecycle callback interceptor methods for a stateful bean execute in a transaction context determined by the lifecycle callback method’s transaction attribute.

The PrePassivate and PostActivate lifecycle callback interceptor methods are only called on a stateful session bean instance if the bean is passivation capable. By default a stateful session bean is passivation capable. See Disabling Passivation of Stateful Session Beans on how to disable passivation of a stateful session bean.

The PrePassivate callback notification signals the intent of the container to passivate the instance. The PostActivate notification signals the instance it has just been reactivated. Because containers automatically maintain the conversational state of a stateful session bean instance when it is passivated, these notifications are not needed for most session beans. Their purpose is to allow stateful session beans to maintain those open resources that need to be closed prior to an instance’s passivation and then reopened during an instance’s activation.

The PrePassivate and PostActivate lifecycle callback interceptor methods execute in an unspecified security context.

The PrePassivate and PostActivate lifecycle callback interceptor methods execute in a transaction context determined by the lifecycle callback method’s transaction attribute.

The session bean class is not required to implement the SessionBean interface or the Serializable interface. Interceptor classes for the bean are likewise not required to implement the Serializable interface.

Compatibility Note: The SessionBean interface was required to be implemented by the session bean class in earlier versions of the Enterprise Beans specification. Under the Enterprise Beans 3.x API, the functionality previously provided by the SessionBean interface is available to the bean class through selective use of dependency injection (of the SessionContext) and optional lifecycle callback interceptor methods.

The SessionBean interface defines four methods: setSessionContext, ejbRemove, ejbPassivate, and ejbActivate.

The setSessionContext method is called by the bean’s container to associate a session bean instance with its context maintained by the container. Typically a session bean instance retains its session context as part of its state.

The ejbRemove notification signals that the instance is in the process of being removed by the container. In the ejbRemove method, the instance typically releases the same resources that it releases in the ejbPassivate method.

The ejbPassivate notification signals the intent of the container to passivate the instance. The ejbActivate notification signals the instance it has just been reactivated. Their purpose is to allow stateful session beans to maintain those open resources that need to be closed prior to an instance’s passivation and then reopened during an instance’s activation. The ejbPassivate and ejbActivate methods are only called on stateful session bean instances.

This specification requires that the ejbRemove, ejbActivate, and ejbPassivate methods of the SessionBean interface, and the ejbCreate method of a stateless session bean be treated as PreDestroy, PostActivate, PrePassivate and PostConstruct life cycle callback interceptor methods, respectively.

If the session bean implements the SessionBean interface, the PreDestroy annotation on the bean class can only be applied to the ejbRemove method; the PostActivate annotation can only be applied to the ejbActivate method; the PrePassivate annotation can only be applied to the ejbPassivate method. Similar requirements apply to use of deployment descriptor metadata as an alternative to the use of annotations.

A stateful session bean class can optionally implement the jakarta.ejb.SessionSynchronization interface or annotate methods using the individual AfterBegin, BeforeCompletion, and AfterCompletion annotations. The deployment descriptor may also be used to declare the individual session synchronization methods. These provide the session bean instances with transaction synchronization notifications. The instances can use these notifications, for example, to manage database data they may cache within transactions—e.g., if Jakarta Persistence is not used. A stateful session bean class may use either the jakarta.ejb.SessionSynchronization interface or the session synchronization annotations, but not both. If annotation are used, there must be at most one AfterBegin method, one BeforeCompletion method, and one AfterCompletion method for the bean.

The afterBegin notification signals a session bean instance that a new transaction has begun. The container invokes this method before the first business method within a transaction (which is not necessarily at the beginning of the transaction). The afterBegin notification is invoked with the transaction context. The instance may do any database work it requires within the scope of the transaction.

The beforeCompletion notification is issued when a session bean instance’s client has completed work on its current transaction but prior to committing the resource managers used by the instance. At this time, the instance should write out any database updates it has cached. The instance can cause the transaction to roll back by invoking the setRollbackOnly method on its SessionContext object.

The afterCompletion notification signals that the current transaction has completed. A completion status of true indicates that the transaction has committed. A status of false indicates that a rollback has occurred. Since a session bean instance’s conversational state is not transactional, it may need to manually reset its state if a rollback occurred.

All Container Providers must support the session synchronization notifications. If a bean class implements the SessionSynchronization interface, the container must invoke the afterBegin, beforeCompletion, and afterCompletion notifications as required by the specification. If the bean implementor uses the session synchronization annotations, the container must invoke only the notifications corresponding to the annotations that have been used.

If a stateful session bean’s PostConstruct, PreDestroy, PrePassivate or PostActivate lifecycle callback interceptor method is invoked in the scope of a transaction, session synchronization callbacks for the transaction are not called on the bean instance.

A session synchronization method can have public, private, protected, or package level access. A session synchronization method must not be declared as final or static.

Only a stateful session bean with container-managed transaction demarcation can receive session synchronization notifications. Stateless session beans and singleton session beans must not implement the SessionSynchronization interface or use the session synchronization annotations.

There is no need for a session bean with bean-managed transaction demarcation to rely on the synchronization call backs because the bean is in control of the commit—the bean knows when the transaction is about to be committed and it knows the outcome of the transaction commit.

A stateless session bean or singleton session bean can be registered with the Enterprise Beans Timer Service for time-based event notifications. The container invokes the appropriate bean instance timeout callback method when a timer for the bean has expired. See Timer Service. Stateful session beans cannot be registered with the Enterprise Beans Timer Service, and therefore should not implement timeout callback methods.

The session bean’s business interface, no-interface view, component interface, or web service endpoint defines the business methods callable by a client.

Except as noted below, the container creates an instance of a session bean as follows. First, the container calls the bean class constructor to create a new session bean instance. Second, the container performs any dependency injection as specified by metadata annotations on the bean class or by the deployment descriptor. This includes the bean’s SessionContext, if applicable. Third, the container calls the PostConstruct lifecycle callback interceptor methods for the bean, if any. The additional steps described below in Stateful Session Beans and Stateless Session Beans apply if the session bean is invoked through the Enterprise Beans 2.1 client view APIs.

If an interceptor associated with the session bean declares an AroundConstruct lifecycle callback interceptor method, the container follows the rules for the AroundConstruct interceptors defined in the Jakarta® Interceptors specification [15].

A stateful session bean written to the Enterprise Beans 3.x API typically has one or more remove methods designated by means of the Remove annotation or remove-method deployment descriptor element.^[17] Invocation of the remove method causes the removal of the stateful session bean after the remove method successfully completes. If the Remove annotation specifies the value of retainIfException as true and the invocation of the Remove method throws an application exception, the instance is not removed. The retain-if-exception subelement of the remove-method deployment descriptor element may be explicitly specified to override the retainIfException value specified or defaulted by the Remove annotation. The default value of the retainIfException element is false. If there are multiple remove methods, their retainIfException values can differ.

A Bean Provider or Deployer may optionally assign a timeout value to a stateful session bean. The stateful session bean timeout is specified using the StatefulTimeout annotation on the bean class. It may also be specified using the stateful-timeout deployment descriptor element. If both are specified, the deployment descriptor value overrides that of the annotation.

The timeout value is the amount of time a stateful session bean instance is permitted to remain idle (not receive any client invocations) before being removed by the container. A timeout value of -1 indicates that the bean must not be removed due to timeout for as long as the application is deployed. A timeout value of 0 indicates that the bean is immediately eligible for removal after becoming idle.

If a stateful session bean timeout is not designated using this standard metadata, the container determines when to end the lifetime of the bean, possibly based on vendor-specific configuration. The details of such configuration are beyond the scope of the specification.

A stateful session bean instance must not be removed due to timeout while it is associated with a transaction or while it is processing a business method or callback. The full stateful session bean life cycle is covered in Stateful Session Beans.

The AroundInvoke interceptor methods are supported for session beans. These interceptor methods may be defined on the bean class and/or on interceptor classes, and apply to the handling of the invocation of the business methods of the bean’s business interface, no-interface view, component interface, and/or web service endpoint.

For stateful session beans that use the session synchronization notifications, the afterBegin notification occurs before any AroundInvoke method invocations, and the beforeCompletion notification occurs after all AroundInvoke invocations have finished.

Interceptors are described in Interceptors.

The following requirements apply to stateless and stateful session beans. See Singleton Session Bean Concurrency for singleton session bean concurrency requirements.

The container serializes calls to each stateful and stateless session bean instance. Most containers will support many instances of a session bean executing concurrently; however, each instance sees only a serialized sequence of method calls. Therefore, a stateful or stateless session bean does not have to be coded as reentrant.

The container must serialize all the container-invoked callbacks (that is, the business method interceptor methods, lifecycle callback interceptor methods, timeout callback methods, beforeCompletion methods, and so on), and it must serialize these callbacks with the client-invoked business method calls.

By default, clients are allowed to make concurrent calls to a stateful session object and the container is required to serialize such concurrent requests. Note that the container never permits multi-threaded access to the actual stateful session bean instance. For this reason, Read/Write method locking metadata, as well as the bean-managed concurrency mode, are not applicable to stateful session beans and must not be used.^[18] See Singleton Session Bean Concurrency for a description of how these concurrency modes and locking types apply to singleton session beans.

The Bean Provider may optionally specify that concurrent client requests to a stateful session bean are prohibited. This is done using the AccessTimeout annotation or the access-timeout deployment descriptor element with a value of 0. In this case, if a client-invoked business method is in progress on an instance when another client-invoked call, from the same or different client, arrives at the same stateful session bean istance, if the second client is a client of the bean’s business interface or no-interface view, the concurrent invocation must result in the second client receiving the jakarta.ejb.ConcurrentAccessException.^[19] If the Enterprise Beans 2.1 client view is used, the container must throw the java.rmi.RemoteException if the second client is a remote client, or the jakarta.ejb.EJBException if the second client is a local client.

There is no need for any restrictions against concurrent client access to stateless session beans because the container routes each request to a different instance of the stateless session bean class.

The following session bean methods are invoked in the scope of a transaction determined by the transaction attribute specified in the bean’s metadata annotations or deployment descriptor.

A stateful session bean’s PostConstruct, PreDestroy, PrePassivate or PostActivate lifecycle callback interceptor method is invoked in the scope of a transaction determined by the transaction attribute specified in the lifecycle callback method’s metadata annotations or deployment descriptor.

A stateful session bean’s afterBegin and beforeCompletion methods are always called with the same transaction context as the business methods executed between the afterBegin and beforeCompletion methods.

A session bean’s constructor, setSessionContext, other dependency injection methods, other life cycle callback interceptor methods, and afterCompletion methods are called with an unspecified transaction context. Refer to Handling of Methods that Run with "an unspecified transaction context" for how the container executes methods with an unspecified transaction context.

If database operations are performed within a stateful session bean’s PostConstruct, PreDestroy, PrePassivate or PostActivate lifecycle callback interceptor methods these operations will not be part of the client’s transaction. If such a transaction is rolled back, the instance is discarded. See Dealing with Exceptions for rules on dealing with exceptions in stateful session beans.

Each portable session bean global JNDI name has the following syntax:

java:global[/<app-name>]/<module-name>/<bean-name>[!<fully-qualified-interface-name>]

The container registers a separate JNDI name entry for each local business interface, each remote business interface, any no-interface view, any local home interface, and any remote home interface. For the no-interface view, the last portion of the entry name is the fully-qualified name of the bean class.

In addition to the previous requirements, if the bean exposes only one of the applicable client interfaces (or, alternatively has only a no-interface view), the container registers an entry for that view with the following syntax:

java:global[/<app-name>]/<module-name>/<bean-name>

The container is also required to make session bean JNDI names available through the java:app and java:module namespaces.^[20]

The following examples show the resulting global JNDI names for various session beans.

The Asynchronous annotation is used to designate which business methods are asynchronous.

The Asynchronous annotation can be applied to a particular business method of a bean class (or superclass), or to the bean class (or superclass). If the Asynchronous annotation is applied at the class level, all business methods declared on that specific class are asynchronous.

Asynchronous methods can also be designated via the deployment descriptor.

Asynchronous method invocation semantics only apply to the no-interface, local business, and remote business client views. Support for asynchronous business methods exposed through the local component, remote component, and web service client views is not required by this specification, and applications which expose such views with asynchronous methods will not be portable.

The valid return type of an asynchronous method is either void or java.util.concurrent.Future<V>, where V is the result value type.

An asynchronous method with return type void must not declare any application exceptions. An asynchronous method with return type Future<V> is permitted to declare application exceptions.

The client’s transaction context does not propagate with an asynchronous method invocation. From the Bean Provider’s point of view, there is never a transaction context flowing in from the client. This means, for example, that the semantics of the REQUIRED transaction attribute on an asynchronous method are exactly the same as REQUIRES_NEW.

The caller security principal propagates with an asynchronous method invocation. Caller security principal propagation behaves exactly the same for asynchronous method invocations as it does for synchronous session bean invocations.

Client exception behavior depends on whether the asynchronous method has return type void or Future<V>.

If the asynchronous method has return type void, then once control has returned from the client’s method call no exceptions occurring during the processing of the invocation will be delivered to the client. For this reason, asynchronous methods with return type void must not declare application exceptions.

If the asynchronous method has return type Future<V>, an exception thrown from the processing of the asynchronous method invocation is accessible to the client via the getCause() method of a java.util.concurrent.ExecutionException thrown from either Future.get() method.

The following figure illustrates the life cycle of a stateful session bean instance.

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

The container must call the afterBegin, beforeCompletion, and afterCompletion methods if the session bean class implements, directly or indirectly, the SessionSynchronization interface, or if the bean class uses the session synchronization annotations.

Operations Allowed in the Methods of a Stateful Session Bean defines the methods of a stateful session bean class from which the session bean instances can access the methods of the jakarta.ejb.SessionContext interface, the java:comp/env environment naming context, resource managers, Timer methods, the EntityManager and EntityManagerFactory methods, and other enterprise beans.

If a session bean instance attempts to invoke a method of the SessionContext interface, and that access is not allowed in Operations Allowed in the Methods of a Stateful Session Bean, the container must throw the java.lang.IllegalStateException.

If a session bean instance attempts to access a resource manager, an enterprise bean, an entity manager or entity manager factory, and that access is not allowed in Operations Allowed in the Methods of a Stateful Session Bean, the behavior is undefined by the Enterprise Beans architecture.

If a session bean instance attempts to invoke a method of the Timer interface and the access is not allowed in Operations Allowed in the Methods of a Stateful Session Bean, the container must throw the java.lang.IllegalStateException.

Notes:
[A] If a client calls lifecycle callback method through a business interface or a no-interface view, the method is treated like a business method.

Notes:

Additional restrictions:

The reasons for disallowing the operations in Operations Allowed in the Methods of a Stateful Session Bean follow:

A RuntimeException that is not an application exception thrown from any method of the stateful session bean class (including the business methods and the lifecycle callback interceptor methods invoked by the container) results in the transition to the "does not exist" state. Exception handling is described in detail in Exception Handling. See the Jakarta Interceptors specification [15] for the rules pertaining to lifecycle callback interceptor methods when more than one such method applies to the bean class.

From the client perspective, the corresponding session object does not exist any more. If a client subsequently attempts to invoke a method on the bean’s business interface or the no-interface view, the container will throw the jakarta.ejb.NoSuchEJBException.^[27] If the Enterprise Beans 2.1 client view is used, the container will throw the java.rmi.NoSuchObjectException if the client is a remote client, or the jakarta.ejb.NoSuchObjectLocalException if the client is a local client.

The Bean Provider cannot assume that the container will always invoke the PreDestroy lifecycle callback interceptor method(s) (or ejbRemove method) for a stateful session bean instance. The following scenarios result in the PreDestroy lifecycle callback interceptor method(s) not being called for an instance:

If resources are allocated in a PostConstruct lifecycle callback interceptor method (or ejbCreate<METHOD> method) and/or in the business methods, and normally released in a PreDestroy lifecycle callback interceptor method, these resources will not be automatically released in the above scenarios. The application using the stateful session bean should provide some clean up mechanism to periodically clean up the unreleased resources.

For example, if a shopping cart component is implemented as a session bean, and the session bean stores the shopping cart content in a database, the application should provide a program that runs periodically and removes “abandoned” shopping carts from the database.

By default, the container may passivate a stateful session bean instance to a secondary storage to save resources. However, the Bean Provider can optionally configure the stateful session bean to prevent passivation of its instances.

For example, a stateful session bean instance may contain non-serializable attributes which would lead to runtime exceptions during passivation, or passivation and activation of such instances may cause degradation of application performance.

If the passivationCapable element of the Stateful annotation is set to false or the passivation-capable element of the session deployment descriptor element is set to false, the container must not attempt to passivate instances of the bean.

Note: application server vendors may use passivation as a technique to provide high availability of stateful session beans by replicating their state from one JVM instance to another across which the container is distributed. In a failure situation, a stateful session bean is made available on a new JVM instance by what is commonly called stateful session bean failover. If a container implementation supports failover of stateful session beans using bean passivation, the failover capability for not passivation capable stateful session beans is not defined.

By default a stateful session bean’s PostConstruct, PreDestroy, PrePassivate and PostActivate methods are executed in an unspecified transactional context. A PostConstruct, PreDestroy, PrePassivate and PostActivate method of a stateful session bean with container-managed transaction demarcation is permitted to have transaction attribute REQUIRES_NEW or NOT_SUPPORTED (RequiresNew or NotSupported if the deployment descriptor is used to specify the transaction attribute).

The state diagram implies the following restrictions on transaction scoping of the client invoked business methods. The restrictions are enforced by the container and must be observed by the client programmer.

If a stateful session bean instance is participating in a transaction, it is an error for a client to invoke the remove method on the session object’s home or component interface object. The container must detect such an attempt and throw the jakarta.ejb.RemoveException to the client. The container should not mark the client’s transaction for rollback, thus allowing the client to recover. Note that this restriction only applies to the remove method on the session object’s home or component interface, not to the invocation of Remove methods.

When a client calls a method on a stateless session object or invokes a method on a stateless session bean through its web service client view, the container selects one of its method-ready instances and delegates the method invocation to it.

The following figure illustrates the life cycle of a stateless session bean instance.

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

Operations Allowed in the Methods of a Stateless Session Bean defines the methods of a stateless session bean class in which the session bean instances can access the methods of the jakarta.ejb.SessionContext interface, the java:comp/env environment naming context, resource managers, TimerService and Timer methods, the EntityManager and EntityManagerFactory methods, 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 Operations Allowed in the Methods of a Stateless Session Bean, the container must throw the java.lang.IllegalStateException.

If a session bean instance attempts to invoke a method of the TimerService or Timer interface and the access is not allowed in Operations Allowed in the Methods of a Stateless Session Bean, the container must throw the java.lang.IllegalStateException.

If a session bean instance attempts to access a resource manager, an enterprise bean, an entity manager or entity manager factory, and the access is not allowed in Operations Allowed in the Methods of a Stateless Session Bean, the behavior is undefined by the Enterprise Beans architecture.

Notes:
[A] If a client calls lifecycle callback method through a business interface or a no-interface view, the method is treated like a business method.

Additional restrictions:

The reasons for disallowing operations in Operations Allowed in the Methods of a Stateless Session Bean:

A RuntimeException that is not an application exception thrown from any method of the enterprise bean class (including the business methods and the lifecycle callback interceptor methods invoked by the container) results in the transition to the "does not exist" state. Exception handling is described in detail in Exception Handling. See the Jakarta Interceptors specification [15] for the rules pertaining to lifecycle callback interceptor methods when more than one such method applies to the bean class.

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.

By default, the container is responsible for deciding when to initialize a singleton session bean instance. However, the Bean Provider can optionally configure the singleton session bean for eager initialization. If the Startup annotation appears on the singleton session bean class or if the singleton session bean has been designated via the deployment descriptor as requiring eager initialization, the container must initialize the singleton session bean instance during the application startup sequence. The container must initialize all such startup-time singleton session beans before any external client requests (that is, client requests originating outside of the application) are delivered to any enterprise bean components in the application.

The following example shows a singleton session bean with startup logic that initializes its shared state:

In some cases, explicit initialization ordering dependencies exist between multiple singleton session bean components in an application. The DependsOn annotation is used to express these dependencies. A DependsOn dependency is used in cases where one singleton session bean must initialize before one or more other singleton session beans. The container ensures that all singleton session beans with which a singleton session bean has a DependsOn relationship have been initialized before the PostConstruct method is called.

Note that if one singleton session bean merely needs to invoke another singleton session bean from its PostConstruct method, no explicit ordering metadata is required. In that case, the first singleton session bean would merely use an Enterprise Beans reference to invoke the target singleton session bean. In this case, the acquisition of the Enterprise Beans reference (either through injection or lookup) does not necessarily imply the actual creation of the corresponding singleton session bean instance.

The following examples illustrate the use of DependsOn metadata:

In the above example, the container must guarantee that singleton B is initialized before singleton A. The DependsOn value attribute holds one or more strings, where each specifies the ejb-name of the target singleton session bean.

In the following example, the container must guarantee that singletons B and C are initialized before singleton A. In the case of multiple values, the ordering in which the target ejb-name values are listed is not preserved at runtime. For example, if singleton B has an ordering dependency on singleton C, it is singleton B’s responsibility to explicitly capture that in its own metadata.

The following example illustrates the use of the fully-qualified ejb-name syntax to refer to a singleton session bean packaged within a different module in the same application.

Circular dependencies within the DependsOn metadata are not permitted. Circular dependencies are not required to be detected by the container but may result in a deployment error.

Any singleton session bean instance that successfully completes initialization is removed by the container during application shutdown. At this time the container must invoke the PreDestroy lifecycle callback interceptor methods on the singleton session bean instance, if any. The container ensures that all singleton session beans with which a singleton session bean has a DependsOn relationship are still available during the PreDestroy callback. After the PreDestroy callback completes, the container ends the life of the singleton session bean instance.

The PostConstruct and PreDestroy methods of singleton session beans with container-managed transaction demarcation can be invoked with or without a transaction. From the Bean Provider’s view there is no client of a PostConstruct or PreDestroy method.

A PostConstruct or PreDestroy method of a singleton session bean with container-managed transaction demarcation is permitted to have transaction attribute REQUIRED, REQUIRES_NEW, or NOT_SUPPORTED (Required, RequiresNew, or NotSupported if the deployment descriptor is used to specify the transaction attribute).

Note that the container must start a new transaction if the REQUIRED (Required) transaction attribute is used. This guarantees, for example, that the transactional behavior of the PostConstruct method is the same regardless of whether the singleton session bean instance is initialized eagerly at container startup time or as a side effect of a first client invocation on the singleton session bean. The REQUIRED transaction attribute value is allowed so that specification of a transaction attribute for the singleton session bean’s PostConstruct and PreDestroy methods can be defaulted.

Errors occurring during singleton session bean initialization are considered fatal and must result in the discarding of the singleton session bean instance. Possible initialization errors include injection failure, a system exception thrown from an AroundConstruct or PostConstruct method, or the failure of a PostConstruct method’s container-managed transaction to successfully commit. If a singleton session bean fails to initialize, attempted invocations on the singleton session bean result in the jakarta.ejb.NoSuchEJBException exception as defined by Session Bean’s Business Interface and Session Bean’s No-Interface View.

The same singleton session bean instance must remain active until application shutdown. Unlike instances of other component types, system exceptions thrown from business methods or callbacks of a singleton session bean do not result in the destruction of the singleton instance.

From the client’s perspective, a singleton session bean always supports concurrent access. In general, the client of a singleton session bean does not have to concern itself with whether other clients might be accessing the singleton session bean at the same time.

From the Bean Provider’s perspective, there are two approaches for controlling singleton session bean concurrency behavior:

When designing a singleton session bean, the bean provider must decide whether the bean will use container-managed or bean-managed concurrency. Typically singleton session beans will be specified to have container-managed concurrency. This is the default if no concurrency management type is specified. A singleton session bean can be designed to use either container-managed concurrency or bean-managed concurrency but it cannot use both.

The lifecycle of any interceptor classes associated with a singleton session bean have the same lifecycle and concurrency behavior as that of the singleton session bean itself. Each interceptor class will be instantiated once per singleton session bean instance. Any state stored in an instance of an interceptor class associated with a singleton session bean should be considered when devising the concurrency plan for the bean.

It is legal to store Jakarta EE objects that do not support concurrent access (e.g. references to Jakarta Persistence entity managers or stateful session beans) within the singleton session bean instance state. However, it is the responsibility of the Bean Provider to ensure such objects are not accessed by more than one thread at a time.

Independent of the bean’s concurrency management type, the container must ensure that no concurrent access to the singleton session bean instance occurs until after the instance has successfully completed its initialization sequence, including any PostConstruct lifecycle callback method(s). The container must temporarily block any singleton session bean access attempts that arrive while the singleton session bean is still initializing.

Independent of the bean’s concurrency management type, the container must ensure that concurrent access to the SessionContext object is thread-safe.

Singleton session beans support reentrant calls, i.e., where an outbound call from a singleton session bean method results in a loopback call to the singleton session bean on the same thread. Reentrant singleton session beans should be programmed and used with caution. Special locking semantics apply to loopback calls on singleton session beans with container-managed concurrency as described below.

Operations Allowed in the Methods of a Singleton Session Bean defines the methods of a singleton session bean class in which the session bean instances can access the methods of the jakarta.ejb.SessionContext interface, the java:comp/env environment naming context, resource managers, TimerService and Timer methods, the EntityManager and EntityManagerFactory methods, 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 Operations Allowed in the Methods of a Singleton Session Bean, the container must throw the java.lang.IllegalStateException.

If a session bean instance attempts to invoke a method of the TimerService or Timer interface and the access is not allowed in Operations Allowed in the Methods of a Singleton Session Bean, the container must throw the java.lang.IllegalStateException.

If a session bean instance attempts to access a resource manager, an enterprise bean, an entity manager or entity manager factory, and the access is not allowed in Operations Allowed in the Methods of a Singleton Session Bean, the behavior is undefined by the Enterprise Beans architecture.

Notes:
[A] If a client calls lifecycle callback method through a business interface or a no-interface view, the method is treated like a business method.

Additional restrictions:

The reasons for disallowing operations in Operations Allowed in the Methods of a Singleton Session Bean:

The session Bean Provider is responsible for providing the following class files:^[31]

The Bean Provider for a session bean that provides a web service client view may also define Jakarta XML Web Services message handlers for the bean. The requirements for such message handlers are defined in [5] and [4].

The following are the requirements for the session bean class:

Optionally:

The AroundConstruct, PostConstruct, PreDestroy, PrePassivate, and PostActivate lifecycle callback interceptor methods may be defined for session beans. If the PrePassivate or PostActivate lifecycle callbacks are defined for stateless session beans or singleton session beans, they are ignored.^[34]

The AroundConstruct lifecycle callback interceptor method may be defined on an interceptor class only. All other lifecycle callback interceptor methods may be defined on the bean class and/or on an interceptor class of the bean. Rules applying to the definition of lifecycle callback interceptor methods are defined in Interceptors for LifeCycle Event Callbacks.

Compatibility Note: If the PostConstruct lifecycle callback interceptor method is the ejbCreate method, if the PreDestroy lifecycle callback interceptor method is the ejbRemove method, if the PostActivate lifecycle callback interceptor method is the ejbActivate method, or if the PrePassivate lifecycle callback interceptor method is the ejbPassivate method, these callback methods must be implemented on the bean class itself (or on its superclasses). Except for these cases, the method names can be arbitrary, but must not start with "ejb" to avoid conflicts with the callback methods defined by the jakarta.ejb.EnterpriseBean interfaces.

The bean class (or superclass) of a stateful session bean may use one or more of the session synchronization annotations AfterBegin, BeforeCompletion, and AfterCompletion. Each bean has at most one session synchronization method for each of the three annotation types. In the case of method overriding of session synchronization methods declared by annotations, the most derived method takes precedence. The signatures of the session synchronization methods must follow these rules:

The session bean class of a session bean that has a home interface may define one or more ejbCreate<METHOD> methods. These ejbCreate methods are intended for use only with components written to the the Enterprise Beans 2.1 and earlier APIs. The signatures of the ejbCreate methods must follow these rules:

Compatibility Note: Enterprise Beans 1.0 allowed the ejbCreate method to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1— an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another RuntimeException to indicate non-application exceptions to the container (see System Exceptions). An Enterprise Beans 2.0 and later compliant enterprise bean should not throw the java.rmi.RemoteException from the ejbCreate method.

The session bean class may define zero or more business methods whose signatures must follow these rules:

Compatibility Note: Enterprise Beans 1.0 allowed the business methods to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1— an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another RuntimeException to indicate non-application exceptions to the container (see System Exceptions). An Enterprise Beans 2.0 or later compliant enterprise bean should not throw the java.rmi.RemoteException from a business method.

The following are the requirements for the session bean’s business interface:

If the business interface is a remote business interface, the argument and return values must be of valid types for RMI/IIOP. The remote business interface is not required or expected to be a java.rmi.Remote interface. The throws clause should not include the java.rmi.RemoteException. The methods of the business interface may only throw the java.rmi.RemoteException if the interface extends java.rmi.Remote.

Note that while it is expected that the bean class will typically implement its business interface(s), if the bean class uses annotations or the deployment descriptor to designate its business interface(s), it is not required that the bean class also be specified as implementing the interface(s).

The following examples assume that there is no deployment descriptor associated with the bean and neither the Local nor the Remote annotation is specified on the bean class or an interface unless noted.

Example 1: session bean A exposes two local business interfaces, Foo and Bar:

Example 2: session bean A exposes two local business interfaces, Foo and Bar:

Example 3: session bean A exposes two remote business interfaces, Foo and Bar

Example 4: session bean A exposes only one remote business interface Foo

Example 5: session bean A exposes only one remote business interface Foo

The following are the requirements for a session bean that exposes a no-interface view:

The following are the requirements for the session bean’s remote component interface:

The following are the requirements for the session bean’s remote home interface:

The following are the requirements for the session bean’s local component interface:

The following are the requirements for the session bean’s local home interface:

The Enterprise Beans 3.x API does not require the definition of a web service endpoint interface for session beans that implement a web service endpoint.

The Jakarta XML Web Services and Jakarta Enterprise Web Services specifications do not require that a separate interface be defined for a web service endpoint. The requirements for web service endpoints under Jakarta XML Web Services and Jakarta Enterprise Web Services are given in [4] and [5].

The deployment tools provided by the container are responsible for the generation of additional classes when the session bean is deployed. The tools obtain the information that they need for generation of the additional classes by introspecting the classes and interfaces provided by the Bean Provider and by examining the session bean’s deployment descriptor.

The deployment tools must generate the following classes:

The deployment tools may also generate a class that mixes some container-specific code with the session bean class. This code may, for example, help the container to manage the bean instances at runtime. The tools can use subclassing, delegation, and code generation.

The deployment tools may also allow the generation of additional code that wraps the business methods and is used to customize the business logic to an existing operational environment. For example, a wrapper for a debit function on the AccountManager bean may check that the debited amount does not exceed a certain limit.

Reference [5] describes the generation of a WSDL document for a web service endpoint. The Java to WSDL mapping must adhere to the requirements of Jakarta XML Web Services [4].

The container’s implementation of the session business interface, which is generated by the deployment tools, implements the business methods specific to the session bean.

The implementation of each business method must activate the instance (if the instance is in the passive state), invoke any business method interceptor methods, and invoke the matching business method on the instance.

The Container Provider is responsible for providing the implementation of the equals and hashCode methods for the business interface, in conformance with the requirements of Session Object Identity.

The container’s implementation of the no-interface view reference, which is generated by the deployment tools, implements the business methods that are exposed to the no-interface view client.

The implementation of each business method must activate the instance (if the instance is in the passive state), invoke any business method interceptor methods, and invoke the matching business method on the instance.

The Container Provider is responsible for providing the implementation of the equals and hashCode methods for the no-interface view reference class, in conformance with the requirements of Client view of Session Object’s Life Cycle.

The session EJBHome class, which is generated by the deployment tools, implements the session bean’s remote home interface. This class implements the methods of the jakarta.ejb.EJBHome interface and the create<METHOD> methods specific to the session bean.

The implementation of each create<METHOD> method invokes a matching ejbCreate<METHOD> method.

The session EJBObject class, which is generated by the deployment tools, implements the session bean’s remote component interface. It implements the methods of the jakarta.ejb.EJBObject interface and the business methods specific to the session bean.

The implementation of each business method must activate the instance (if the instance is in the passive state), invoke any business method interceptor methods, and invoke the matching business method on the instance.

The session EJBLocalHome class, which is generated by the deployment tools, implements the session bean’s local home interface. This class implements the methods of the jakarta.ejb.EJBLocalHome interface and the create<METHOD> methods specific to the session bean.

The implementation of each create<METHOD> method invokes a matching ejbCreate<METHOD> method.

The session EJBLocalObject class, which is generated by the deployment tools, implements the session bean’s local component interface. It implements the methods of the jakarta.ejb.EJBLocalObject interface and the business methods specific to the session bean.

The implementation of each business method must activate the instance (if the instance is in the passive state), invoke any business method interceptor methods, and invoke the matching business method on the instance.

The implementation class for a stateless session bean’s web service endpoint is generated by the container’s deployment tools. This class must handle requests to the web service endpoint, unmarshall the SOAP request, invoke any business method interceptor methods, and invoke the stateless session bean method that matches the web service endpoint method that corresponds to the request.

The object returned from an asynchronous method with return type Future<V> is implemented by the container’s deployment tools.

The deployment tools are responsible for implementing the handle classes for the session bean’s remote home and remote component interfaces.

The deployment tools are responsible for implementing the class that provides metadata to the remote client view contract. The class must be a valid RMI Value class and must implement the jakarta.ejb.EJBMetaData interface.

The container must ensure that only one thread can be executing a stateless or stateful session bean instance at any time. Therefore, stateful and stateless session beans do not have to be coded as reentrant. One implication of this rule is that an application cannot make loopback calls to a stateless or stateful session bean instance.

The container must follow the rules with respect to transaction scoping, security checking, and exception handling, as described in Support for Transactions, Security Management, and Exception Handling, respectively.

The container must support the use of Jakarta XML Web Services message handlers for web service endpoints. Container requirements for support of message handlers are specified in [4] and [5].

If message handlers are present, they must be invoked before any business method interceptor methods.

The container must implement the SessionContext.getEJBObject method such that the bean instance can use the Java language cast to convert the returned value to the session bean’s remote component interface type. Specifically, the bean instance does not have to use the PortableRemoteObject.narrow method for the type conversion.

The container must implement the EJBContext.lookup method such that when the lookup method is used to look up a bean’s remote home interface, a bean instance can use the Java language cast to convert the returned value to a session bean’s remote home interface type. Specifically, the bean instance does not have to use the PortableRemoteObject.narrow method for the type conversion.

A message-driven bean must be annotated with the MessageDriven annotation or denoted in the deployment descriptor as a message-driven bean. The MessageDriven annotation is a component-defining annotation and is applied to the bean class.

The message-driven bean class must implement the appropriate message listener interface for the messaging type that the message-driven bean supports or specify the message listener interface using the MessageDriven metadata annotation or the messaging-type deployment descriptor element. The specific message listener interface that is implemented by a message-driven bean class distinguishes the messaging type that the message-driven bean supports.

The bean’s message listener method (e.g., onMessage in the case of jakarta.jms.MessageListener) is called by the container when a message has arrived for the bean to service. The message listener method contains the business logic that handles the processing of the message.

If the message-driven bean class implements more than one interface other than java.io.Serializable, java.io.Externalizable, or any of the interfaces defined by the jakarta.ejb package, the message listener interface must be specified by the messageListenerInterface element of the MessageDriven annotation or the messaging-type element of the message-driven deployment descriptor element.

A message-driven bean is permitted to implement a listener interface with no methods. A bean that implements a no-methods interface, exposes all non-static public methods of the bean class and of any superclasses except java.lang.Object as message listener methods.

In this case, when requested by a resource adapter, the container provides a proxy which implements the message listener interface and all message listener methods of the bean. A resource adapter may use the Reflection API to invoke a message listener method on such a proxy. When the resource adapter invokes a method on the proxy, the message listener method on the bean instance and any interceptor methods are invoked as needed. The resource adapter determines which message listener method is invoked according to its implementation logic.

Only public methods of the bean class and of any superclasses except java.lang.Object may be invoked by a resource adapter. Attempted invocations of methods with any other access modifiers on a proxy provided by the container must result in the jakarta.ejb.EJBException.

A message-driven bean may use dependency injection mechanisms to acquire references to resources or other objects in its environment (see Enterprise Bean Environment). If a message-driven bean makes use of dependency injection, the container injects these references after the bean instance is created, and before any message-listener methods are invoked on the bean instance. If a dependency on the MessageDrivenContext is declared, or if the bean class implements the optional MessageDrivenBean interface (see The Optional MessageDrivenBean Interface), the MessageDrivenContext is also injected at this time. If dependency injection fails, the bean instance is discarded.

If the bean specifies a dependency on the MessageDrivenContext interface (or if the bean class implements the MessageDrivenBean interface), the container must provide the message-driven bean instance with a MessageDrivenContext. This gives the message-driven bean instance access to the instance’s context maintained by the container. The MessageDrivenContext interface has the following methods:

The following lifecycle event callbacks are supported for message-driven beans.

The PostConstruct and PreDestroy callback methods may be defined directly on the bean class or on a separate interceptor class.^[36] The AroundConstruct lifecycle callback interceptor method, if used, must be defined on an interceptor class (see [15]). See Lifecycle Callback Interceptor Methods.

The PostConstruct callback occurs before the first message listener method invocation on the bean. This is at a point after which any dependency injection has been performed by the container.

The PostConstruct lifecycle callback interceptor method executes in an unspecified transaction and security context.

The PreDestroy callback occurs at the time the bean is removed from the pool or destroyed.

The PreDestroy lifecycle callback interceptor method executes in an unspecified transaction and security context.

The message-driven bean class is not required to implement the jakarta.ejb.MessageDrivenBean interface.

Compatibility Note: The MessageDrivenBean interface was required by earlier versions of the Enterprise Beans specification. Under the Enterprise Beans 3.x API, the functionality previously provided by the MessageDrivenBean interface is available to the bean class through the use of dependency injection (of the MessageDrivenContext) and optional lifecycle callback methods.

The MessageDrivenBean interface defines two methods, setMessageDrivenContext and ejbRemove.

The setMessageDrivenContext method is called by the bean’s container to associate a message-driven bean instance with its context maintained by the container. Typically a message-driven bean instance retains its message-driven context as part of its state.

The ejbRemove notification signals that the instance is in the process of being removed by the container. In the ejbRemove method, the instance releases the resources that it is holding.

This specification requires that the ejbRemove and the ejbCreate methods of a message-driven bean be treated as the PreDestroy and PostConstruct lifecycle callback methods, respectively. If the message-driven bean implements the MessageDrivenBean interface, the PreDestroy annotation can only be applied to the ejbRemove method. Similar requirements apply to use of deployment descriptor metadata as an alternative to the use of annotations.

A message-driven bean can be registered with the Enterprise Beans Timer Service for time-based event notifications. The container invokes the appropriate bean instance timeout callback method when a timer for the bean has expired. See Timer Service.

Except as noted below, the container creates an instance of a message-driven bean in three steps. First, the container calls the bean class constructor to create a new message-driven bean instance. Second, the container injects the bean’s MessageDrivenContext, if applicable, and performs any other dependency injection as specified by metadata annotations on the bean class or by the deployment descriptor. Third, the container calls the instance’s PostConstruct lifecycle callback methods, if any. See Lifecycle Callback Interceptor Methods.

If an interceptor associated with the message-driven bean declares an AroundConstruct lifecycle callback interceptor method, the container follows the rules for the AroundConstruct interceptors defined in the Jakarta Interceptors specification [15].

Compatibility Note: Enterprise Beans 2.1 required the message-driven bean class to implement the ejbCreate method. This requirement has been removed from the Enterprise Beans 3.x API. If the message-driven bean class implements the ejbCreate method, the ejbCreate method is treated as the bean’s PostConstruct method, and the PostConstruct annotation can only be applied to the ejbCreate method.

AroundInvoke interceptor methods are supported for message-driven beans. These interceptor methods may be defined on the bean class or on a interceptor class and apply to the handling of the invocation of the bean’s message listener method(s).

Interceptors are described in Interceptors.

The container serializes calls to each message-driven bean instance. Most containers will support many instances of a message-driven bean executing concurrently; however, each instance sees only a serialized sequence of method calls. Therefore, a message-driven bean does not have to be coded as reentrant.

The container must serialize all the container-invoked callbacks (e.g., lifecycle callback interceptor methods and timeout callback methods), and it must serialize these callbacks with the message listener method calls.

A container allows many instances of a message-driven bean class to be executing concurrently, thus allowing for the concurrent processing of a stream of messages. No guarantees are made as to the exact order in which messages are delivered to the instances of the message-driven bean class, although the container should attempt to deliver messages in order when it does not impair the concurrency of message processing. Message-driven beans should therefore be prepared to handle messages that are out of sequence: for example, the message to cancel a reservation may be delivered before the message to make the reservation.

A bean’s message listener and timeout callback methods are invoked in the scope of a transaction determined by the transaction attribute specified in the bean’s metadata annotations or deployment descriptor. If the bean is specified as using container-managed transaction demarcation, either the REQUIRED or the NOT_SUPPORTED transaction attribute must be used for the message listener methods, and either the REQUIRED, REQUIRES_NEW, or the NOT_SUPPORTED transaction attribute for timeout callback methods. See Support for Transactions.

When a message-driven bean using bean-managed transaction demarcation uses the jakarta.transaction.UserTransaction interface to demarcate transactions, the message receipt that causes the bean to be invoked is not part of the transaction. If the message receipt is to be part of the transaction, container-managed transaction demarcation with the REQUIRED transaction attribute must be used.

The bean constructor, the setMessageDrivenContext method, the message-driven bean’s dependency injection methods, and lifecycle callback methods are called with an unspecified transaction context. Refer to Handling of Methods that Run with "an unspecified transaction context" for how the container executes methods with an unspecified transaction context.

A caller principal may propagate into a message-driven bean’s message listener methods. Whether this occurs is a function of the specific message-listener interface and associated messaging provider, but is not governed by this specification.

The Bean Provider can use the RunAs metadata annotation (or corresponding deployment descriptor element) to define a run-as identity for the enterprise bean. The run-as identity applies to the bean’s message listener methods and timeout methods. Run-as identity behavior is further defined in Run-as.

A message-driven bean is associated with a destination or endpoint when the bean is deployed in the container. It is the responsibility of the Deployer to associate the message-driven bean with a destination or endpoint.

The Bean Provider may provide information to the Deployer about the configuration of the message-driven bean in its operational environment. This may include information about message acknowledgement modes, message selectors, expected destination or endpoint types, etc.

Activation configuration properties are specified by means of the activationConfig element of the MessageDriven annotation or activation-config deployment descriptor element. Activation configuration properties specified in the deployment descriptor are added to those specified by means of the MessageDriven annotation. If a property of the same name is specified in both, the deployment descriptor value overrides the value specified in the annotation.

This section describes activation configuration properties specific to the Jakarta Messaging message-driven beans.

The container may or may not support its built-in Jakarta Messaging provider using a resource adapter. However, it must allow the application to configure a message-driven bean that uses the built-in Jakarta Messaging provider using the activation properties defined by this specification.

Both the container and any Jakarta Messaging resource adapters are free to support activation properties in addition to those listed here. However, applications that use non-standard activation properties will not be portable.

A message-driven bean’s message listener method must not throw the java.rmi.RemoteException.

Message-driven beans should not, in general, throw RuntimeException.

A RuntimeException that is not an application exception thrown from any method of the message-driven bean class (including a message listener method and the callbacks invoked by the container) results in the transition to the "does not exist" state. If a message-driven bean uses bean-managed transaction demarcation and throws a RuntimeException, the container should not acknowledge the message. Exception handling is described in detail in Exception Handling. See the Jakarta Interceptors specification [15] for the rules pertaining to lifecycle callback interceptor methods when more than one such method applies to the bean class.

From the client perspective, the message consumer continues to exist. If the client continues sending messages to the destination or endpoint associated with the bean, the container can delegate the client’s messages to another instance.

The message listener methods of some messaging types may throw application exceptions. An application exception is propagated by the container to the resource adapter.

The Bean Provider cannot assume that the container will always invoke the PreDestroy callback method (or ejbRemove method) for a message-driven bean instance. The following scenarios result in the PreDestroy callback method not being called on an instance:

If the message-driven bean instance allocates resources in the PostConstruct lifecycle callback method and/or in the message listener method, and releases normally the resources in the PreDestroy method, these resources will not be automatically released in the above scenarios. The application using the message-driven bean should provide some clean up mechanism to periodically clean up the unreleased resources.

In standard Jakarta Messaging usage scenarios, the messaging mode of a message’s JMSReplyTo destination (Queue or Topic) is the same as the mode of the destination to which the message has been sent. Although a message-driven bean is not directly dependent on the mode of the Jakarta Messaging destination from which it is consuming messages, it may contain code that depends on the mode of its message’s JMSReplyTo destination. In particular, if a message-driven bean replies to a message, the mode of the reply’s message producer and the mode of the JMSReplyTo destination must be the same. In order to implement a message-driven bean that is independent of JMSReplyTo mode, the Bean Provider should use instanceOf to test whether a JMSReplyTo destination is a Queue or Topic, and then use a matching message producer for the reply.

Operations Allowed in the Methods of a Message-Driven Bean defines the methods of a message-driven bean class in which the message-driven bean instances can access the methods of the jakarta.ejb.MessageDrivenContext interface, the java:comp/env environment naming context, resource managers, TimerService and Timer methods, the EntityManager and EntityManagerFactory methods, and other enterprise beans.

If a message-driven bean instance attempts to invoke a method of the MessageDrivenContext interface, and the access is not allowed in Operations Allowed in the Methods of a Message-Driven Bean, the container must throw and log the java.lang.IllegalStateException.

If a message-driven bean instance attempts to invoke a method of the TimerService or Timer interface, and the access is not allowed in Operations Allowed in the Methods of a Message-Driven Bean, the container must throw the java.lang.IllegalStateException.

If a bean instance attempts to access a resource manager, an enterprise bean, or an entity manager or entity manager factory, and the access is not allowed in Operations Allowed in the Methods of a Message-Driven Bean, the behavior is undefined by the Enterprise Beans specification.

Additional restrictions:

The reasons for disallowing operations in Operations Allowed in the Methods of a Message-Driven Bean:

The message-driven Bean Provider is responsible for providing the following class files:

The following are the requirements for the message-driven bean class:

Optionally:

The message-driven bean class may have superclasses and/or superinterfaces. If the message-driven bean has superclasses, the message listener methods, lifecycle callback interceptor methods, timeout callback methods, the ejbCreate method, and the methods of the MessageDrivenBean interface may be defined in the message-driven bean class or in any of its superclasses.

The message-driven bean class is allowed to implement other methods (for example, helper methods invoked internally by the message listener method) in addition to the methods required by the Enterprise Beans specification.

A message-driven bean class is permitted to have superclasses that are themselves message-driven bean classes. However, there are no special rules that apply to the processing of annotations or the deployment descriptor for this case. For the purposes of processing a particular message-driven bean class, all superclass processing is identical regardless of whether the superclasses are themselves message-driven bean classes. In this regard, the use of message-driven bean classes as superclasses merely represents a convenient use of implementation inheritance, but does not have component inheritance semantics.

The message-driven bean class must define the message listener methods. The signature of a message listener method must follow these rules:

The method must be declared as public.

The method must not be declared as final or static.

The following additional requirements apply for a message-driven bean with a no-methods interface:

Note: This includes callback methods. The Bean Provider should exercise caution when choosing to expose callback methods as message listener methods. The runtime context (e.g. transaction context, caller principal, operations allowed, etc.) for a method invoked as a callback can differ significantly from the context for the same method when invoked as a message listener. In general, callback methods should not be exposed as message listener methods. Therefore, it is recommended that all methods other than message listener methods be assigned an access type other than public.

PostConstruct and PreDestroy lifecycle callback interceptor methods may be defined for message-driven beans. If PrePassivate or PostActivate lifecycle callbacks are defined, they are ignored.^[38]

Compatibility Note: If the PostConstruct lifecycle callback interceptor method is the ejbCreate method, or if the PreDestroy lifecycle callback interceptor method is the ejbRemove method, these callback methods must be implemented on the bean class itself (or on its superclasses). Except for these cases, the method names can be arbitrary, but must not start with "ejb" to avoid conflicts with the callback methods defined by the jakarta.ejb.EnterpriseBean interfaces.

Lifecycle callback interceptor methods may be defined on the bean class and/or on an interceptor class of the bean. Rules applying to the definition of lifecycle callback interceptor methods are defined in Interceptors for LifeCycle Event Callbacks.

The deployment tools provided by the container are responsible for the generation of additional classes when the message-driven bean is deployed. The tools obtain the information that they need for generation of the additional classes by introspecting the classes and interfaces provided by the Enterprise Bean Provider and by examining the message-driven bean’s deployment descriptor.

The deployment tools may generate a class that mixes some container-specific code with the message-driven bean class. This code may, for example, help the container to manage the bean instances at runtime. Subclassing, delegation, and code generation can be used by the tools.

The Container Provider must support the deployment of a message-driven bean with a no-methods listener interface.

The container’s implementation class generated by the deployment tools must implement the message listener interface and implement all non-static public methods of the bean class and of any superclasses except java.lang.Object as message listener methods.

The Container Provider must support the deployment of a Jakarta Messaging message-driven bean as the consumer of a Jakarta Messaging queue or topic.

If the message listener supports a request/response messaging type, it is the container’s responsibility to deliver the message response.

The container must ensure that only one thread can be executing an instance at any time.

The container must follow the rules with respect to transaction scoping, security checking, and exception handling, as described in Support for Transactions, Security Management, and Exception Handling.

The interceptor deployment descriptor element is used to specify the interceptor methods of an interceptor class. The interceptor methods are specified by using the around-invoke, around-timeout, around-construct, post-construct, pre-destroy, pre-passivate, and post-activate elements.

At most one method of a given interceptor class can be designated as an around-invoke method, an around-timeout method, a lifecycle callback interceptor method, regardless of whether the deployment descriptor is used to define interceptors or whether some combination of annotations and deployment descriptor elements is used.

The interceptor-binding element is used to specify the binding of interceptor classes to target classes and their methods. The subelements of the interceptor-binding element are as follows:

Default interceptors are bound to all target classes in a module using the wildcard syntax "*". In addition, interceptors may be bound at the level of the target class (class-level interceptors) or methods of the target class (method-level interceptors).

The binding of interceptors to classes is additive. If interceptors are bound at the class level and/or default level as well as at the method level, both class-level and/or default-level as well as method-level interceptors will apply. The deployment descriptor may be used to augment the interceptors and interceptor methods defined by means of annotations. When the deployment descriptor is used to augment the interceptors specified in annotations, the interceptor methods specified in the deployment descriptor will be invoked after those specified in annotations, according to the ordering specified earlier. The interceptor-order deployment descriptor element may be used to override this ordering.

The exclude-default-interceptors element disables default interceptors for the level at which it is specified and lower. That is, exclude-default-interceptors when applied at the class level disables the application of default interceptors for all methods of the class. The exclude-class-interceptors element applied to a method disables the application of class-level interceptors for the given method. Explicitly listing an excluded higher-level interceptor at a lower level causes it to be applied at that level and below.

It is possible to override the ordering of interceptors by using the interceptor-order element to specify a total ordering of interceptors at class level and/or method level. If the interceptor-order element is used, the ordering specified at the given level must be a total order over all interceptor classes that have been defined at that level and above (unless they have been explicitly excluded by means of one of the exclude- elements described above).

There are four possible styles of the interceptor-binding element syntax:

Style 1:

Specifying the target-name element as the wildcard value "*" designates default interceptors.

Style 2:

This style is used to refer to interceptors associated with the specified target class (class-level interceptors).

Style 3:

This style is used to associate a method-level interceptor with the specified method of the specified target class. If there are multiple methods with the same overloaded name, the element of this style refers to all the methods with the overloaded name. Note that the wildcard value "*" cannot be used to specify method-level interceptors.

Style 4:

This style is used to associate a method-level interceptor with the specified method of the specified target class. This style is used to refer to a single method within a set of methods with an overloaded name. The values PARAM-1 through PARAM-n are the fully-qualified Java types of the method’s input parameters (if the method has no input arguments, the method-params element contains no method-param elements). Arrays are specified by the array element’s type, followed by one or more pair of square brackets (e.g. int[][]).

If both styles 3 and 4 are used to define method-level interceptors for the same bean, the relative ordering of those method-level interceptors is undefined.

Transactions are a proven technique for simplifying application programming. Transactions free the application programmer from dealing with the complex issues of failure recovery and multi-user programming. The transactional system ensures that a unit of work either fully completes, or the work is fully rolled back. Furthermore, transactions make it possible for the programmer to design the application as if it ran in an environment that executes units of work serially.

Support for transactions is an essential element of the Enterprise Beans architecture. The Enterprise Bean Provider and the client application programmer are not exposed to the complexity of distributed transactions. The Bean Provider can choose between using programmatic transaction demarcation in the enterprise bean code (this style is called bean-managed transaction demarcation) or declarative transaction demarcation performed automatically by the Enterprise Beans container (this style is called container-managed transaction demarcation).

With bean-managed transaction demarcation, the enterprise bean code demarcates transactions using the jakarta.transaction.UserTransaction interface. All resource manager accesses between the UserTransaction.begin and UserTransaction.commit calls are part of a transaction.

With container-managed transaction demarcation, the container demarcates transactions per instructions provided by the developer in metadata annotations or in the deployment descriptor. These instructions, called transaction attributes, tell the container whether it should include the work performed by an enterprise bean method in a client’s transaction, run the enterprise bean method in a new transaction started by the container, or run the method with "no transaction" (Refer to Handling of Methods that Run with "an unspecified transaction context" for the description of the "no transaction" case).

Regardless of whether an enterprise bean uses bean-managed or container-managed transaction demarcation, the burden of implementing transaction management is on the Enterprise Beans Container and Server Provider. The Enterprise Beans container and server implement the necessary low-level transaction protocols, such as the two-phase commit protocol between a transaction manager and a database system or messaging provider, transaction context propagation, and distributed two-phase commit.

Many applications will consist of one or several enterprise beans that all use a single resource manager (typically a relational database management system). The Enterprise Beans container can make use of resource manager local transactions as an optimization technique for enterprise beans for which distributed transactions are not needed. A resource manager local transaction does not involve control or coordination by an external transaction manager. The container’s use of local transactions as an optimization technique for enterprise beans with either container-managed transaction demarcation or bean-managed transaction demarcation is not visible to the enterprise beans. For a discussion of the use of resource manager local transactions as a container optimization strategy, refer to [18] and [16].

The Enterprise Beans architecture supports flat transactions. A flat transaction cannot have any child (nested) transactions.

The Jakarta® Transactions [17] is a specification of the interfaces between a transaction manager and the other parties involved in a distributed transaction processing system: the application programs, the resource managers, and the application server.

The Java Transaction Service (JTS) [19] API is a Java binding of the CORBA Object Transaction Service (OTS) 1.1 specification. JTS provides transaction interoperability using the standard IIOP protocol for transaction propagation between servers. The JTS API is intended for vendors who implement transaction processing infrastructure for enterprise middleware. For example, an Enterprise Beans server vendor may use a JTS implementation as the underlying transaction manager.

The Enterprise Beans architecture does not require the Enterprise Beans container to support the JTS interfaces. The Enterprise Beans architecture requires that the Enterprise Beans container support the Jakarta Transactions API defined in [17] and the Jakarta Connectors APIs defined in [16].

The Enterprise Beans architecture makes it possible for an application program to update data in multiple databases in a single transaction.

In the following figure, a client invokes the enterprise bean X. Bean X updates data using two database connections that the Deployer configured to connect with two different databases, A and B. Then X calls another enterprise bean, Y. Bean Y updates data in database C. The Enterprise Beans server ensures that the updates to databases A, B, and C are either all committed or all rolled back.

The application programmer does not have to do anything to ensure transactional semantics. Behind the scenes, the Enterprise Beans server enlists the database connections as part of the transaction. When the transaction commits, the Enterprise Beans server and the database systems perform a two-phase commit protocol to ensure atomic updates across all three databases.

The Enterprise Beans architecture makes it possible for an application program to send messages to or receive messages from one or more Jakarta Messaging Destinations and/or to update data in one or more databases in a single transaction.

In the following figure, a client invokes the enterprise bean X. Bean X sends a message to a Jakarta Messaging queue A and updates data in a database B using connections that the Deployer configured to connect with a Jakarta Messaging provider and a database. Then X calls another enterprise bean, Y. Bean Y updates data in database C. The Enterprise Beans server ensures that the operations on A, B, and C are either all committed, or all rolled back.

The application programmer does not have to do anything to ensure transactional semantics. The enterprise beans X and Y perform the message send and database updates using the standard Jakarta Messaging and JDBC™ APIs. Behind the scenes, the Enterprise Beans server enlists the session on the connection to the Jakarta Messaging provider and the database connections as part of the transaction. When the transaction commits, the Enterprise Beans server and the messaging and database systems perform a two-phase commit protocol to ensure atomic updates across all the three resources.

In the following figure, a client sends a message to the Jakarta Messaging queue A serviced by the message-driven bean X. Bean X updates data using two database connections that the Deployer configured to connect with two different databases, B and C. The Enterprise Beans server ensures that the dequeuing of the Jakarta Messaging message, its receipt by bean X, and the updates to databases B and C are either all committed or all rolled back.

The Enterprise Beans architecture allows updates of data at multiple sites to be performed in a single transaction.

In the following figure, a client invokes the enterprise bean X. Bean X updates data in database A, and then calls another enterprise bean Y that is installed in a remote Enterprise Beans server. Bean Y updates data in database B. The Enterprise Beans architecture makes it possible to perform the updates to databases A and B in a single transaction.

When X invokes Y, the two Enterprise Beans servers cooperate to propagate the transaction context from X to Y. This transaction context propagation is transparent to the application-level code.

At transaction commit time, the two Enterprise Beans servers use a distributed two-phase commit protocol (if the capability exists) to ensure the atomicity of the database updates.

A Java client can use the jakarta.transaction.UserTransaction interface to explicitly demarcate transaction boundaries. The client program obtains the jakarta.transaction.UserTransaction interface through dependency injection or lookup in the bean’s EJBContext or in the JNDI name space.

A client program using explicit transaction demarcation may perform, via enterprise beans, atomic updates across multiple databases residing at multiple Enterprise Beans servers, as illustrated in the following figure.

The application programmer demarcates the transaction with begin and commit calls. If the enterprise beans X and Y are configured to use a client transaction (i.e., their methods have transaction attributes that either require or support an existing transaction context), the Enterprise Beans server ensures that the updates to databases A and B are made as part of the client’s transaction.

Whenever a client invokes a method on an enterprise bean’s business interface, on the bean no-interface view, on a home or component interface, or a message listener method, the container interposes on the method invocation. The interposition allows the container to control transaction demarcation declaratively through the transaction attribute set by the developer. (See Specification of the Transaction Attributes for a Bean’s Methods for a description of transaction attributes.)

For example, if a session bean method is configured with the REQUIRED transaction attribute, the container behaves as follows: If the client request is not associated with a transaction context, the container automatically initiates a transaction whenever a client invokes an enterprise bean method that requires a transaction context. If the client request contains a transaction context, the container includes the enterprise bean method in the client transaction.

The following figure illustrates such a scenario. A non-transactional client invokes the enterprise bean X, and the invoked method has the REQUIRED ^[42] transaction attribute. Because the invocation from the client does not include a transaction context, the container starts a new transaction before dispatching the method on X. Bean X’s work is performed in the context of the transaction. When X calls other enterprise beans (Y in our example), the work performed by the other enterprise beans is also automatically included in the transaction (subject to the transaction attribute of the other enterprise bean).

The container automatically commits the transaction at the time X returns a reply to the client.

If a message-driven bean’s message listener method is configured with the REQUIRED transaction attribute, the container automatically starts a new transaction before the delivery of the message and, hence, before the invocation of the method.^[43]

The container automatically enlists the resource manager associated with the arriving message and all the resource managers accessed by the message listener method with the transaction.

It is illegal to associate Jakarta Transactions transactional interceptors (see [17]) with Enterprise Beans.^[44]

When designing an enterprise bean, the developer must decide whether the enterprise bean will demarcate transactions programmatically in the business methods (bean-managed transaction demarcation), or whether the transaction demarcation is to be performed by the container based on the transaction attributes specified in metadata annotations or in the deployment descriptor (container-managed transaction demarcation). Typically enterprise beans will be specified to have container-managed transaction demarcation. This is the default if no transaction management type is specified.

A session bean or a message-driven bean can be designed with bean-managed transaction demarcation or with container-managed transaction demarcation. (But it cannot be both at the same time.)

An enterprise bean instance can access resource managers in a transaction only in the enterprise bean’s methods in which there is a transaction context available.

Transactions not only make completion of a unit of work atomic, but they also isolate the units of work from each other, provided that the system allows concurrent execution of multiple units of work.

The isolation level describes the degree to which the access to a resource manager by a transaction is isolated from the access to the resource manager by other concurrently executing transactions.

The following are guidelines for managing isolation levels in enterprise beans.

This subsection describes the requirements for the Bean Provider of an enterprise bean with bean-managed transaction demarcation.

The enterprise bean with bean-managed transaction demarcation must be a session bean or a message-driven bean.

An instance that starts a transaction must complete the transaction before it starts a new transaction.

The Bean Provider uses the UserTransaction interface to demarcate transactions. All updates to the resource managers between the UserTransaction.begin and UserTransaction.commit methods are performed in a transaction. While an instance is in a transaction, the instance must not attempt to use the resource-manager specific transaction demarcation API (e.g. it must not invoke the commit or rollback method on the java.sql.Connection interface or on the jakarta.jms.Session interface).^[45]

A stateful session bean instance may, but is not required to, commit a started transaction before a business method returns. If a transaction has not been completed by the end of a business method, the container retains the association between the transaction and the instance across multiple client calls until the instance eventually completes the transaction. A stateful session bean instance must commit a transaction before PostConstruct, PreDestroy, PrePassivate or PostActivate lifecycle callback interceptor method returns.

A stateless session bean instance must commit a transaction before a business method or timeout callback method returns.

A singleton session bean instance must commit a transaction before a business method or timeout callback method or PostConstruct or PreDestroy lifecycle callback interceptor method returns.

A message-driven bean instance must commit a transaction before a message listener method or timeout callback method returns.

If AroundInvoke interceptor methods are applied to the business method or AroundTimeout interceptor methods are applied to the timeout callback method of a singleton or a stateless session bean or a message-driven bean, the transaction must be completed before the last AroundInvoke or AroundTimeout interceptor method completes.

The following code segments illustrate a business method that performs a transaction involving two database connections.

The following code segments illustrate a business method that performs a transaction involving both a database connection and a Jakarta Messaging connection.

The following code segments illustrate a stateful session bean that retains a transaction across three client calls, invoked in the following order: method1, method2, and method3.^[46]

It is possible for an enterprise bean to open and close a database connection in each business method (rather than hold the connection open until the end of transaction). The following code segments illustrate a stateful session bean for which the client executes the sequence of methods (method1, method2, method2, method2, and method3). In this scenario, all the database updates done by the multiple invocations of method2 are performed in the scope of the same transaction, which is the transaction started in method1 and committed in method3.