EJB.6.10 The Responsibilities of the Bean Provider

This section describes the responsibilities of session bean provider to ensure that a session bean can be deployed in any EJB container.

EJB.6.10.1 Classes and Interfaces

The session bean provider is responsible for providing the following class files:

• Session bean class

• Session bean's remote interface

• Session bean's home interface

EJB.6.10.2 Session Bean Class

The following are the requirements for session bean class:

• The class must implement, directly or indirectly, the javax.ejb.SessionBean interface.

• The class must be defined as public , must not be final , and must not be abstract .

• The class must have a public constructor that takes no parameters. The container uses this constructor to create instances of the session bean class.

• The class must not define the finalize() method.

• The class may, but is not required to, implement the session bean's remote interface. ^[3]

  ^[3] If the session bean class does implement the remote interface, care must be taken to avoid passing of this as a method argument or result. This potential error can be avoided by choosing not to implement the remote interface in the session bean class.

• The class must implement the business methods and the ejbCreate methods.

• If the class is a stateful session bean, it may optionally implement the javax.ejb.SessionSynchronization interface.

• The session bean class may have superclasses and/or superinterfaces. If the session bean has superclasses, then the business methods, the ejbCreate methods, the methods of the SessionBean interface, and the methods of the optional SessionSynchronization interface may be defined in the session bean class, or in any of its superclasses.

• The session bean class is allowed to implement other methods (for example, helper methods invoked internally by the business methods) in addition to the methods required by the EJB specification.

EJB.6.10.3 ejbCreate Methods

The session bean class must define one or more ejbCreate(...) methods whose signatures must follow these rules:

• The method name must be ejbCreate .

• The method must be declared as public .

• The method must not be declared as final or static .

• The return type must be void .

• The method arguments must be legal types for RMI-IIOP.

• The throws clause may define arbitrary application exceptions, possibly including the javax.ejb.CreateException .

Compatibility Note

EJB 1.0 allowed the ejbCreate method to throw the java.rmi.RemoteException to indicate a non-application exception. This practice is deprecated in EJB 1.1 ”an EJB 1.1 compliant enterprise bean should throw the javax.ejb.EJBException or another RuntimeException to indicate non-application exceptions to the container (see Section EJB.12.2.2).

EJB.6.10.4 Business Methods

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

• The method names can be arbitrary, but they must not start with " ejb " to avoid conflicts with the callback methods used by the EJB architecture.

• The business method must be declared as public .

• The method must not be declared as final or static .

• The argument and return value types for a method must be legal types for RMI-IIOP.

• The throws clause may define arbitrary application exceptions.

Compatibility Note

EJB 1.0 allowed the business methods to throw the java.rmi.RemoteException to indicate a non-application exception. This practice is deprecated in EJB 1.1 ”an EJB 1.1 compliant enterprise bean should throw the javax.ejb.EJBException or another RuntimeException to indicate non-application exceptions to the container (see Section EJB.12.2.2).

EJB.6.10.5 Session Bean's Remote Interface

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

• The interface must extend the javax.ejb.EJBObject interface.

• The methods defined in this interface must follow the rules for RMI-IIOP. This means that their argument and return values must be of valid types for RMI-IIOP, and their throws clause must include the java.rmi.RemoteException .

• The remote interface is allowed to have superinterfaces. Use of interface inheritance is subject to the RMI-IIOP rules for the definition of remote interfaces.

• For each method defined in the remote interface, there must be a matching method in the session bean's class. The matching method must have:

  - The same name.

  - The same number and types of arguments, and the same return type.

  - All the exceptions defined in the throws clause of the matching method of the session bean class must be defined in the throws clause of the method of the remote interface.

EJB.6.10.6 Session Bean's Home Interface

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

• The interface must extend the javax.ejb.EJBHome interface.

• The methods defined in this interface must follow the rules for RMI-IIOP. This means that their argument and return values must be of valid types for RMI-IIOP, and that their throws clause must include the java.rmi.RemoteException .

• The home interface is allowed to have superinterfaces. Use of interface inheritance is subject to the RMI-IIOP rules for the definition of remote interfaces.

• A session bean's home interface must define one or more create(...) methods.

• Each create method must be named " create ," and it must match one of the ejbCreate methods defined in the session bean class. The matching ejbCreate method must have the same number and types of arguments. (Note that the return type is different.)

• The return type for a create method must be the session bean's remote interface type.

• All the exceptions defined in the throws clause of an ejbCreate method of the session bean class must be defined in the throws clause of the matching create method of the home interface.

• The throws clause must include javax.ejb.CreateException .

EJB.6.11 The Responsibilities of the Container Provider

This section describes the responsibilities of the container provider to support a session bean. The container provider is responsible for providing the deployment tools and for managing the session bean instances at runtime.

Because the EJB specification does not define the API between deployment tools and the container, we assume that the deployment tools are provided by the container provider. Alternatively, the deployment tools may be provided by a different vendor who uses the container vendor's specific API.

EJB.6.11.1 Generation of Implementation Classes

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 enterprise bean provider and by examining the session bean's deployment descriptor.

The deployment tools must generate the following classes:

• A class that implements the session bean's home interface (session EJBHome class).

• A class that implements the session bean's remote interface (session EJBObject class).

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.

EJB.6.11.2 Session EJBHome Class

The session EJBHome class, which is generated by the deployment tools, implements the session bean's home interface. This class implements the methods of the javax.ejb.EJBHome interface and the create methods specific to the session bean.

The implementation of each create(...) method invokes a matching ejbCreate(...) method.

EJB.6.11.3 Session EJBObject Class

The session EJBObject class, which is generated by the deployment tools, implements the session bean's remote interface. It implements the methods of the javax.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) and invoke the matching business method on the instance.

EJB.6.11.4 Handle Classes

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

EJB.6.11.5 EJBMetaData Class

The deployment tools are responsible for implementing the class that provides meta-data to the client view contract. The class must be a valid RMI Value class and must implement the javax.ejb.EJBMetaData interface.

EJB.6.11.6 Non-Reentrant Instances

The container must ensure that only one thread can be executing an instance at any time. If a client request arrives for an instance while the instance is executing another request, the container must throw the java.rmi.RemoteException to the second request.

Note

A session object is intended to support only a single client. Therefore, it would be an application error if two clients attempted to invoke the same session object.

One implication of this rule is that an application cannot make loopback calls to a session bean instance.

EJB.6.11.7 Transaction Scoping, Security, Exceptions

The container must follow the rules with respect to transaction scoping, security checking, and exception handling, as described in Chapters EJB.11, EJB.15, and EJB.12, respectively.