## org.jboss.ejb.plugins
Class AbstractInstanceCache

    java.lang.Object
      |
      +--org.jboss.ejb.plugins.AbstractInstanceCache

All Implemented Interfaces:
  ContainerPlugin, InstanceCache, MetricsConstants, Monitorable, Service, XmlLoadable

Direct Known Subclasses:
  EntityInstanceCache, StatefulSessionInstanceCache

public abstract class AbstractInstanceCache
extends java.lang.Object
implements InstanceCache, XmlLoadable, Monitorable, MetricsConstants

Base class for caches of entity and stateful beans.

It manages the cache entries through a `CachePolicy` object; the implementation of the cache policy object must respect the following requirements:

- Have a public constructor that takes a single argument of type AbstractInstanceCache.class or a subclass

Version:
  $Revision: 1.10.2.14 $

  Revisions:

  20010703 marcf:

  - Synchronization is on the context and not on the mutex any longer

  20010704 marcf:

  - Commented the getLock removeLock, temporarely, might need to come back when we go beyond locking at the context level and lock by ID

  2001/07/26: billb

  1. Locking is now separate from EntityEnterpriseContext objects and is now encapsulated in BeanLock and BeanLockManager. Did this because the lifetime of an EntityLock is sometimes longer than the lifetime of the ctx.

  2001/08/07: billb

  1. releaseLockRef should be enclosed in peek in remove()

  2001/12/03: billb

  1. Make sure ctx.getID() is non-null when received from unschedulePassivation.
Author:
  Simone Bordet, Bill Burke, Marc Fleury, Scott Stark

Inner Class Summary
`protected class` `AbstractInstanceCache.PassivationHelper` Helper class that schedules, unschedules, and executes the passivation jobs.

Field Summary
`protected Logger` `log` The log for this cache instance

Fields inherited from interface org.jboss.monitor.MetricsConstants
`ACTIVITY, APPLICATION, BEAN, BEANCACHE_METRICS, CHECKPOINT, INVOCATION_METRICS, MEMORY_MONITOR, METHOD, PRIMARY_KEY, SYSTEM_METRICS, THREAD_MONITOR, TIME, TYPE`

Constructor Summary
`AbstractInstanceCache()`

Method Summary
`protected abstract EnterpriseContext` `acquireContext()` Acquires an EnterpriseContext from the pool
`protected abstract void` `activate(EnterpriseContext ctx)` Activates the given EnterpriseContext
`protected abstract boolean` `canPassivate(EnterpriseContext ctx)` Returns whether the given context can be passivated or not
`void` `destroy()`
`protected abstract void` `freeContext(EnterpriseContext ctx)` Frees the given EnterpriseContext to the pool
`EnterpriseContext` `get(java.lang.Object id)` Gets a bean instance from this cache given the identity.
`protected CachePolicy` `getCache()` Returns the cache policy used for this cache.
`java.lang.Object` `getCacheLock()` Returns the mutex used to sync access to the cache policy object
`protected abstract Container` `getContainer()` Returns the container for this cache.
`protected abstract java.lang.Object` `getKey(EnterpriseContext ctx)` Returns the key used by the cache to map the given context
`void` `importXml(org.w3c.dom.Element element)`
`void` `init()`
`void` `insert(EnterpriseContext ctx)` Inserts an active bean instance after creation or activation.
`boolean` `isActive(java.lang.Object id)` Checks whether an instance corresponding to a particular id is active
`boolean` `isJMSMonitoringEnabled()`
`protected void` `logActivation(java.lang.Object id)`
`protected void` `logPassivation(java.lang.Object id)`
`protected void` `logPassivationPostponed(java.lang.Object id)`
`protected void` `logPassivationScheduled(java.lang.Object id)`
`protected abstract void` `passivate(EnterpriseContext ctx)` Passivates the given EnterpriseContext
`void` `release(EnterpriseContext ctx)` Releases the given bean instance from this cache.
`void` `remove(java.lang.Object id)` Removes a bean instance from this cache given the identity.
`void` `resetStatistic()`
`java.util.Map` `retrieveStatistic()`
`void` `sample(java.lang.Object s)` Samples the status of the implementor object and register the status into the snapshot argument.
`protected void` `schedulePassivation(EnterpriseContext ctx)` Schedules the given EnterpriseContext for passivation
`void` `setJMSMonitoringEnabled(boolean enable)`
`protected abstract void` `setKey(java.lang.Object id, EnterpriseContext ctx)` Sets the given id as key for the given context
`void` `start()`
`void` `stop()`
`protected EnterpriseContext` `unschedulePassivation(java.lang.Object id)` Tries to unschedule the given EnterpriseContext for passivation; returns the unscheduled context if it wasn't passivated yet, null if the passivation already happened.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.jboss.ejb.ContainerPlugin
`setContainer`

Field Detail

### log

    protected Logger log

  The log for this cache instance

Constructor Detail

### AbstractInstanceCache

    public AbstractInstanceCache()

Method Detail

### sample

    public void sample(java.lang.Object s)

  Description copied from interface: `Monitorable`
  Samples the status of the implementor object and register the status into the snapshot argument.
  Specified by:
    `sample` in interface `Monitorable`

### retrieveStatistic

    public java.util.Map retrieveStatistic()

### resetStatistic

    public void resetStatistic()

### setJMSMonitoringEnabled

    public void setJMSMonitoringEnabled(boolean enable)

### isJMSMonitoringEnabled

    public boolean isJMSMonitoringEnabled()

