Chapter 19. The javax.ejb Package

CreateException	EJB 1.0
javax.ejb	serializable checked

This exception must be thrown by all create() methods declared in an Enterprise JavaBeans object's home interface. It is thrown if an error occurs during the process of creating the bean, as opposed to a communications error with the server before or after the bean is created.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->CreateException

Subclasses: DuplicateKeyException

DuplicateKeyException	EJB 1.0
javax.ejb	serializable checked

This extension of CreateException is thrown if a client attempts to create an entity bean using a primary key that matches the key of an existing entity bean of the same type.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->CreateException-->DuplicateKeyException

EJBContext	EJB 1.0
javax.ejb

The EJBContext interface is the base interface for context objects provided to EJB objects by their containers. EJBContext represents runtime context information the EJB object can use during method calls to check on environment variables, query the identity of the caller, etc.

The getCallerIdentity() and isCallerInRole() methods are provided to allow the EJB object to check on the identity of the caller, if it is known. The getEnvironment() method provides a Properties list with any environment variables the EJB container exports to its EJB objects. The getEJBHome() method returns an instance of the EJB object's home interface, which allows the EJB object to query about its own type, implementing classes, etc.

The rest of the EJBContext methods are related to transaction support. The getUserTransaction() method is the EJB object's access to the container-provided implementation of the javax.transaction.UserTransaction interface. The getRollbackOnly() method tells the EJB object if it is operating within a transaction that has been rolled back, and the setRollbackOnly() method sets the current enclosing transaction, if any, to be rolled back.

Implementations: EntityContext, SessionContext

EJBException	EJB 1.0
javax.ejb	serializable checked

Thrown by an Enterprise JavaBeans implementation when it encounters an error during the execution of a client-invoked business method or a container-invoked notification method. The container receives the exception (since it serves as a proxy for all client interactions with the bean) and is responsible for converting the EJBException to an appropriate subclass of java.rmi.RemoteException to be returned to the client.

If the EJB object was operating within a container-defined transaction context when the exception was thrown, the container does a rollback on the transaction before throwing the RemoteException to the client. If the bean was operating within a client-defined transaction context, the container marks the transaction for rollback and throws a javax.transaction.TransactionRolledbackException (a subclass of RemoteException) to the client, to indicate that it should give up on its transaction.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->EJBException

EJBHome	EJB 1.0
javax.ejb	remote

The EJBHome interface is the base interface for all home interfaces for Enterprise JavaBeans. If you develop an Enterprise JavaBeans object, you have to provide a home interface for it that extends this interface. The home interface allows clients to create beans of the corresponding type and to find them, if it is an entity bean. When you extend the EJBHome interface to create a home interface for your EJB object type, you must specify any create or finder methods for the bean you intend to provide for the client. The EJBHome interface provides two remove() methods that let a client remove its reference to a bean from the container and a getEJBMetaData() method that returns an EJBMetaData instance for the EJB object's type.

Hierarchy: (EJBHome(java.rmi.Remote))

Returned By: EJBContext.getEJBHome(), EJBMetaData.getEJBHome(), EJBObject.getEJBHome()

EJBMetaData	EJB 1.0
javax.ejb

This interface provides metadata on a particular type of Enterprise JavaBeans object. It allows you to query for the bean type's home interface, the Class for its home interface, the Class of its primary key (for entity beans only), the Class for its remote interface, and whether the bean is a session bean or an entity bean. This metadata might be used by EJB development tools to introspect on additional aspects of EJB classes that cannot be obtained from the Object introspection methods. Any implementation of this interface is required to be serializable and must be valid for use over RMI.

Returned By: EJBHome.getEJBMetaData()

EJBObject	EJB 1.0
javax.ejb	remote

This interface is the base interface for all remote interfaces for Enterprise JavaBeans. When a client acquires a remote reference to an EJB object, it is given an instance of the EJBObject interface as a stub. If you develop an Enterprise JavaBeans object, you must provide a remote interface for it by extending the EJBObject interface. In the remote interface for your EJB object type, you specify the business methods on your bean that are accessible by remote clients.

The EJBObject interface provides methods that allow a client to query the bean's home interface, get a portable handle for the remote bean, get the primary key for the bean (if it is an entity bean), compare the bean for equality with another bean, and remove the client's reference to the bean.

Hierarchy: (EJBObject(java.rmi.Remote))

Passed To: EJBObject.isIdentical()

Returned By: EntityContext.getEJBObject(), Handle.getEJBObject(), SessionContext.getEJBObject()

EnterpriseBean	EJB 1.0
javax.ejb	serializable

