Appendix A. The EJB 2.0 API

Interfaces

This appendix provides a quick reference of the EJB APIs. You should use this reference if you need to get quick information on which methods are implemented by a particular interface, the arguments for a method, or the return type. Although the exceptions are described in detail in Chapter 13, "Exception Handling," we provide a summary view of them here for your convenience.

Figure A.1 shows a UML diagram of the EJB interfaces and their relationships.

Figure A.1. A UML diagram representing the EJB interface hierarchy.

javax.ejb.EJBContext

An enterprise bean uses the EJBContext interface to gain access to the runtime context provided by the container. The EJBContext interface is the parent interface to the SessionContext and EntityContext interfaces, as shown in Figure A.1. Table A.1 shows the methods defined in the EJBContext interface.

Table A.1. The Methods of the EJBContext Interface

Return Type	Method Name
Identity	getCallerIdentity
Principal	getCallerPrincipal
EJBHome	getEJBHome
EJBLocalHome	getEJBLocalHome
Properties	getEnvironment
boolean	getRollbackOnly
UserTransaction	getUserTransaction
boolean	isCallerInRole
void	setRollbackOnly

getCallerIdentity

The getCallerIdentity method returns the java.security.Identity of the caller. Here is the method signature:

 public java.security.Identity getCallerIdentity(); 

Caution

The getCallerIdentity method has been deprecated. You should use the getCallerPrincipal method instead.

getCallerPrincipal

The getCallerPrincipal method returns a java.security.Principal , which identifies the caller. The method should never return null. Here is the method signature:

 public java.security.Principal getCallerPrincipal(); 

getEJBHome

The getEJBHome method returns the home interface of the enterprise bean. Here is the method signature:

 public javax.ejb.EJBHome getEJBHome(); 

getEJBLocalHome

The getEJBLocalHome method returns the local home interface of the enterprise bean. Here is the method signature:

 public javax.ejb.EJBLocalHome getEJBLocalHome(); 

getEnvironment

The getEnvironment method returns the enterprise bean's environment properties. This method has been deprecated. Here is the method signature:

 public Properties getEnvironment(); 

Caution

The getEnvironment method has been deprecated. You should use the JNDI naming context java:comp/env to access the bean's environment.

getRollbackOnly

The getRollbackOnly tests to see whether the transaction has been marked for rollback. Only enterprise beans with container-managed transactions are allowed to use this method. Here is the method signature:

 public boolean getRollbackOnly() throws IllegalStateException; 

An IllegalStateException will be thrown if the instance is not allowed to use this method. Typically, this is because the instance is using bean-managed transactions.

getUserTransaction

The getUserTransaction method returns the transaction demarcation interface. Only enterprise beans with bean-managed transactions are allowed to use the UserTransaction interface. Because entity beans must always use container-managed transactions, only session beans and message-driven beans with bean-managed transactions are allowed to invoke this method. Here is the method signature:

 public javax.transaction.UserTransaction getUserTransaction() throws  IllegalStateException; 

An IllegalStateException will be thrown if the instance is not allowed to use this method. Typically, this is because the instance is using container-managed transactions.

isCallerInRole

The isCallerInRole method tests to see whether the caller is in a given role. There are two variations of this method. Here are the method signatures:

 public boolean isCallerInRole(String roleName);  public boolean isCallerInRole(java.security.Identity roleName); 

The second method, which takes an Identity as its argument, is deprecated and should not be used. The roleName argument in the non-deprecated version must be one of the security roles defined in the deployment descriptor. This method returns true if the caller of the bean method is in the role specified by the argument.

Caution

The isCallerInRole method that takes a java.security.Identity has been deprecated and should not be used.

setRollbackOnly

The setRollbackOnly method marks the current transaction for rollback. The transaction will become permanently marked for rollback. A transaction marked for rollback can never commit. Only enterprise beans with container-managed transactions are allowed to use this method. Here is the method signature:

 public void setRollbackOnly() throws IllegalStateException; 

An IllegalStateException will be thrown if the instance is not allowed to use this method. Typically, this is because the instance is using bean-managed transactions.

javax.ejb.EJBHome

The EJBHome interface defines the methods that allow a remote client to create, locate, and remove enterprise beans. A bean provider must create a home interface for an entity or session bean, and the home interface must extend the EJBHome interface. The message-driven bean is not exposed to clients and therefore does not require a home interface. Table A.2 shows the methods in the EJBHome interface.

