com.sun.ejb
Interface Container

All Known Implementing Classes:

AbstractSingletonContainer, BaseContainer, BMCSingletonContainer, CMCSingletonContainer, CommitCEntityContainer, EntityContainer, MessageBeanContainer, ReadOnlyBeanContainer, StatefulSessionContainer, StatelessSessionContainer, TimerBeanContainer

public interface Container

A Container stores EJB instances and is responsible for the lifecycle, state management, concurrency, transactions, security, naming, resource management, etc. It does the above by interposing actions before and after invocations on EJBs. It uses the ProtocolManager, SecurityManager, TransactionManager, NamingManager for help with the above responsibilities. There are four types of Containers: StatefulSessionContainer, StatelessSessionContainer, EntityContainer, and MessageBeanContainer. Note: the term "Container" here refers to an instance of one of the above container classes. In the EJB spec "container" refers to a process or JVM which hosts EJB instances.

There is one instance of the Container for each EJB type (deployment desc). When a JAR is deployed on the EJB server, a Container instance is created for each EJB declared in the ejb-jar.xml for the EJB JAR.

The Container interface provides methods called from other parts of the RI as well as from generated EJBHome/EJBObject implementations.

Field Summary

static int	SEC_CHECKED
static int	SEC_EXCLUDED
static int	SEC_NOT_INITIALIZED
static int	SEC_UNCHECKED
static java.lang.String[]	secAttrStrings
static int	TX_BEAN_MANAGED
static int	TX_MANDATORY
static int	TX_NEVER
static int	TX_NOT_INITIALIZED
static int	TX_NOT_SUPPORTED
static int	TX_REQUIRED
static int	TX_REQUIRES_NEW
static int	TX_SUPPORTS
static java.lang.String[]	txAttrStrings

Method Summary

void	assertValidLocalObject(java.lang.Object o) Verify that a given object is an EJBLocalObject of an ejb from this ejb container.
void	assertValidRemoteObject(java.lang.Object o) Verify that a given object is an EJBObject of an ejb from this ejb container.
boolean	authorize(EjbInvocation inv) Go through ejb container to do ejb security manager authorization.
void	doAfterBegin(ComponentInvocation ci) Called from the TM when an EJB with Bean-Managed transactions starts a tx
void	externalPostInvoke() Performs post external invocation cleanup such as restoring the original class loader.
void	externalPreInvoke() Performs pre external invocation setup such as setting application context class loader.
java.lang.ClassLoader	getClassLoader()
java.lang.String	getComponentId() Called from NamingManagerImpl during java:comp/env lookup.
EjbDescriptor	getEjbDescriptor()
EJBHome	getEJBHome()
EJBLocalObject	getEJBLocalObjectForPrimaryKey(java.lang.Object pkey)
EJBLocalObject	getEJBLocalObjectForPrimaryKey(java.lang.Object pkey, EJBContext ctx) Obtain an Entity EJBLocalObject corresponding to the primary key.
EJBMetaData	getEJBMetaData()
EJBObject	getEJBObjectForPrimaryKey(java.lang.Object pkey) Obtain an Entity EJBObject corresponding to the primary key.
java.lang.Object	getJaccEjb(EjbInvocation inv) Used by EjbInvocation during JACC EnterpriseBean policy handler request for target EnterpriseBean instance.
SecurityManager	getSecurityManager()
java.rmi.Remote	getTargetObject(byte[] instanceKey, java.lang.String remoteBusinessIntf) Return the EJBObject/EJBHome for the given instanceKey.
boolean	isTimedObject() Returns true if this Container uses EJB Timer Service.
void	onReady() Called when server instance is Ready
void	onShutdown() Called when server instance is shuting down
void	onTermination() Called when server instance is terminating.
void	postCreate(EjbInvocation inv, java.lang.Object primaryKey) Called by the EJB(Local)Home after invoking ejbCreate on an EntityBean.
java.lang.Object	postFind(EjbInvocation inv, java.lang.Object primaryKeys, java.lang.Object[] findParams) Called by the EJB(Local)Home after invoking ejbFind* on an EntityBean.
void	postInvoke(EjbInvocation inv) Called by the EJB(Local)Object/EJB(Local)Home after an invocation on a bean.
void	preInvoke(EjbInvocation inv) Called by the EJB(Local)Object/EJB(Local)Home before an invocation on a bean.
void	preSelect() Notification from persistence manager than an ejbSelect query is about to be invoked on a bean of the ejb type for this container.
void	releaseTargetObject(java.rmi.Remote remoteObj) Release the EJBObject/EJBHome object.
void	removeBeanUnchecked(EJBLocalObject bean) Remove a bean.
void	removeBeanUnchecked(java.lang.Object pkey) Remove a bean given primary key.
void	setStartedState() Start servicing invocations for EJB instances in this Container.
void	setStoppedState() Stop servicing invocations for EJB instances in this Container.
void	setUndeployedState() Stop servicing invocations for EJB instances in this Container as the container is being undeployed.
void	startApplication(boolean deploy) Called after all the components in the container's application have loaded successfully.
void	undeploy() Called from EJB JarManager when an application is undeployed.
boolean	userTransactionMethodsAllowed(ComponentInvocation inv) EJB spec makes a distinction between access to the UserTransaction object itself and access to its methods.
void	webServicePostInvoke(EjbInvocation inv) Called by webservice code to do ejb invocation post processing.