This interface is the base interface for all Enterprise JavaBeans implementations. If you develop an Enterprise JavaBeans object, your bean implementation must extend this interface, usually by extending one of the derived interfaces, SessionBean or EntityBean. The EnterpriseBean interface is a marker interface only and does not define any methods.

Hierarchy: (EnterpriseBean(Serializable))

Implementations: EntityBean, SessionBean

EntityBean	EJB 1.0
javax.ejb	serializable

This interface is the base interface for all entity EJB objects. The methods defined on the EntityBean interface are used by EJB containers to notify the entity bean about entity-specific events, such as the need to (re)load its state from persistent storage.

The ejbActivate() and ejbPassivate() methods are called on the bean by the container when the bean is associated and disassociated with a specific entity, respectively. The ejbLoad() and ejbStore() methods are called when the entity bean needs to read and write its persistent state, respectively. The ejbRemove() method is called when the entity associated with this bean should be removed from persistent storage. When the container sets the entity bean's context, it calls the setEntityContext() method. The container removes the association with a given context by calling the unsetEntityContext() method.

Hierarchy: (EntityBean(EnterpriseBean(Serializable)))

EntityContext	EJB 1.0
javax.ejb

This extension of the EJBContext interface represents runtime context information for an entity bean. In addition to the context provided by the EJBContext methods, EntityContext allows the entity bean to query for its primary key and a remote reference to itself.

Hierarchy: (EntityContext(EJBContext))

Passed To: EntityBean.setEntityContext()

FinderException	EJB 1.0
javax.ejb	serializable checked

This exception must be thrown by any finder methods declared on an entity bean's home interface. It is thrown if an error occurred while the server attempted to find the requested entity or entities.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->FinderException

Subclasses: ObjectNotFoundException

Handle	EJB 1.0
javax.ejb

A Handle represents a portable reference to a remote EJB object, in that it can be serialized, passed across Java VM boundaries, and then used to reconstitute a remote reference to the same EJB object from which it was acquired. You acquire a handle for an EJB object using the getHandle() method on its remote EJBObject.

The Handle interface acts as a base interface for EJB type-specific handle classes, which are typically generated for you by container deployment tools. Its only method is getEJBObject(), which returns a remote reference to the EJB object that it represents.

Passed To: EJBHome.remove()

Returned By: EJBObject.getHandle()

ObjectNotFoundException	EJB 1.0
javax.ejb	serializable checked

This subclass of FinderException is thrown by finder methods that are declared to return a single entity bean, when the requested entity can't be found in the server's persistent storage.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->FinderException-->ObjectNotFoundException

RemoveException	EJB 1.0
javax.ejb	serializable checked

Thrown by the remove methods on an EJB home interface, when an attempt to remove a bean from its container is rejected or fails at either the container or the EJB object level.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->RemoveException

Thrown By: EJBHome.remove(), EJBObject.remove(), EntityBean.ejbRemove()

SessionBean	EJB 1.0
javax.ejb	serializable

This is the base interface for all session Enterprise JavaBeans implementations. The methods on this interface are used by the EJB container to notify the bean about certain events.

The ejbActivate() and ejbPassivate() methods are invoked by the container when the bean leaves/enters (respectively) a passive state in the container. After the ejbPassivate() method completes, the container should be able to serialize the bean object and store it to disk or some other persistent storage, if the container chooses. During the ejbActivate() method, the bean can restore any data or resources it released when it was passivated. The container calls ejbRemove() on the bean just before the bean is destroyed. The container sets the bean's context by calling its setSessionContext() method. The session bean keeps the same context throughout its lifetime, so there is no corresponding unset method, as there is for EntityBean.

Hierarchy: (SessionBean(EnterpriseBean(Serializable)))

SessionContext	EJB 1.0
javax.ejb

This extension of the EJBContext interface represents runtime context information for a session bean. In addition to the context provided by the EJBContex methods, SessionContext allows the session bean to query for a remote reference to itself.

Hierarchy: (SessionContext(EJBContext))

Passed To: SessionBean.setSessionContext()

SessionSynchronization	EJB 1.0
javax.ejb

Session beans are not required to be transactional, but if you want your session bean to be notified of transaction boundaries, you can have your bean implementation class extend the SessionSynchronization interface. The EJB container invokes the methods on this interface to notify your bean about the start and end of transactions.

The afterBegin() is called when a new transaction has started. Any business methods invoked on the bean between this point and a subsequent call to its beforeCompletion() method execute within the context of this transaction. The beforeCompletion() method is called on the bean when a transaction is about to end. The afterCompletion() method is called after the transaction has ended, and the boolean argument tells the bean whether the transaction was committed successfully (true) or rolled back (false).