 | CONTENTS |  |
Appendix A. The Enterprise JavaBeans API
This appendix is a quick reference guide to the Enterprise JavaBeans API. 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 javax.ejb package also contains a number of exceptions that are thrown by enterprise beans.
A.1.1 EJB 2.0: AccessLocalException
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);
}
A.1.2 CreateException
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);
}
A.1.3 DuplicateKeyException
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);
}
A.1.4 EJBContext
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();
}
A.1.5 EJBException
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();
}
A.1.6 EJBHome
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);
}
A.1.7 EJB 2.0: EJBLocalHome
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;
}
A.1.8 EJB 2.0: EJBLocalObject
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;
}
A.1.9 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();
}
A.1.10 EJBObject
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();
}
A.1.11 EnterpriseBean
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 {}
A.1.12 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 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();
}
A.1.13 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();
public abstract EJBLocalObject getEJBLocalObject(); //new in EJB 2.0
}
A.1.14 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.15 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.16 HomeHandle
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();
}
A.1.17 EJB 2.0: MessageDrivenBean
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;
}
A.1.18 EJB 2.0: MessageDrivenContext
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 {}
A.1.19 NoSuchEntityException
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.20 ObjectNotFoundException
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);
}
A.1.21 RemoveException
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);
}
A.1.22 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.23 SessionContext
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();
}
A.1.24 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();
}
A.1.25 EJB 2.0: TransactionRequiredLocalException
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);
}
A.1.26 EJB 2.0: TransactionRolledbackLocalException
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);
}
A.2 EJB 2.0: Package: javax.jms
This package defines the classes and interfaces of the Java Message Service. The MessageListener interface of this package is important to EJB 2.0.
A.2.1 MessageListener
This interface must be implemented by message-driven beans. The onMessage() method is used to deliver JMS Message objects to the message-driven bean at runtime.
public interface MessageListener
{
public void onMessage(Message message);
}
A.3 EJB 2.0: Package: javax.ejb.spi
This package is used by EJB vendors when implementing EJB container systems. It is not used by enterprise bean developers.
A.3.1 HandleDelegate
When you pass an EJBObject or EJBHome remote reference from one container system to another, the EJB container uses the HandleDelegate object to convert the EJBObject or EJBHome reference from a vendor-specific form to a vendor-neutral form that can be passed between different EJB vendors' servers. HandleDelegate is an interoperability facility that is invisible to the bean developer and is for EJB vendors only. As a bean developer, you should not be concerned with it.
public interface HandleDelegate {
public EJBHome readEJBHome(ObjectInputStream istream)
throws throws java.io.IOException,java.lang.ClassNotFoundException;
public EJBObject readEJBObject(ObjectInputStream istream)
throws throws java.io.IOException,java.lang.ClassNotFoundException;
public void writeEJBHome(EJBHome ejbHome, ObjectOutputStream ostream)
throws throws java.io.IOException;
public void writeEJBObject(EJBObject ejbObject, ObjectOutputStream ostream)
throws throws java.io.IOException;
}
| CONTENTS | |