Table A.2. The Methods of the EJBHome Interface

Return Type	Method Name
EJBMetaData	getEJBMetaData
HomeHandle	getHomeHandle
void	remove

getEJBMetaData

The getEJBMetaData method obtains a reference to an object that implements the EJBMetaData interface for the enterprise bean. The EJBMetaData interface allows the client to obtain information about the enterprise bean. Here is the method signature:

 public EJBMetaData getEJBMetaData() throws java.rmi.RemoteException; 

getEJBHomeHandle

The getEJBHomeHandle returns a handle for the home object. The handle can be used at later time to re-obtain a reference to the home object, possibly in a different JVM. Here is the method signature:

 public EJBHomeHandle getEJBHomeHandle() throws java.rmi.RemoteException; 

remove

There are two variations of the remove method. Both cause the EJBObject to be removed. Here are the method signatures:

 public void remove(Handle handle) throws java.rmi.RemoteException, RemoveException;  public void remove(Object primaryKey) throws java.rmi.RemoteException, RemoveException; 

Caution

The remove method that takes a primary key can be used only for an entity bean. An attempt to call this method on a session bean will result in a RemoveException being thrown.

With either variation of the remove method, a RemoveException will be thrown if the enterprise bean or the container does not allow the client to remove the object. The RemoveException is described later in this appendix.

javax.ejb.EJBLocalHome

All enterprise beans that use a local home interface must extend their local home interface from the EJBLocalHome interface. The local home interface for an enterprise bean defines the methods that allow local clients to create, find, and remove EJB objects. It also can contain home business methods that are not specific to a specific bean instance. These home business methods can be defined only for entity beans.

remove

The remove method removes an object identified by its primary key. Here is the method signature:

 public void remove(Object primaryKey) throws RemoteException, EJBException; 

This method can be called only by local clients of an entity bean. An attempt to invoke this method on a session bean will result in a RemoveException .

javax.ejb.EJBLocalObject

The EJBLocalObject interface must be extended by all enterprise beans' local interfaces. An enterprise bean's local interface provides the local client view of an EJB object. Table A.3 shows the methods in the EJBLocalObject interface.

Table A.3. The Methods of the EJBLocalObject Interface

Return Type	Method Name
EJBLocalHome	getEJBLocalHome
Object	getPrimaryKey
boolean	isIdentical
void	remove

getEJBLocalHome

Obtain the enterprise bean's local home interface. The local home interface defines the enterprise bean's create , finder , remove , and home business methods that are available to local clients. Here is the method signature:

 public EJBLocalHome getEJBLocalHome() throws EJBException; 

getPrimaryKey

This method can be called on an entity bean. An attempt to invoke this method on a session bean will result in an EJBException . Here is the method signature:

 public Object getPrimaryKey() throws RemoteException, EJBException; 

isIdentical

Test whether a given EJB local object is identical to the invoked EJB local object. Here is the method signature:

 public boolean isIdentical(EJBLocalObject obj) throws EJBException; 

remove

Removes the EJB local object. Here is the method signature:

 public void remove() throws RemoveException, EJBException; 

javax.ejb.EJBMetaData

A client uses the EJBMetaData interface to obtain metadata information about an enterprise bean. The metadata is typically used by development tools or scripting languages. The EJBMetaData interface does not extend the Remote interface and is not accessed remotely by the client. An instance of this class is sent to the client as a copy, and changes to the object are not reflected on the server. Table A.4 shows the methods in the EJBMetaData interface.

Table A.4. The Methods of the EJBMetaData Interface

Return Type	Method Name
EJBHome	getEJBHome
Class	getHomeInterfaceClass
Class	getPrimaryKeyClass
Class	getRemoteInterfaceClass
boolean	isSession
boolean	isStatelessSession

Tip

The EJBMetaData class is designed for remote clients only. It is not supported with local clients.

getEJBHome

The getEJBHome method returns the home interface of the enterprise bean. Here is the method signature:

 public javax.ejb.EJBHome getEJBHome(); 

getHomeInterfaceClass

The getHomeInterfaceClass returns the Class object for the enterprise bean's home interface. Here is the method signature:

 public Class getHomeInterfaceClass(); 

getPrimaryKeyClass

The getPrimaryKeyClass returns the Class object for the enterprise bean's primary key class. Here is the method signature:

 public Class getPrimaryKeyClass(); 

getRemoteInterfaceClass

