org.openejb.core.entity
Class EntityInstanceManager

java.lang.Object
  extended by org.openejb.core.entity.EntityInstanceManager

public class EntityInstanceManager
extends java.lang.Object

One instance of this class is used with each EntityContainer. It is responsible for managing the Method Ready and Transaction Ready pools where bean instances are stored between client calls.

To obtain an instance the obtainInstance( ) method must be called with the primary key and bean type to obtained. The bean instance will be returned form the method ready pool if its not already enrolled in the current transaction, or from the transaction ready pool if it is.

If the bean identity requested is registered with a different tx, a different bean instance is returned which results in both transaction accessing the same bean identity, but using different bean instances.

The poolInstance( ) method is invoked when the client call is finished using the bean instance. the instance will be returned to the transaction ready pool if its registered with a transaction or it will be placed in the method ready pool if its not.

The freeInstance( ) method is invoked in an EJBException or some other RuntimeException occurs. In these situations, the bean instance must be de-registered from the transaction and de-referenced for garbage collection. the freeInstance( ) handles these operations.

This class automatically handles transferring bean instances to the Transaction Ready Pool and transferring them back to the Method Ready pool as necessary.

This class also handles the ejbStore operations by registering the instance with the transaction. The ejbStore Operation doesn't not need to be executed by the container. The container is, however, responsible for the ejbLoad method.


Nested Class Summary
static class EntityInstanceManager.Key
           
protected  class EntityInstanceManager.SyncronizationWrapper
           
 
Field Summary
protected  EntityContainer container
           
 Logger logger
           
protected  java.util.HashMap poolMap
           
protected  int poolsize
           
protected  SafeToolkit toolkit
           
protected  java.util.Hashtable txReadyPool
           
 
Constructor Summary
EntityInstanceManager()
          CONSTRUCTOR METHODS
 
Method Summary
 void discardInstance(ThreadContext callContext, javax.ejb.EntityBean bean)
          An instance is freed if a EJBException or some other runtime exception occurs.
 void freeInstance(ThreadContext callContext, javax.ejb.EntityBean bean)
          Should be called when an instance is simply removed from the pool Calls unsetEntityContext in the instance.
protected  javax.ejb.EntityBean getPooledInstance(ThreadContext callContext)
          Obtains a bean instance from the proper bean pool.
 void init(EntityContainer myContainer, java.util.HashMap deployments, java.util.Properties props)
           
protected  void loadingBean(javax.ejb.EntityBean bean, ThreadContext callContext)
          called prior to invoking ejbLoad on the bean.
 javax.ejb.EntityBean obtainInstance(ThreadContext callContext)
          Obtains a bean instance from the either the method ready pool or the Tx method ready pool.
 void poolInstance(ThreadContext callContext, javax.ejb.EntityBean bean)
          Returns a bean instance to the method ready or tx method ready pool.
protected  void reusingBean(javax.ejb.EntityBean bean, ThreadContext callContext)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

poolsize

protected int poolsize

container

protected EntityContainer container

txReadyPool

protected java.util.Hashtable txReadyPool

poolMap

protected java.util.HashMap poolMap

logger

public Logger logger

toolkit

protected SafeToolkit toolkit
Constructor Detail

EntityInstanceManager

public EntityInstanceManager()
CONSTRUCTOR METHODS

Method Detail

init

public void init(EntityContainer myContainer,
                 java.util.HashMap deployments,
                 java.util.Properties props)
          throws OpenEJBException
Throws:
OpenEJBException

obtainInstance

public javax.ejb.EntityBean obtainInstance(ThreadContext callContext)
                                    throws OpenEJBException
Obtains a bean instance from the either the method ready pool or the Tx method ready pool. (Tx == Transaction) An entity bean is obtained from the ready pool if its not enrolled in the current tx. An entity bean is obtained from the tx ready pool if it is enrolled in the current tx. A tx ready entity can only be obtained if: a: It not currently servicing a thread in that tx. b: It allows for reentrant access. Reentrant beans are accessed by multiple threads and are therefore unsafe and must be coded to be multi-threaded. If the primaryKey is null when the method is invoked, the bean will be retrived from the MethodReady pool and will not be associated with the current tx The call method is required for automatically peforming the ejbLoad when a bean instance is first registered with a transaction.

Throws:
OpenEJBException

loadingBean

protected void loadingBean(javax.ejb.EntityBean bean,
                           ThreadContext callContext)
                    throws OpenEJBException
called prior to invoking ejbLoad on the bean. e.g. to give the CMP container a chance to load the persistent state

Throws:
OpenEJBException

reusingBean

protected void reusingBean(javax.ejb.EntityBean bean,
                           ThreadContext callContext)
                    throws OpenEJBException
Throws:
OpenEJBException

getPooledInstance

protected javax.ejb.EntityBean getPooledInstance(ThreadContext callContext)
                                          throws OpenEJBException
Obtains a bean instance from the proper bean pool. Each bean class has its own pool of instances. If the bean class' pool is empty, a new Instance is created. If a bean instance is not avaible one will be created.

Throws:
OpenEJBException

poolInstance

public void poolInstance(ThreadContext callContext,
                         javax.ejb.EntityBean bean)
                  throws OpenEJBException
Returns a bean instance to the method ready or tx method ready pool. A bean is returned to the tx method ready pool if the current thread is associated with a transaction. If the current thread is not associated with a transaction then the bean is returned to the Method Ready pool If the primary key is null, this would indicate that the returning bean instance was used for a find or home business methods -- in this case the bean is returned to the MethodReady pool even if the current thread is associated with a transaction.

Throws:
OpenEJBException

freeInstance

public void freeInstance(ThreadContext callContext,
                         javax.ejb.EntityBean bean)
                  throws SystemException
Should be called when an instance is simply removed from the pool Calls unsetEntityContext in the instance.

Parameters:
callContext -
bean -
Throws:
SystemException

discardInstance

public void discardInstance(ThreadContext callContext,
                            javax.ejb.EntityBean bean)
                     throws SystemException
An instance is freed if a EJBException or some other runtime exception occurs. To free an instance is to discard the instance so it can be garbage collected. If the instance is in the tx ready pool it is removed. EJB 1.1, section 12.3.2 "Discard the instance (i.e. the Container must not invoke any business methods or container callbacks on the instance)."

Parameters:
callContext -
bean -
Throws:
SystemException


Copyright © 1999-2011 OpenEJB. All Rights Reserved.