EJB.9.2 Responsibilities of the Enterprise Bean Provider
This section describes the responsibilities of an entity bean provider to ensure that the entity bean can be deployed in any EJB container.
The requirements are stated for the provider of an entity bean with bean-managed persistence. The differences for entities with container-managed persistence are defined in Section EJB.9.4.
EJB.9.2.1 Classes and Interfaces
The entity bean provider is responsible for providing the following class files:
-
Entity bean class and any dependent classes
-
Entity bean's remote interface
-
Entity bean's home interface
-
Primary key class
EJB.9.2.2 Enterprise Bean Class
The following are the requirements for an entity bean class:
-
The class must implement, directly or indirectly, the
javax.ejb.EntityBean
interface.
-
The class must be defined as
public
and must not be
abstract
.
-
The class must not be defined as
final
.
-
The class must define a public constructor that takes no arguments.
-
The class must not define the
finalize()
method.
-
The class may, but is not required to, implement the entity bean's remote interface.
[4]
If the class implements the entity bean's remote interface, the class must provide no-op
implementations
of the
methods
defined in the
javax.ejb.EJBObject
interface. The container will never invoke these methods on the bean instances at runtime.
[4]
If the entity 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 entity bean class.
-
A no-op implementation of these methods is required to avoid defining the entity bean class as abstract.
-
The entity bean class must implement the business methods, and the
ejbCreate, ejbPostCreate,
and
ejbFind<METHOD>
methods as described later in this section.
-
The entity bean class may have superclasses and/or superinterfaces. If the entity bean has superclasses, the business methods, the
ejbCreate and ejbPostCreate
methods, the finder methods, and the methods of the
EntityBean
interface may be implemented in the enterprise bean class or in any of its superclasses.
-
The entity 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.9.2.3
ejbCreate
Methods
The entity bean class may define zero 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 the entity bean's primary key type.
-
The method argument and return value types must be legal types for RMI-IIOP.
-
The throws clause may define arbitrary application specific exceptions, 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
java.lang.RuntimeException
to indicate non-application exceptions to the container (see Section EJB.12.2.2).
The entity object created by the
ejbCreate
method must have a unique primary key. This means that the primary key must be different from the primary keys of all the existing entity objects within the same home. The
ejbCreate
method should throw the
DuplicateKeyException
on an attempt to create an entity object with a duplicate primary key. However, it is legal to reuse the primary key of a previously removed entity object.
EJB.9.2.4
ejbPostCreate
Methods
For each
ejbCreate(...)
method, the entity bean class must define a matching
ejbPostCreate(...)
method, using the following rules:
-
The method name must be
ejbPostCreate
.
-
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 the same as the arguments of the matching
ejbCreate(...)
method.
-
The throws clause may define arbitrary application specific exceptions, including the
javax.ejb.CreateException
.
Compatibility Note
EJB 1.0 allowed the
ejbPostCreate
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
java.lang.RuntimeException
to indicate non-application exceptions to the container (see Section EJB.12.2.2).
EJB.9.2.5
ejbFind
Methods
The entity bean class may also define additional
ejbFind<METHOD>(...)
finder methods.
The signatures of the finder methods must follow the following rules:
-
A finder method name must start with the prefix
ejbFind
(e.g.,
ejbFindByPrimaryKey
,
ejbFindLargeAccounts
,
ejbFindLateShipments
).
-
A finder method must be declared as
public
.
-
The method must not be declared as
final
or
static
.
-
The method argument types must be legal types for RMI-IIOP.
-
The return type of a finder method must be the entity bean's primary key type, or a collection of primary keys (see Section EJB.9.1.8).
-
The throws clause may define arbitrary application specific exceptions, including the
javax.ejb.FinderException
.
-
Every entity bean must define the
ejbFindByPrimaryKey
method. The result type for this method must be the primary key type (i.e., the
ejbFindByPrimaryKey
method must be a
single-object
finder).
Compatibility Note
EJB 1.0 allowed the finder 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
java.lang.RuntimeException
to indicate non-application exceptions to the container (see Section EJB.12.2.2).
EJB.9.2.6 Business Methods
The entity 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 method argument and return value types must be legal types for RMI-IIOP.
-
The throws clause may define arbitrary application specific 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
java.lang.RuntimeException
to indicate non-application exceptions to the container (see Section EJB.12.2.2).
EJB.9.2.7 Entity Bean's Remote Interface
The following are the requirements for the entity bean's remote interface:
-
The interface must extend the
javax.ejb.EJBObject
interface.
-
The methods defined in the remote interface must follow the rules for RMI-IIOP. This means that their argument and return value types must be valid types for RMI-IIOP, and their throws clauses 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 entity bean's class. The matching method must have:
-
- The same name.
-
- The same number and types of its arguments, and the same return type.
-
- All the exceptions defined in the throws clause of the matching method of the enterprise bean class must be defined in the throws clause of the method of the remote interface.
EJB.9.2.8 Entity Bean's Home Interface
The following are the requirements for the entity 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 types 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.
-
Each method defined in the home interface must be one of the following:
-
- A create method
-
- A finder method
-
Each
create
method must be named
create
, and it must match one of the
ejbCreate
methods defined in the enterprise bean class. The matching
ejbCreate
method must have the same number and types of its arguments. (Note that the return type is different.)
-
The return type for a
create
method must be the entity bean's remote interface type.
-
All the exceptions defined in the throws clause of the matching
ejbCreate
and
ejbPostCreate
methods of the enterprise bean class must be included in the throws clause of the matching
create
method of the home interface (i.e., the set of exceptions defined for the
create
method must be a superset of the union of exceptions defined for the
ejbCreate
and
ejbPostCreate
methods).
-
The throws clause of a
create
method must include the
javax.ejb.CreateException
.
-
Each
finder
method must be named
find<METHOD>
(e.g.,
findLargeAccounts
), and it must match one of the
ejbFind<METHOD>
methods defined in the entity bean class (e.g.,
ejbFindLargeAccounts
). The matching
ejbFind<METHOD>
method must have the same number and types of arguments. (Note that the return type may be different.)
-
The return type for a
find<METHOD>
method must be the entity bean's remote interface type (for a single-object finder), or a collection thereof (for a multi-object finder).
-
The home interface must always include the
findByPrimaryKey
method, which is always a single-object finder. The method must declare the primary key class as the method argument.
-
All the exceptions defined in the throws clause of an
ejbFind
method of the entity bean class must be included in the throws clause of the matching
find
method of the home interface.
-
The throws clause of a
finder
method must include the
javax.ejb.FinderException
.
EJB.9.2.9 Entity Bean's Primary Key Class
The bean provider must specify a primary key class in the deployment descriptor.
The primary key type must be a legal value type in RMI-IIOP.
The class must provide suitable implementation of the
hashCode()
and
equals(Object other)
methods to simplify the management of the primary keys by client code.
|