The getRemoteInterfaceClass returns the Class object for the enterprise bean's remote interface class. Here is the method signature:

 public Class getRemoteInterfaceClass(); 

isSession

The isSession method returns true if the enterprise bean is a session bean. Otherwise, it will return false. Here is the method signature:

 public boolean isSession(); 

isStatelessSession

The isStatelessSession method returns true if the enterprise bean is a stateless session bean. Otherwise it will return false. Here is the method signature:

 public boolean isStatelessSession(); 

javax.ejb.EJBObject

A bean provider creates a remote interface that extends the EJBObject interface. The remote interface defines the business methods that can be called by a remote client. Each enterprise bean, except for the message-driven, has a component interface. Table A.5 shows the methods in the EJBObject interface.

Table A.5. The Methods of the EJBObject Interface

Return Type	Method Name
EJBHome	getEJBHome
Handle	getHandle
Object	getPrimaryKey
boolean	isIdentical
void	remove

getEJBHome

The getEJBHome method returns the home interface of the enterprise bean. Here is the method signature:

 public javax.ejb.EJBHome getEJBHome() throws java.rmi.RemoteException; 

getHandle

The getHandle method returns a handle for the EJB object. The handle can be used at later time to re-obtain a reference to the EJB object, possibly in a different JVM. Here is the method signature:

 public Handle getHandle() throws java.rmi.RemoteException; 

getPrimaryKey

The getPrimaryKey method returns the primary key for an EJB object. This method can be called only on an entity bean. If you attempt to invoke this method on a session bean, a RemoteException will be thrown. Here is the method signature:

 public Object getPrimaryKey() throws java.rmi.RemoteException; 

isIdentical

The isIdentical method tests whether a given EJB object is identical to the invoked EJB object. Here's the method signature:

 public boolean isIdentical(EJBObject obj) throws java.rmi.RemoteException; 

The method returns true if the given EJB object is identical to the one invoked. Otherwise false is returned.

remove

The remove method removes the EJB object. Here is the method signature:

 public void remove() throws java.rmi.RemoteException, RemoveException; 

If the enterprise bean or the container does not allow destruction of the object, a RemoveException is thrown.

javax.ejb.EnterpriseBean

Every enterprise bean class must implement the EnterpriseBean interface. The EnterpriseBean interface does not define any methods itself but acts as a placeholder for future methods. It is a common superinterface for SessionBean and EntityBean .

javax.ejb.EntityBean

Every entity bean class must implement the EntityBean interface. The container uses the EntityBean methods to notify enterprise bean instances of lifecycle events. Table A.6 shows the methods in the EntityBean interface.

Table A.6. The Methods of the EntityBean Interface

Return Type	Method Name
void	ejbActivate
void	ejbLoad
void	ejbPassivate
void	ejbRemove
void	ejbStore
void	setEntityContext
void	unsetEntityContext

Tip

In the next several methods, the RemoteException is defined in the method signature to provide backward compatibility with enterprise beans written for the EJB 1.0 Specification. Enterprise beans written for the EJB 1.1 and 2.0 Specifications should throw the javax.ejb.EJBException instead of the RemoteException .

ejbActivate

The container invokes the ejbActivate method when the instance is taken out of the pool of available instances and becomes associated with a specific EJB object. Here is the method signature:

 public void ejbActivate() throws java.rmi.RemoteException, EJBException; 

ejbLoad

The container invokes the ejbLoad method to instruct the instance to synchronize its state by loading its state from the underlying database. Here is the method signature:

 public void ejbLoad() throws java.rmi.RemoteException, EJBException; 

This method always executes in the transaction context determined by the value of the transaction attribute in the deployment descriptor.

ejbPassivate

The container invokes the ejbPassivate method on an instance before the instance becomes disassociated with a specific EJB object. After this method completes, the container will place the instance into the pool of available instances. Here is the method signature:

 public void ejbPassivate() throws java.rmi.RemoteException, EJBException; 

ejbRemove

The container invokes the ejbRemove method before it removes the EJB object that is currently associated with the instance. This method is invoked when a client invokes a remove operation on the enterprise bean. Here is the method signature:

 public void ejbRemove() throws java.rmi.RemoteException, EJBException, RemoveException; 

ejbStore

The container invokes the ejbStore method to instruct the instance to synchronize its state by storing it to the underlying database. This method always executes in the transaction context determined by the value of the transaction attribute in the deployment descriptor. Here is the method signature:

 public void ejbStore() throws java.rmi.RemoteException, EJBException; 