Field Detail

TX_NOT_INITIALIZED

static final int TX_NOT_INITIALIZED

See Also:

Constant Field Values

TX_NOT_SUPPORTED

static final int TX_NOT_SUPPORTED

See Also:

Constant Field Values

TX_BEAN_MANAGED

static final int TX_BEAN_MANAGED

See Also:

Constant Field Values

TX_REQUIRED

static final int TX_REQUIRED

See Also:

Constant Field Values

TX_SUPPORTS

static final int TX_SUPPORTS

See Also:

Constant Field Values

TX_REQUIRES_NEW

static final int TX_REQUIRES_NEW

See Also:

Constant Field Values

TX_MANDATORY

static final int TX_MANDATORY

See Also:

Constant Field Values

TX_NEVER

static final int TX_NEVER

See Also:

Constant Field Values

txAttrStrings

static final java.lang.String[] txAttrStrings

SEC_NOT_INITIALIZED

static final int SEC_NOT_INITIALIZED

See Also:

Constant Field Values

SEC_UNCHECKED

static final int SEC_UNCHECKED

See Also:

Constant Field Values

SEC_EXCLUDED

static final int SEC_EXCLUDED

See Also:

Constant Field Values

SEC_CHECKED

static final int SEC_CHECKED

See Also:

Constant Field Values

secAttrStrings

static final java.lang.String[] secAttrStrings

Method Detail

getTargetObject

java.rmi.Remote getTargetObject(byte[] instanceKey,
                                java.lang.String remoteBusinessIntf)

Return the EJBObject/EJBHome for the given instanceKey.

Parameters:

remoteBusinessIntf - True if this invocation is for the RemoteHome view of the bean. False if for the RemoteBusiness view. Called from the ProtocolManager when a remote invocation arrives.

releaseTargetObject

void releaseTargetObject(java.rmi.Remote remoteObj)

Release the EJBObject/EJBHome object. Called from the ProtocolManager after a remote invocation completes.

externalPreInvoke

void externalPreInvoke()

Performs pre external invocation setup such as setting application context class loader. Called by getTargetObject() and web service inv

externalPostInvoke

void externalPostInvoke()

Performs post external invocation cleanup such as restoring the original class loader. Called by releaseTargetObject() and web service inv

getEJBObjectForPrimaryKey

EJBObject getEJBObjectForPrimaryKey(java.lang.Object pkey)

Obtain an Entity EJBObject corresponding to the primary key. Used by the PersistenceManager.

getEJBLocalObjectForPrimaryKey

EJBLocalObject getEJBLocalObjectForPrimaryKey(java.lang.Object pkey,
                                              EJBContext ctx)

Obtain an Entity EJBLocalObject corresponding to the primary key. Used by the PersistenceManager.

getEJBLocalObjectForPrimaryKey

EJBLocalObject getEJBLocalObjectForPrimaryKey(java.lang.Object pkey)

assertValidLocalObject

void assertValidLocalObject(java.lang.Object o)
                            throws EJBException

Verify that a given object is an EJBLocalObject of an ejb from this ejb container. The given object must be an EJBLocalObject and have the same ejb type ( meaning same ejb-jar and same ejb-name ) as this container. Note that for entity beans this equality check is independent of primary key.

Throws:

EJBException - Thrown when the assertion fails.

assertValidRemoteObject

void assertValidRemoteObject(java.lang.Object o)
                             throws EJBException

Verify that a given object is an EJBObject of an ejb from this ejb container. The given object must be an EJBObject and have the same ejb type ( meaning same ejb-jar and same ejb-name ) as this container. Note that for entity beans this equality check is independent of primary key.

Throws:

EJBException - Thrown when the assertion fails.

removeBeanUnchecked

void removeBeanUnchecked(EJBLocalObject bean)

Remove a bean. Used by the PersistenceManager.

removeBeanUnchecked

