This appendix is a quick reference guide to the Enterprise JavaBeans API. Within each package, the classes are organized alphabetically.
This package contains the heart of the EJB
API. It consists mostly of interfaces, many of which are implemented
by your EJB vendor. These interfaces essentially define the services
provided by the bean’s container, the services that must be
implemented by the bean itself, and the client interface to an
enterprise bean. The javax.ejb
package also
contains a number of exceptions that are thrown by enterprise beans.
This standard system exception is thrown by local component interfaces to indicate that the caller (enterprise bean) does not have permission to access the method.
public class AccessLocalException extends EJBException { public AccessLocalException(); public AccessLocalException(String message); public AccessLocalException(String message, Exception ex); }
This standard application exception must be thrown by all create methods that are defined in the home interface; it indicates that the bean could not be created.
public class javax.ejb.CreateException extends java.lang.Exception { public CreateException(); public CreateException(String message); }
This standard application exception is thrown by the create methods of the home interface of entity beans; it indicates that a bean with the same primary key already exists.
public class javax.ejb.DuplicateKeyException extends javax.ejb.CreateException { public DuplicateKeyException(); public DuplicateKeyException(String message); }
This is the base class for the EntityContext
,
SessionContext
, and
MessageDrivenContext
.
EJBContext
is the bean class’s interface to
the container system. It provides information about the enterprise
bean’s security identity and transaction status. It also
provides access to environment variables and the bean’s EJB
home.
public interface javax.ejb.EJBContext { public abstract Principal getCallerPrincipal(); public abstract EJBHome getEJBHome(); public abstract EJBLocalHome getEJBLocalHome(); // new in 2.0 public abstract boolean getRollbackOnly(); public abstract UserTransaction getUserTransaction(); public abstract Properties getEnvironment(); // deprecated public abstract Identity getCallerIdentity(); // deprecated public abstract boolean isCallerInRole(Identity role); // deprecated public abstract boolean isCallerInRole(String roleName); public abstract void setRollbackOnly(); }
This RuntimeException
is thrown by the bean class
from its business methods and callback methods to indicate that an
unexpected exception has occurred. The exception causes the ongoing
transaction to be rolled back and the bean instance to be destroyed.
public class javax.ejb.EJBException extends java.lang.RuntimeException { public EJBException(); public EJBException(String message); public EJBException(Exception exception); public Exception getCausedByException(); }
This interface must be extended by the bean’s remote home interface, a developer-provided class that defines the bean’s life-cycle methods. The enterprise bean’s create, find, and home methods are defined in the remote home interface. This interface is implemented by the bean’s EJB home.
public interface javax.ejb.EJBHome extends java.rmi.Remote { public abstract HomeHandle getHomeHandle(); public abstract EJBMetaData getEJBMetaData(); public abstract void remove(Handle handle); public abstract void remove(Object primaryKey); }
This interface must be extended by the bean’s local home interface, a developer-provided class that defines the bean’s life-cycle methods. The enterpise bean’s create, find, and home methods are defined in the local home interface. This interface is implemented by the bean’s EJB home.
public interface EJBLocalHome { public void remove(java.lang.Object primaryKey) throws RemoveException,EJBException; }
This interface defines the base functionality for access to local
enterprise beans; it is implemented by the EJB object. The developer
must provide a local interface for the bean that defines the business
methods of the bean, and the local interface must extend the
EJBLocalObject
interface.
public interface EJBLocalObject { public EJBLocalHome getEJBLocalHome() throws EJBException; public Object getPrimaryKey() throws EJBException; public boolean isIdentical(EJBLocalObject obj) throws EJBException; public void remove() throws RemoveException, EJBException; }
This interface is implemented by the container vendor to provide a serializable class that contains information about the bean.
public interface javax.ejb.EJBMetaData { public abstract EJBHome getEJBHome(); public abstract Class getHomeInterfaceClass(); public abstract Class getPrimaryKeyClass(); public abstract Class getRemoteInterfaceClass(); public abstract boolean isSession(); public abstract boolean isStatelessSession(); }
This interface defines the base functionality for access to remote
enterprise beans; it is implemented by the EJB object. The developer
must provide a remote interface for the bean that defines the
business methods of the bean, and the remote interface must extend
the EJBObject
interface.
public interface javax.ejb.EJBObject extends java.rmi.Remote { public abstract EJBHome getEJBHome(); public abstract Handle getHandle(); public abstract Object getPrimaryKey(); public abstract boolean isIdentical(EJBObject obj); public abstract void remove(); }
This interface is extended by the
EntityBean
, SessionBean
, and
MessageDrivenBean
interfaces. It serves as a
common typing mechanism.
public interface javax.ejb.EnterpriseBean extends java.io.Serializable {}
This interface must be implemented by the entity bean class. It provides a set of callback notification methods that alert the bean instance that it is about to experience or has just experienced some change in its life cycle.
public interface javax.ejb.EntityBean extends javax.ejb.EnterpriseBean { public abstract void ejbActivate(); public abstract void ejbLoad(); public abstract void ejbPassivate(); public abstract void ejbRemove(); public abstract void ejbStore(); public abstract void setEntityContext(EntityContext ctx); public abstract void unsetEntityContext(); }
This
interface is a specialization of the EJBContext
that provides methods for obtaining an
EntityBean
’s EJB object reference and
primary key. The EntityContext
provides the bean
instance with an interface to the container.
public interface javax.ejb.EntityContext extends javax.ejb.EJBContext { public abstract EJBObject getEJBObject(); public abstract Object getPrimaryKey(); public abstract EJBLocalObject getEJBLocalObject(); //new in EJB 2.0 }
This standard application exception is thrown by find methods defined in the home interface to indicate that a failure occurred during the execution of the find method.
public class javax.ejb.FinderException extends java.lang.Exception { public FinderException(); public FinderException(String message); }
This interface provides the client with a serializable object that can be used to obtain a remote reference to a specific bean.
public interface javax.ejb.Handle extends java.io.Serializable { public abstract EJBObject getEJBObject(); }
This interface provides the client with a serializable object that can be used to obtain a remote reference to a bean’s home.
public interface javax.ejb.HomeHandleextends java.io.Serializable { public abstract EJBHome getEJBHome(); }
This interface must be implemented by the message-driven bean class. It provides a set of callback notification methods that alert the bean instance that it is about to experience or has just experienced a change in its life cycle.
public interface MessageDrivenBean extends EnterpriseBean { public void ejbRemove()throws EJBException; public void setMessageDrivenContext(MessageDrivenContext ctx) throws EJBException; }
This interface is a subtype of the EJBContext
that
provides no additional methods; all its methods are defined in the
EJBContext
. The
MessageDrivenContext
provides the bean instance
with an interface to the container.
public interface MessageDrivenContext extends EJBContext {}
This EJBException
is typically thrown by the bean
class’s ejbLoad()
and
ejbStore()
methods to indicate that the
entity’s data does not exist. For example, this exception will
be thrown if an entity bean with bean-managed persistence attempts to
read its state—ejbLoad()
—from a record
that has been deleted from the database.
public class javax.ejb.NoSuchEntityException extends javax.ejb.EJBException { public NoSuchEntityException(); public NoSuchEntityException(String message); public NoSuchEntityException(Exception exception); }
This standard application exception is thrown by find methods that return a single EJB object. It indicates that no bean matching the specified criteria could be found.
public class javax.ejb.ObjectNotFoundException extends javax.ejb.FinderException { public ObjectNotFoundException(); public ObjectNotFoundException(String message); }
This standard application exception is thrown by remove methods to indicate that a failure occurred while removing the bean.
public class javax.ejb.RemoveException extends java.lang.Exception { public RemoveException(); public RemoveException(String message); }
This interface must be implemented by the session bean class. It provides a set of callback notification methods that alert the bean instance that it has experienced, or is about to experience, some change in its life cycle.
public interface javax.ejb.SessionBean extends javax.ejb.EnterpriseBean { public abstract void ejbActivate(); public abstract void ejbPassivate(); public abstract void ejbRemove(); public abstract void setSessionContext(SessionContext ctx); }
This interface is a specialization of the
EJBContext
that provides methods for obtaining the
SessionBean's
EJB object reference. The
SessionContext
provides the bean instance with an
interface to the container.
public interface javax.ejb.SessionContext extends javax.ejb.EJBContext { public abstract EJBObject getEJBObject(); }
This interface provides a stateful bean instance with additional callback notifications. These callback methods notify the bean of its current state with respect to a transaction.
public interface javax.ejb.SessionSynchronization { public abstract void afterBegin(); public abstract void afterCompletion(boolean committed); public abstract void beforeCompletion(); }
This standard system exception is thrown by local component
interfaces to indicate that the call had no transaction context, but
the method called requires an active transaction. This situation
might occur if the client has no transaction but invokes a method
with the Mandatory
transaction attribute.
public interface TransactionRequiredLocalException extends EJBException { public TransactionRequiredLocalException(); public TransactionRequiredLocalException(String message); }
This standard system exception is thrown to indicate that the caller’s transaction has been rolled back, or marked to be rolled back, due to some failure that occurred while the method was executing. This exception tells the caller that further work for that transaction would be fruitless.
public interface TransactionRolledbackLocalException extends EJBException { public TransactionRolledbackLocalException(); public TransactionRolledbackLocalException(String message); public TransactionRolledbackLocalException(String message,Exception ex); }