Appendix A. The Enterprise JavaBeans API

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.

A.1. Package: javax.ejb

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.

A.1.1. CreateException

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);
}

A.1.2. DuplicateKeyException

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);
}

A.1.3. EJBContext

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();
}

A.1.4. EJBException (1.1)

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();
}

A.1.5. EJBHome

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);
}

A.1.6. EJBMetaData

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
}

A.1.7. EJBObject

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();
}

A.1.8. EnterpriseBean

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 {}

A.1.9. EntityBean

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();
}

A.1.10. EntityContext

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();
}

A.1.11. FinderException

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);
}

A.1.12. Handle

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();
}

A.1.13. HomeHandle (1.1)

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();
}

A.1.14. NoSuchEntityException (1.1)

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); 

}

A.1.15. ObjectNotFoundException

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);
}

A.1.16. RemoveException

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);
}

A.1.17. SessionBean

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);
}

A.1.18. SessionContext

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();
}

A.1.19. SessionSynchronization

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();
}