### get

    public EnterpriseContext get(java.lang.Object id)
                          throws java.rmi.RemoteException,
                                 java.rmi.NoSuchObjectException

  Description copied from interface: `InstanceCache`
  Gets a bean instance from this cache given the identity. This method may involve activation if the instance is not in the cache. Implementation should have O(1) complexity. This method is never called for stateless session beans.
  Specified by:
    `get` in interface `InstanceCache`
  Following copied from interface: `org.jboss.ejb.InstanceCache`
  Parameters:
    `id` - the primary key of the bean
  Returns:
    the EnterpriseContext related to the given id
  Throws:
    `java.rmi.RemoteException` - in case of illegal calls (concurrent / reentrant), NoSuchObjectException if the bean cannot be found.
  See Also:
    `InstanceCache.release(org.jboss.ejb.EnterpriseContext)`

### insert

    public void insert(EnterpriseContext ctx)

  Description copied from interface: `InstanceCache`
  Inserts an active bean instance after creation or activation. Implementation should guarantee proper locking and O(1) complexity.
  Specified by:
    `insert` in interface `InstanceCache`
  Following copied from interface: `org.jboss.ejb.InstanceCache`
  Parameters:
    `ctx` - the EnterpriseContext to insert in the cache
  See Also:
    `InstanceCache.remove(java.lang.Object)`

### release

    public void release(EnterpriseContext ctx)

  Description copied from interface: `InstanceCache`
  Releases the given bean instance from this cache. This method may passivate the bean to get it out of the cache. Implementation should return almost immediately leaving the passivation to be executed by another thread.
  Specified by:
    `release` in interface `InstanceCache`
  Following copied from interface: `org.jboss.ejb.InstanceCache`
  Parameters:
    `ctx` - the EnterpriseContext to release
  See Also:
    `InstanceCache.get(java.lang.Object)`

### remove

    public void remove(java.lang.Object id)

  Description copied from interface: `InstanceCache`
  Removes a bean instance from this cache given the identity. Implementation should have O(1) complexity and guarantee proper locking.
  Specified by:
    `remove` in interface `InstanceCache`
  Following copied from interface: `org.jboss.ejb.InstanceCache`
  Parameters:
    `id` - the pimary key of the bean
  See Also:
    `InstanceCache.insert(org.jboss.ejb.EnterpriseContext)`

### isActive

    public boolean isActive(java.lang.Object id)

  Description copied from interface: `InstanceCache`
  Checks whether an instance corresponding to a particular id is active
  Specified by:
    `isActive` in interface `InstanceCache`
  Following copied from interface: `org.jboss.ejb.InstanceCache`
  Parameters:
    `id` - the pimary key of the bean
  See Also:
    `InstanceCache.insert(org.jboss.ejb.EnterpriseContext)`

### importXml

    public void importXml(org.w3c.dom.Element element)
                   throws DeploymentException

  Specified by:
    `importXml` in interface `XmlLoadable`

### init

    public void init()
              throws java.lang.Exception

  Specified by:
    `init` in interface `Service`

### start

    public void start()
               throws java.lang.Exception

  Specified by:
    `start` in interface `Service`

### stop

    public void stop()

  Specified by:
    `stop` in interface `Service`

### destroy

    public void destroy()

  Specified by:
    `destroy` in interface `Service`

### schedulePassivation

    protected void schedulePassivation(EnterpriseContext ctx)

  Schedules the given EnterpriseContext for passivation
  See Also:
    `AbstractInstanceCache.PassivationHelper.schedule(org.jboss.ejb.EnterpriseContext)`

### unschedulePassivation

    protected EnterpriseContext unschedulePassivation(java.lang.Object id)

  Tries to unschedule the given EnterpriseContext for passivation; returns the unscheduled context if it wasn't passivated yet, null if the passivation already happened.
  See Also:
    `AbstractInstanceCache.PassivationHelper.unschedule(java.lang.Object)`

### logActivation

    protected void logActivation(java.lang.Object id)

### logPassivationScheduled

    protected void logPassivationScheduled(java.lang.Object id)

### logPassivation

    protected void logPassivation(java.lang.Object id)

### logPassivationPostponed

    protected void logPassivationPostponed(java.lang.Object id)

### getContainer

    protected abstract Container getContainer()

  Returns the container for this cache.

### getCache

    protected CachePolicy getCache()

  Returns the cache policy used for this cache.

### getCacheLock

    public java.lang.Object getCacheLock()

  Returns the mutex used to sync access to the cache policy object

### passivate

    protected abstract void passivate(EnterpriseContext ctx)
                               throws java.rmi.RemoteException

  Passivates the given EnterpriseContext

### activate

    protected abstract void activate(EnterpriseContext ctx)
                              throws java.rmi.RemoteException

  Activates the given EnterpriseContext

### acquireContext

    protected abstract EnterpriseContext acquireContext()
                                                 throws java.lang.Exception

  Acquires an EnterpriseContext from the pool

### freeContext

    protected abstract void freeContext(EnterpriseContext ctx)

  Frees the given EnterpriseContext to the pool

### getKey

    protected abstract java.lang.Object getKey(EnterpriseContext ctx)

  Returns the key used by the cache to map the given context

### setKey

    protected abstract void setKey(java.lang.Object id,
                                   EnterpriseContext ctx)

  Sets the given id as key for the given context

### canPassivate

    protected abstract boolean canPassivate(EnterpriseContext ctx)

  Returns whether the given context can be passivated or not

Copyright © 2000 The JBoss Organization. All Rights Reserved.