start page | rating of books | rating of authors | reviews | copyrights

Book Home Java Enterprise in a Nutshell Search this book

Chapter 19. The javax.ejb Package

The javax.ejb package is the primary package in the Enterprise JavaBeans API. It contains interfaces for all the key entities you need to create and use EJB objects. It also contains a number of EJB-specific exceptions. Figure 19-1 shows the class hierarchy of this package.

There are no concrete implementations provided for any of the interfaces in the javax.ejb package. EJB providers build their own implementations based on the EJB specification and provide them in their EJB-enabled servers. You should, however, build EJB server objects and clients strictly using the standard interfaces defined in this package, in order to keep your code compatible with any standard EJB server.

figure

Figure 19-1. The javax.ejb package

CreateExceptionEJB 1.0
javax.ejbserializable 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.

public class CreateException extends Exception {
// Public Constructors
public CreateException ();
public CreateException (String message);
}

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

Subclasses: DuplicateKeyException

DuplicateKeyExceptionEJB 1.0
javax.ejbserializable 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.

public class DuplicateKeyException extends CreateException {
// Public Constructors
public DuplicateKeyException ();
public DuplicateKeyException (String message);
}

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

EJBContextEJB 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.

public interface EJBContext {
// Public Instance Methods
public abstract java.security.Identity getCallerIdentity ();
public abstract EJBHome getEJBHome ();
public abstract java.util.Properties getEnvironment ();
public abstract boolean getRollbackOnly ();
public abstract javax.jts.UserTransaction getUserTransaction () throws java.lang.IllegalStateException;
public abstract boolean isCallerInRole (java.security.Identity role);
public abstract void setRollbackOnly ();
}

Implementations: EntityContext, SessionContext

EJBExceptionEJB 1.0
javax.ejbserializable 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.

public class EJBException extends Exception {
// Public Constructors
public EJBException ();
public EJBException (Exception ex);
public EJBException (String message);
// Public Instance Methods
public Exception getCausedByException (); default:null
}

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

EJBHomeEJB 1.0
javax.ejbremote

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.

public interface EJBHome extends java.rmi.Remote {
// Public Instance Methods
public abstract EJBMetaData getEJBMetaData () throws java.rmi.RemoteException;
public abstract void remove (Object primaryKey) throws java.rmi.RemoteException, RemoveException;
public abstract void remove (Handle handle) throws java.rmi.RemoteException, RemoveException;
}

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

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

EJBMetaDataEJB 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.

public interface EJBMetaData {
// Public Instance Methods
public abstract EJBHome getEJBHome ();
public abstract Class getHomeInterfaceClass ();
public abstract Class getPrimaryKeyClass ();
public abstract Class getRemoteInterfaceClass ();
public abstract boolean isSession ();
}

Returned By: EJBHome.getEJBMetaData()

EJBObjectEJB 1.0
javax.ejbremote

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.

public interface EJBObject extends java.rmi.Remote {
// Public Instance Methods
public abstract EJBHome getEJBHome () throws java.rmi.RemoteException;
public abstract Handle getHandle () throws java.rmi.RemoteException;
public abstract Object getPrimaryKey () throws java.rmi.RemoteException;
public abstract boolean isIdentical (EJBObject obj) throws java.rmi.RemoteException;
public abstract void remove () throws java.rmi.RemoteException, RemoveException;
}

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

Passed To: EJBObject.isIdentical()

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

EnterpriseBeanEJB 1.0
javax.ejbserializable

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.

public interface EnterpriseBean extends Serializable {
}

Hierarchy: (EnterpriseBean(Serializable))

Implementations: EntityBean, SessionBean

EntityBeanEJB 1.0
javax.ejbserializable

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.

public interface EntityBean extends EnterpriseBean {
// Public Instance Methods
public abstract void ejbActivate () throws java.rmi.RemoteException;
public abstract void ejbLoad () throws java.rmi.RemoteException;
public abstract void ejbPassivate () throws java.rmi.RemoteException;
public abstract void ejbRemove () throws java.rmi.RemoteException, RemoveException;
public abstract void ejbStore () throws java.rmi.RemoteException;
public abstract void setEntityContext (EntityContext ctx) throws java.rmi.RemoteException;
public abstract void unsetEntityContext () throws java.rmi.RemoteException;
}

Hierarchy: (EntityBean(EnterpriseBean(Serializable)))

EntityContextEJB 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.

public interface EntityContext extends EJBContext {
// Public Instance Methods
public abstract EJBObject getEJBObject () throws java.lang.IllegalStateException;
public abstract Object getPrimaryKey () throws java.lang.IllegalStateException;
}

Hierarchy: (EntityContext(EJBContext))

Passed To: EntityBean.setEntityContext()

FinderExceptionEJB 1.0
javax.ejbserializable 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.

public class FinderException extends Exception {
// Public Constructors
public FinderException ();
public FinderException (String message);
}

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

Subclasses: ObjectNotFoundException

HandleEJB 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.

public interface Handle {
// Public Instance Methods
public abstract EJBObject getEJBObject () throws java.rmi.RemoteException;
}

Passed To: EJBHome.remove()

Returned By: EJBObject.getHandle()

ObjectNotFoundExceptionEJB 1.0
javax.ejbserializable 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.

public class ObjectNotFoundException extends FinderException {
// Public Constructors
public ObjectNotFoundException ();
public ObjectNotFoundException (String message);
}

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

RemoveExceptionEJB 1.0
javax.ejbserializable 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.

public class RemoveException extends Exception {
// Public Constructors
public RemoveException ();
public RemoveException (String message);
}

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

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

SessionBeanEJB 1.0
javax.ejbserializable

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.

public interface SessionBean extends EnterpriseBean {
// Public Instance Methods
public abstract void ejbActivate () throws java.rmi.RemoteException;
public abstract void ejbPassivate () throws java.rmi.RemoteException;
public abstract void ejbRemove () throws java.rmi.RemoteException;
public abstract void setSessionContext (SessionContext ctx) throws java.rmi.RemoteException;
}

Hierarchy: (SessionBean(EnterpriseBean(Serializable)))

SessionContextEJB 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.

public interface SessionContext extends EJBContext {
// Public Instance Methods
public abstract EJBObject getEJBObject () throws java.lang.IllegalStateException;
}

Hierarchy: (SessionContext(EJBContext))

Passed To: SessionBean.setSessionContext()

SessionSynchronizationEJB 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).

public interface SessionSynchronization {
// Public Instance Methods
public abstract void afterBegin () throws java.rmi.RemoteException;
public abstract void afterCompletion (boolean committed) throws java.rmi.RemoteException;
public abstract void beforeCompletion () throws java.rmi.RemoteException;
}


Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.