setEntityContext

The container invokes the ejbStore method on an instance after the instance has been created to set the associated entity context. The bean instance should store the context in an instance variable. Here is the method signature:

 public void setEntityContext(EntityContext ctx) throws java.rmi.RemoteException,  EJBException; 

unsetEntityContext

The container invokes the ejbStore method on an instance before removing the instance. This is the last method that the container invokes on the instance. Here is the method signature:

 public void unsetEntityContext() throws java.rmi.RemoteException, EJBException; 

javax.ejb.EntityContext

The EntityContext interface provides an instance with access to the container-provided runtime context. The container passes the EntityContext interface to an entity enterprise bean instance after the instance has been created. The EntityContext interface remains associated with the instance for the lifetime of the instance. Table A.7 shows the methods in the EntityContext interface.

Table A.7. The Methods of the EntityContext Interface

Return Type	Method Name
EJBLocalObject	getEJBLocalObject
EJBObject	getEJBObject
Object	getPrimaryKey

getEJBLocalObject

The getEJBObject method returns a reference to the EJB local object that currently is associated with the instance. An instance can use this method, for example, when it wants to pass itself as a reference in a method argument or return value. Here is the method signature:

 public EJBLocalObject getEJBLocalObject() throws IllegalStateException; 

An IllegalStateException will be thrown if an instance invokes this method while the instance is in a state that does not allow this method to be invoked or if the enterprise bean does not have a local interface.

getEJBObject

The getEJBObject method returns a reference to the EJB object that is currently associated with the instance. An instance can use this method, for example, when it wants to pass a reference to itself in a method argument or result. Here is the method signature:

 public EJBObject getEJBObject() throws IllegalStateException; 

An IllegalStateException will be thrown if an instance invokes this method while the instance is in a state that does not allow this method to be invoked.

getPrimaryKey

The getPrimaryKey method returns the primary key of the EJB object that is currently associated with this instance. Only an instance of an entity bean can call this method. Here is the method signature:

 public Object getPrimaryKey() throws IllegalStateException; 

Note

The result of this method is the same as the result of calling the getEJBObject().getPrimaryKey() .

javax.ejb.Handle

A handle is an abstraction of a network reference to an EJB object. A handle can be used as a persistent reference to an EJB object and can be re-created later. The Handle interface has one method, getEJBObject ; its return type is EJBObject .

getEJBObject

The getEJBObject method returns a reference to the EJB object that is currently associated with the instance. An instance can use this method, for example, when it wants to pass a reference to itself in a method argument or result. Here is the method signature:

 public EJBObject getEJBObject() throws java.rmi.RemoteException; 

javax.ejb.HomeHandle

The HomeHandle interface is an abstraction of a network reference to a home object. A HomeHandle can be used as a persistent reference to a home object and can be shared between clients. The HomeHandle interface has one method, getEJBHome ; its return type is EJBHome .

getEJBHome

The getEJBObject method returns a reference to the EJB object that is currently associated with the instance. An instance can use this method, for example, when it wants to pass a reference to itself in a method argument or result. Here is the method signature:

 public EJBObject getEJBObject() throws java.rmi.RemoteException; 

javax.ejb.MessageDrivenBean

Every message-driven enterprise bean implements the MessageDrivenBean interface. The container uses the message-driven bean methods to notify the bean instances of lifecycle events. Table A.8 shows the methods in the MessageDrivenBean interface.

Table A.8. The Methods of the MessageDrivenBean Interface

Return Type	Method Name
void	ejbRemove
void	setMessageDrivenContext

ejbRemove

The container invokes the ejbRemove method before it ends the life of the message-driven object. This happens when a container decides to terminate the message-driven object. Here is the method signature:

 public void ejbRemove() throws EJBException; 

setMessageDrivenContext

The container calls the setMessageDrivenContext method after the instance creation. The enterprise bean instance should store the reference to the context object in an instance variable. Here is the method signature:

 public void setMessageDrivenContext(MessageDrivenContext ctx) throws EJBException; 

javax.ejb.MessageDrivenContext

As Figure A.1 shows, the MessageDrivenContext interface extends the EJBContext interface. In EJB 2.0, the MessageDrivenContext interface does not define any methods, but merely serves as a marker to identify a runtime context as belonging to a message-driven bean.

javax.ejb.SessionBean