void removeBeanUnchecked(java.lang.Object pkey)

Remove a bean given primary key. Used by the PersistenceManager.

preSelect

void preSelect()
               throws EJBException

Notification from persistence manager than an ejbSelect query is about to be invoked on a bean of the ejb type for this container. This allows the ejb container to perform the same set of actions as take place before a finder method, such as calling ejbStore on bean instances. (See EJB 2.1, Section 10.5.3 ejbFind,ejbStore)

Throws:

EJBException - Thrown if an error occurs during the preSelect actions performed by the container. If thrown, the remaining select query steps should be aborted and an EJBException should be propagated back to the application code.

preInvoke

void preInvoke(EjbInvocation inv)

Called by the EJB(Local)Object/EJB(Local)Home before an invocation on a bean.

postInvoke

void postInvoke(EjbInvocation inv)

Called by the EJB(Local)Object/EJB(Local)Home after an invocation on a bean.

webServicePostInvoke

void webServicePostInvoke(EjbInvocation inv)

Called by webservice code to do ejb invocation post processing.

postCreate

void postCreate(EjbInvocation inv,
                java.lang.Object primaryKey)
                throws CreateException

Called by the EJB(Local)Home after invoking ejbCreate on an EntityBean. After this postCreate the EJB(Local)Home can call ejbPostCreate on the EntityBean.

Parameters:

primaryKey - the value returned from ejbCreate.

Throws:

CreateException

postFind

java.lang.Object postFind(EjbInvocation inv,
                          java.lang.Object primaryKeys,
                          java.lang.Object[] findParams)
                          throws FinderException

Called by the EJB(Local)Home after invoking ejbFind* on an EntityBean.

Parameters:

primaryKeys - the primaryKey or collection of primaryKeys (Collection/Enumeration) returned from ejbFind.

findParams - the parameters to the ejbFind method.

Returns:

an EJBObject reference or Collection/Enumeration of EJBObjects.

Throws:

FinderException

getEjbDescriptor

EjbDescriptor getEjbDescriptor()

Returns:

the EjbDescriptor containing deployment information for the EJB type corresponding to this Container instance.

getEJBMetaData

EJBMetaData getEJBMetaData()

Returns:

the MetaData for this EJB type.

getClassLoader

java.lang.ClassLoader getClassLoader()

Returns:

the classloader of this container instance.

getEJBHome

EJBHome getEJBHome()

Returns:

the EJBHome object reference for this container instance.

getSecurityManager

SecurityManager getSecurityManager()

Returns:

A SecurityManager object for this container.

userTransactionMethodsAllowed

boolean userTransactionMethodsAllowed(ComponentInvocation inv)

EJB spec makes a distinction between access to the UserTransaction object itself and access to its methods. getUserTransaction covers the first check and this method covers the second. It is called by the UserTransaction implementation to verify access.

doAfterBegin

void doAfterBegin(ComponentInvocation ci)

Called from the TM when an EJB with Bean-Managed transactions starts a tx

startApplication

void startApplication(boolean deploy)

Called after all the components in the container's application have loaded successfully. Allows containers to delay any instance creation or external invocations until the second phase of deployment. Note that this callback occurs at a point that is still considered within deployment. Failures should still still be treated as a deployment error.

Parameters:

deploy - true if this method is called during application deploy

undeploy

void undeploy()

Called from EJB JarManager when an application is undeployed.

onReady

void onReady()

Called when server instance is Ready

onShutdown

void onShutdown()

Called when server instance is shuting down

onTermination

void onTermination()

Called when server instance is terminating. This method is the last one called during server shutdown.

getComponentId

java.lang.String getComponentId()

Called from NamingManagerImpl during java:comp/env lookup.

setStartedState

void setStartedState()

Start servicing invocations for EJB instances in this Container.

setStoppedState

void setStoppedState()

Stop servicing invocations for EJB instances in this Container. Subsequent EJB invocations will receive exceptions. Invocations already in progress will be allowed to complete eventually.

setUndeployedState

void setUndeployedState()

Stop servicing invocations for EJB instances in this Container as the container is being undeployed. No new EJB invocations will be accepted from now on. Invocations already in progress will be allowed to complete eventually.

getJaccEjb

java.lang.Object getJaccEjb(EjbInvocation inv)

Used by EjbInvocation during JACC EnterpriseBean policy handler request for target EnterpriseBean instance.

Returns:

EnterpriseBean instance or null if not applicable for this invocation.

authorize

boolean authorize(EjbInvocation inv)

Go through ejb container to do ejb security manager authorization.

isTimedObject

boolean isTimedObject()

Returns true if this Container uses EJB Timer Service.