CasPool (Apache UIMA Java SDK 2.9.0 User-Level API Documentation)

java.lang.Object
- org.apache.uima.util.CasPool

```
public class CasPool
extends Object
```
This class represents a simple pool of CAS instances. This is useful for multithreaded applications, where there is a need for multiple CASes to be processed simultaneously. Because CAS creation is expensive, it is a good idea to create a pool of reusable CAS instances at initialization time, rather than creating a new CAS each time one is needed.
Clients check-out CAS instances from the pool using the getCas() method and check-in CAS instances using the releaseCas(CAS) method.
Design considerations: The pool favors reuse of CASes is some arbitrary preferred priority order. For example if there is a pool of 10 CASes, but only 2 are being check-out at any given time, the same 2 CASes will be used (as opposed to a FIFO approach where all the CASes would be cycled through). If more threads request CASes from the pool than are available, the pool (optionally) puts requesting threads into a wait state. When CASes become available, the longest-waiting thread gets the CAS; this approach prevents starvation behavior (where some threads get all the CASes and others get none).

Constructor Summary

Constructors
Constructor and Description
`CasPool(int aNumInstances, AnalysisEngine aAnalysisEngine)` Creates a new CasPool
`CasPool(int aNumInstances, CasDefinition aCasDefinition, Properties aPerformanceTuningSettings)` Creates a new CasPool.
`CasPool(int aNumInstances, CasManager aCasManager, Properties aPerformanceTuningSettings)` Creates a new CasPool
`CasPool(int aNumInstances, Collection<? extends ProcessingResourceMetaData> aCollectionOfProcessingResourceMetaData, Properties aPerformanceTuningSettings, ResourceManager aResourceManager)` Creates a new CasPool
`CasPool(int aNumInstances, ProcessingResourceMetaData aMetaData)` Creates a new CasPool
`CasPool(int aNumInstances, ProcessingResourceMetaData aMetaData, ResourceManager aResourceManager)` Creates a new CasPool

Method Summary

Methods
Modifier and Type	Method and Description
`protected Vector<CAS>`	`getAllInstances()`
`CAS`	`getCas()` Checks out a CAS from the pool.
`CAS`	`getCas(long aTimeout)` Checks out a CAS from the pool.
`protected Vector<CAS>`	`getFreeInstances()`
`int`	`getNumAvailable()` Gets the number of CASes currently available in this pool.
`int`	`getSize()` Gets the size of this pool (the total number of CAS instances that it can hold).
`void`	`releaseCas(CAS aCas)` Checks in a CAS to the pool.

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

- Constructor Detail
  - CasPool
```
public CasPool(int aNumInstances,
       Collection<? extends ProcessingResourceMetaData> aCollectionOfProcessingResourceMetaData,
       Properties aPerformanceTuningSettings,
       ResourceManager aResourceManager)
        throws ResourceInitializationException
```
    Creates a new CasPool
    
    Parameters:
    aNumInstances - the number of CAS instances in the pool
    aCollectionOfProcessingResourceMetaData - a collection of ProcessingResourceMetaData objects.
    aPerformanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
    aResourceManager - the resource manager to use to resolve import declarations within the metadata
    
    Throws:
    
    ResourceInitializationException - if the CAS instances could not be created
  - CasPool
```
public CasPool(int aNumInstances,
       AnalysisEngine aAnalysisEngine)
        throws ResourceInitializationException
```
    Creates a new CasPool
    
    Parameters:
    aNumInstances - the number of CAS instances in the pool
    aAnalysisEngine - the analysis engine that will create the CAS instances and which will later be used to process them
    
    Throws:
    
    ResourceInitializationException - if the CAS instances could not be created
  - CasPool
```
public CasPool(int aNumInstances,
       ProcessingResourceMetaData aMetaData)
        throws ResourceInitializationException
```
    Creates a new CasPool
    
    Parameters:
    aNumInstances - the number of CAS instances in the pool
    aMetaData - metadata that includes the type system for the CAS
    
    Throws:
    
    ResourceInitializationException - if the CAS instances could not be created
  - CasPool
```
public CasPool(int aNumInstances,
       ProcessingResourceMetaData aMetaData,
       ResourceManager aResourceManager)
        throws ResourceInitializationException
```
    Creates a new CasPool
    
    Parameters:
    aNumInstances - the number of CAS instances in the pool
    aMetaData - metadata that includes the type system for the CAS
    aResourceManager - Resource Manager
    
    Throws:
    
    ResourceInitializationException - if the CAS instances could not be created
  - CasPool
```
public CasPool(int aNumInstances,
       CasDefinition aCasDefinition,
       Properties aPerformanceTuningSettings)
        throws ResourceInitializationException
```
    Creates a new CasPool. TODO: do we need this method AND the one that takes a CasManager?
    
    Parameters:
    aNumInstances - the number of CAS instances in the pool
    aCasDefinition - the Cas definition, which includes the type system, type priorities, and indexes for the CASes in the pool.
    aPerformanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
    
    Throws:
    
    ResourceInitializationException - -
  - CasPool
```
public CasPool(int aNumInstances,
       CasManager aCasManager,
       Properties aPerformanceTuningSettings)
        throws ResourceInitializationException
```
    Creates a new CasPool
    
    Parameters:
    aNumInstances - the number of CAS instances in the pool
    aCasManager - CAS Manager that will be used to create the CAS. The CAS Manager holds the CAS Definition. Also all CASes created from the same CAS Manager will share identical TypeSystem objects.
    aPerformanceTuningSettings - Properties object containing framework performance tuning settings using key names defined on UIMAFramework interface
    
    Throws:
    
    ResourceInitializationException - -
- Method Detail
  - getCas
```
public CAS getCas()
```
    Checks out a CAS from the pool.
    
    Returns:
    a CAS instance. Returns null if none are available (in which case the client may Object.wait() on this object in order to be notified when an instance becomes available).
  - getCas
```
public CAS getCas(long aTimeout)
```
    Checks out a CAS from the pool. If none is currently available, wait for the specified amount of time for one to be checked in.
    
    Parameters:
    aTimeout - the time to wait in milliseconds. A value of <=0 will wait forever.
    
    Returns:
    a CAS instance. Returns null if none are available within the specified timeout period.
  - releaseCas
```
public void releaseCas(CAS aCas)
```
    Checks in a CAS to the pool. This automatically calls the CAS.reset() method, to ensure that when the CAS is later retrieved from the pool it will be ready to use. Also notifies other Threads that may be waiting for an instance to become available. Synchronized on the CAS to avoid the unnatural case where multiple threads attempt to return the same CAS to the pool at the same time.
    
    Parameters:
    aCas - the Cas to release
  - getSize
```
public int getSize()
```
    Gets the size of this pool (the total number of CAS instances that it can hold).
    
    Returns:
    the size of this pool
  - getNumAvailable
```
public int getNumAvailable()
```
    Gets the number of CASes currently available in this pool.
    
    Returns:
    the numberof available CASes
  - getAllInstances
```
protected Vector<CAS> getAllInstances()
```
  - getFreeInstances
```
protected Vector<CAS> getFreeInstances()
```

Class CasPool

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CasPool

CasPool

CasPool

CasPool

CasPool

CasPool

Method Detail

getCas

getCas

releaseCas

getSize

getNumAvailable

getAllInstances

getFreeInstances