Package org.glassfish.persistence.ejb.entitybean.container

Class EntityContainer

  • All Implemented Interfaces:
    CacheListener, Container, JavaEEContainer, EjbContainerFacade
    Direct Known Subclasses:
    CommitCEntityContainer, ReadOnlyBeanContainer
    public class EntityContainer
extends BaseContainer
implements CacheListener
    This class implements the Container interface for EntityBeans. It is responsible for instance & lifecycle management for BMP & CMP EntityBeans. The EntityContainer implements option B of the commit-time options described in the EJB2.0 spec section 10.5.9 It also implements optimistic concurrency (i.e. multiple non-exclusive bean instances per primary key) when there are multiple concurrent transactions on a EntityBean.

    The following sequence of actions happens for the EntityContainer, for each EJB lifecycle stage (note: getEJBObject, getContext, releaseContext, preInvokeTx, postInvokeTx are called from BaseContainer). 1. EJB Creation homeImpl.create, container.getContext, container.preInvokeTx, ejb.ejbCreate, container.postCreate, ejb.ejbPostCreate, container.postInvokeTx, container.releaseContext 2. EJB Finding homeImpl.find---, container.getContext, container.preInvokeTx, ejb.ejbFind---, container.postFind, container.postInvokeTx, container.releaseContext 3. EJB Invocation container.getEJBObject, ejbObject.someMethod, container.getContext, container.preInvokeTx, ejb.someMethod, container.postInvokeTx, container.releaseContext

    State Management: The EntityContainer manages collections of EJBs in different states. The 5 states of an EntityBean (an EJB can be in only 1 state at a time):

    1. POOLED : does not have identity. EJBs in the POOLED state are all identical, hence are maintained in a java.util.Vector, whose size is maintained below a HIGH_WATER_MARK (currently 100).
    2. READY : ready for invocations, no transaction in progress. EJBs in the READY state are associated with a primary key. To enhance reuse of EJB instances, only one READY EJB per primary key is stored. READY EJBs are managed by the ejbstore/EntityStore class. READY EJBs are looked up using a key consisting of the primary key and a null transaction context.
    3. INVOKING : processing an invocation. EJBs in the INVOKING state are not stored anywhere. Before transitioning from READY or INCOMPLETE_TX to INVOKING, the EJB is removed from the EntityStore.
    4. INCOMPLETE_TX : ready for invocations, transaction in progress. EJBs in the INCOMPLETE_TX state are associated with a primary key. INCOMPLETE_TX EJBs are managed by the ejbstore/EntityStore class. INCOMPLETE_TX EJBs are looked up using a composite key consisting of the primary key and the transaction context.
    5. DESTROYED : does not exist.
    All READY bean instances are stored in the readyStore. All INCOMPLETE_TX bean instances are stored in the ActiveTxCache. Beans in the READY state are stored with key = ejbObject. Beans in the INCOMPLETE_TX state are stored with key = ejbObject+Tx. Instances in INVOKING state which have transactions associated with them are also in ActiveTxCache. All POOLED instances are stored in the pooledEJBs vector. Note on locking order: if both ready/ActiveTxCache and context are to be locked, always acquire the context lock first, then the Store lock. Note on locking order: if both ready/ActiveTxCache and ejbObject need locks, always acquire the ejbObject lock first, then the Store lock.
    Author:
    Mahesh Kannan, Shanker N, Pramod Gopinath

    • Field Detail

      • passivationCandidates

        protected Stack passivationCandidates

      • readyStore

        protected Cache readyStore

      • isReentrant

        protected boolean isReentrant

      • isContainerManagedPers

        protected boolean isContainerManagedPers

      • _maxBuckets

        protected int _maxBuckets

      • idleEJBObjectPassivator

        protected org.glassfish.persistence.ejb.entitybean.container.EntityContainer.IdleBeansPassivator idleEJBObjectPassivator

      • idleLocalEJBObjectPassivator

        protected org.glassfish.persistence.ejb.entitybean.container.EntityContainer.IdleBeansPassivator idleLocalEJBObjectPassivator

      • defaultCacheEJBO

        protected boolean defaultCacheEJBO

      • ejboRemoved

        protected int ejboRemoved

      • totalPassivations

        protected int totalPassivations

      • totalPassivationErrors

        protected int totalPassivationErrors

    • Method Detail

      • validateTxAttr

        protected void validateTxAttr​(MethodDescriptor md,
                              int txAttr)
                       throws jakarta.ejb.EJBException
        Description copied from class: BaseContainer
        Validate transaction attribute value. Allow subclasses to add their own validation.
        Overrides:
        validateTxAttr in class BaseContainer
        Throws:
        jakarta.ejb.EJBException

      • setupIdleBeansPassivator

        public org.glassfish.persistence.ejb.entitybean.container.EntityContainer.IdleBeansPassivator setupIdleBeansPassivator​(Cache cache)
                                                                                                                throws Exception
        setup a timer task to trim timed out entries in the cache.
        Parameters:
        cache - cache which is used to setup the timer task
        Returns:
        the passivator object
        Throws:
        Exception

      • cancelTimerTasks

        public void cancelTimerTasks()
        cancel a timer task to trim timed out entries in the cache.

      • getMaxCacheSize

        public int getMaxCacheSize()

      • getSteadyPoolSize

        public int getSteadyPoolSize()

      • getMaxPoolSize

        public int getMaxPoolSize()

      • getPooledCount

        public long getPooledCount()

      • getReadyCount

        public long getReadyCount()

      • _getContext

        protected ComponentContext _getContext​(EjbInvocation inv)
        Called from BaseContainer.preInvoke which is called from the EJBObject for local and remote invocations, and from the EJBHome for create/find.
        Specified by:
        _getContext in class BaseContainer

      • willInvokeWithClientTx

        protected boolean willInvokeWithClientTx​(EjbInvocation inv)

      • releaseContext

        public void releaseContext​(EjbInvocation inv)
        This is called from BaseContainer.postInvoke after EntityContainer.preInvokeTx has been called.
        Specified by:
        releaseContext in class BaseContainer

      • postCreate

        public void postCreate​(EjbInvocation inv,
                       Object primaryKey)
                throws jakarta.ejb.CreateException
        This is called from the generated "HelloEJBHomeImpl" create* method, after ejb.ejbCreate() has been called and before ejb.ejbPostCreate() is called. Note: postCreate will not be called if ejbCreate throws an exception
        Specified by:
        postCreate in interface Container
        Overrides:
        postCreate in class BaseContainer
        primaryKey - the value returned from ejbCreate.
        Throws:
        jakarta.ejb.CreateException

      • preSelect

        public void preSelect()
               throws jakarta.ejb.EJBException
        Called from CMP PersistentManager
        Specified by:
        preSelect in interface Container
        Overrides:
        preSelect in class BaseContainer
        Throws:
        jakarta.ejb.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.

      • postFind

        public Object postFind​(EjbInvocation inv,
                       Object primaryKeys,
                       Object[] findParams)
                throws jakarta.ejb.FinderException
        Convert a collection of primary keys to a collection of EJBObjects. (special case: single primary key). Note: the order of input & output collections must be maintained. Null values are preserved in both the single primary key return and collection-valued return cases. This is called from the generated "HelloEJBHomeImpl" find* method, after ejb.ejbFind**() has been called. Note: postFind will not be called if ejbFindXXX throws an exception
        Specified by:
        postFind in interface Container
        Overrides:
        postFind in class BaseContainer
        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:
        jakarta.ejb.FinderException

      • getEJBObjectForPrimaryKey

        public jakarta.ejb.EJBObject getEJBObjectForPrimaryKey​(Object pkey)
        Called only from the Persistence Manager for EJB2.0 CMP EntityBeans. This is a private API between the PM and Container because there is no standard API defined in EJB2.0 for the PM to get an EJBObject for a primary key (home.findByPrimaryKey cant be used because it may not run in the same tx).
        Specified by:
        getEJBObjectForPrimaryKey in interface Container
        Overrides:
        getEJBObjectForPrimaryKey in class BaseContainer

      • getEJBLocalObjectForPrimaryKey

        public jakarta.ejb.EJBLocalObject getEJBLocalObjectForPrimaryKey​(Object pkey,
                                                                 jakarta.ejb.EJBContext ctx)
        Called only from the Persistence Manager for EJB2.0 CMP EntityBeans. Called only during cascade delete...... This is a private API between the PM and Container because there is no standard API defined in EJB2.0 for the PM to get an EJBLocalObject for a primary key (findByPrimaryKey cant be used because it may not run in the same tx). Example 1: A cascadeDeletes B and B calls getA() (expected return value: null) In the above case, getA() eventualy calls getEJBLocalObjectForPrimaryKey(PK_of_A, Ctx_of_B) We first check if B is in the process of being cascade deleted by checking the cascadeDeleteBeforeEJBRemove flag. If this flag is true, only then we bother to check if the Context associated with the PK_of_A in this transaction is marked for cascade delete which can be figured out by checking isCascadeDeleteAfterSuperEJBRemove() in A's context. If A is marked for cascade delete then we return null else the EJBLocalObject associated with A. Example 2: C cascadeDeletes B and B calls getA() (expected return value: EJBLocalObject for PK_of_A) In the above case, getA() eventualy calls getEJBLocalObjectForPrimaryKey(PK_of_A, Ctx_of_B) We first check if B is in the process of being cascade deleted by checking the cascadeDeleteBeforeEJBRemove flag. This flag will be true, and hence we check if the Context associated with the PK_of_A in this transaction is marked for cascade delete which can be figured out by checking isCascadeDeleteAfterSuperEJBRemove() in A's context. In this case this flag will be false and hcen we return the ejbLocalObject Example 2: B is *NOT* cascade deleted and B calls getA() (expected return value: EJBLocalObject for PK_of_A) In the above case, getA() eventualy calls getEJBLocalObjectForPrimaryKey(PK_of_A, Ctx_of_B) We first check if B is in the process of being cascade deleted by checking the cascadeDeleteBeforeEJBRemove flag. This flag will be FALSE, and hence we do not make any further check and return the EJBLocalObject associated with A
        Specified by:
        getEJBLocalObjectForPrimaryKey in interface Container
        Overrides:
        getEJBLocalObjectForPrimaryKey in class BaseContainer
        Parameters:
        pkey - The primary key for which the EJBLocalObject is required
        ctx - The context associated with the bean from which the accessor method is invoked
        Returns:
        The EJBLocalObject associated with the PK or null if it is cascade deleted.

      • getEJBLocalObjectForPrimaryKey

        public jakarta.ejb.EJBLocalObject getEJBLocalObjectForPrimaryKey​(Object pkey)
        Called only from the Persistence Manager for EJB2.0 CMP EntityBeans. This is a private API between the PM and Container because there is no standard API defined in EJB2.0 for the PM to get an EJBLocalObject for a primary key (findByPrimaryKey cant be used because it may not run in the same tx).
        Specified by:
        getEJBLocalObjectForPrimaryKey in interface Container
        Overrides:
        getEJBLocalObjectForPrimaryKey in class BaseContainer

      • removeBean

        protected void removeBean​(EjbInvocation inv)
                   throws jakarta.ejb.RemoveException
        container.preInvoke() must already be done. So this will be called with the proper Tx context.
        Throws:
        jakarta.ejb.RemoveException - if an error occurs while removing the bean

      • removeBeanUnchecked

        public void removeBeanUnchecked​(jakarta.ejb.EJBLocalObject localObj)
        Remove a bean. Used by the PersistenceManager. This is needed because the PM's remove must bypass tx/security checks.
        Specified by:
        removeBeanUnchecked in interface Container
        Overrides:
        removeBeanUnchecked in class BaseContainer

      • forceDestroyBean

        protected void forceDestroyBean​(EJBContextImpl ctx)
        Discard the bean instance. The bean's persistent state is not removed. This is usually called when the bean instance throws a system exception, from BaseContainer.postInvokeTx, getReadyEJB, afterBegin, beforeCompletion, passivateEJB.
        Specified by:
        forceDestroyBean in class BaseContainer

      • checkExists

        protected void checkExists​(EJBLocalRemoteObject ejbObj)
        Check if the given EJBObject/LocalObject has been removed. Called before executing non-business methods of EJBLocalObject.
        Overrides:
        checkExists in class BaseContainer
        Throws:
        jakarta.ejb.NoSuchObjectLocalException - if the object has been removed.

      • trimEvent

        public void trimEvent​(Object primaryKey,
                      Object context)
        Description copied from interface: CacheListener
        an cached value is trimmed (to prevent cache overflow)
        Specified by:
        trimEvent in interface CacheListener
        Parameters:
        primaryKey - lookup key
        context - value of the cached entity

      • internalGetEJBLocalObjectImpl

        protected EJBLocalObjectImpl internalGetEJBLocalObjectImpl​(Object primaryKey)
        The following are private methods for implementing internal logic for lifecyle and state management, in a reusable way.

      • internalGetEJBLocalObjectImpl

        protected EJBLocalObjectImpl internalGetEJBLocalObjectImpl​(Object primaryKey,
                                                           boolean incrementRefCount)

      • internalGetEJBLocalObjectImpl

        protected EJBLocalObjectImpl internalGetEJBLocalObjectImpl​(Object primaryKey,
                                                           boolean incrementRefCount,
                                                           boolean cacheEJBO)

      • passivateAndPoolEJB

        protected void passivateAndPoolEJB​(EntityContextImpl context)

      • activateEJBFromPool

        protected EntityContextImpl activateEJBFromPool​(Object primaryKey,
                                                EjbInvocation inv)
        Called from getContext and getEJBWithIncompleteTx Get an EJB in the ready state (i.e. which is not doing any invocations and doesnt have any incomplete Tx), for the ejbObject provided in the EjbInvocation. Concurrent invocations should get *different* instances.

      • removeIncompleteTxEJB

        protected void removeIncompleteTxEJB​(EntityContextImpl context,
                                     boolean updateTxBeanTable)
        Called from releaseContext if ejb is removed, from afterCompletion, and from passivateEJB.

      • afterNewlyActivated

        protected void afterNewlyActivated​(EntityContextImpl context)

      • createReadyStore

        protected void createReadyStore​(int cacheSize,
                                int numberOfVictimsToSelect,
                                float loadFactor,
                                long idleTimeout)
                         throws Exception
        Throws:
        Exception

      • createEJBObjectStores

        protected void createEJBObjectStores​(int cacheSize,
                                     int numberOfVictimsToSelect,
                                     long idleTimeout)
                              throws Exception
        Throws:
        Exception

      • destroyReadyStoreOnUndeploy

        protected void destroyReadyStoreOnUndeploy()

      • removeContextFromReadyStore

        protected void removeContextFromReadyStore​(Object primaryKey,
                                           EntityContextImpl context)