This appendix is a quick reference guide to the
Enterprise JavaBeans API.
It is broken down into sections. First, we look at the classes in the
javax.ejb
package, followed by the classes in the
javax.ejb.deployment
package (EJB 1.0 only).
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 package also contains a number of exceptions that are thrown by enterprise beans.
This standard application exception must be thrown by all create methods defined in the home interface to indicate 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, and it indicates that a bean already exists with the same primary key.
public class javax.ejb.DuplicateKeyException extends javax.ejb.CreateException { public DuplicateKeyException(); public DuplicateKeyException(String message); }
This is the base class for both EntityContext
and
SessionContext
. EJBContext
is
the bean class’s interface to the container system. It provides
information about the 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(); // new in 1.1 public abstract EJBHome getEJBHome(); public abstract boolean getRollbackOnly(); public abstract UserTransaction getUserTransaction(); public abstract Properties getEnvironment(); // deprecated in 1.1 public abstract Identity getCallerIdentity(); // deprecated in 1.1 public abstract boolean isCallerInRole(Identity role); // deprecated in 1.1 public abstract boolean isCallerInRole(String roleName); // new in 1.1 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 a 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 home interface, a developer-provided class that defines the life-cycle methods of the bean. The bean’s create and find methods are defined in the 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(); // new in 1.1 public abstract EJBMetaData getEJBMetaData(); public abstract void remove(Handle handle); public abstract void remove(Object primaryKey); }
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(); // new in 1.1 }
This interface defines the base functionality for access to
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; 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 both the EntityBean
and SessionBean
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 just has 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(); }
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.HomeHandle extends java.io.Serializable { public abstract EJBHome getEJBHome(); }
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 the home interface’s find methods that return only one 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 the 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.
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(); }