Every session bean must implement the SessionBean interface. The container uses the SessionBean methods to notify the bean instances of lifecycle events. Table A.9 shows the methods in the SessionBean interface.

Table A.9. The Methods of the SessionBean Interface

Return Type	Method Name
void	ejbActivate
void	ejbPassivate
void	ejbRemove
void	setSessionContext

Tip

With several of the methods that follow, the RemoteException is defined in the method signature to provide backward compatibility with enterprise beans written for the EJB 1.0 Specification. Enterprise beans written for the EJB 1.1 and 2.0 Specifications should throw the javax.ejb.EJBException instead of the RemoteException .

ejbActivate

The ejbActivate method is called when the instance is activated from its "passive" state. The instance should acquire any resource that it needs for its life cycle. Here is the method signature:

 public void ejbActivate() throws java.rmi.RemoteException, EJBException; 

ejbPassivate

The ejbPassivate method is called before the instance enters the "passive" state. The instance should release any resources that it is holding on to. After the ejbPassivate method completes, the instance must be in a state that allows the container to use the Java Serialization protocol to externalize and store away the instance's state. Here is the method signature:

 public void ejbPassivate() throws java.rmi.RemoteException, EJBException; 

ejbRemove

The container calls the ejbRemove method before it ends the life of the session object. This happens as a result of a client's invoking a remove operation, or when a container decides to terminate the session object after a timeout. Here is the method signature:

 public void ejbRemove() throws java.rmi.RemoteException, EJBException; 

setSessionContext

The container calls the setSessionContext method after the instance creation. The enterprise bean instance should store the reference to the context object in an instance variable. Here is the method signature:

 public void setSessionContext(SessionContext ctx) throws java.rmi.RemoteException,  EJBException; 

javax.ejb.SessionContext

The SessionContext interface provides access to the runtime session context that the container provides for a session bean instance. The container passes the SessionContext interface to a session bean instance after the instance has been created. The session context remains associated with the instance for its lifetime.

Table A.10 shows the methods in the SessionContext interface.

Table A.10. The Methods of the SessionContext Interface

Return Type	Method Name
EJBLocalObject	getEJBLocalObject
EJBObject	getEJBObejct

getEJBLocalObject

The getEJBLocalObject returns a reference to the local EJB object that currently is associated with the instance. An instance can use this method, for example, when it wants to pass a reference to itself in a method argument or result. Here is the method signature:

 public EJBLocalObject getEJBLocalObject() throws IllegalStateException; 

An IllegalStateException will be thrown if an instance invokes this method while the instance is in a state that does not allow this method to be invoked or if the enterprise bean does not have a local interface.

getEJBObject

The getEJBObject returns a reference to the EJB object that is currently associated with the instance. An instance can use this method, for example, when it wants to pass a reference to itself in a method argument or result. Here is the method signature:

 public EJBObject getEJBObject() throws IllegalStateException; 

javax.ejb.SessionSynchronization

The SessionSynchronization interface allows a session bean instance to be notified by the container of transaction boundaries. A session bean class is not required to implement this interface. Table A.11 shows the methods in the SessionSynchronization interface.

Table A.11. The Methods of the SessionSynchronization Interface

Return Type	Method Name
void	afterBegin
void	afterCompletion
void	beforeCompletion

Tip

With several of the methods that follow, the RemoteException is defined in the method signature to provide backward compatibility with enterprise beans written for the EJB 1.0 Specification. Enterprise beans written for the EJB 1.1 and 2.0 Specifications should throw the javax.ejb.EJBException instead of the RemoteException .

afterBegin

The afterBegin method notifies a session bean instance that a new transaction has started, and that the subsequent business methods on the instance will be invoked in the context of the transaction. The instance can use this method, for example, to read data from a database and cache the data in the instance fields. Here is the method signature:

 public void afterBegin() throws java.rmi.RemoteException, EJBException; 

afterCompletion

The afterCompletion method notifies a session bean instance that a transaction commit protocol has completed, and tells the instance whether the transaction has been committed or rolled back. Here is the method signature:

 public void afterCompletion(boolean committed) throws java.rmi.RemoteException,  EJBException; 

The argument is true if the transaction has been committed, false if the transaction has been rolled back.

beforeCompletion

The beforeCompletion method notifies a session bean instance that a transaction is about to be committed. The instance can use this method, for example, to write any cached data to a database. Here is the method signature:

 public void beforeCompletion() throws java.rmi.RemoteException, EJBException;