This class tracks the objects being pooled with a reference
counting mechanism. This is a general description of the states
followed by their expected transitions.
Base states:
- STATE_NEW -- The resource has just been created. A resource
is only in this state until the first state transition occurs.
- STATE_AVAILABLE -- The resource may be selected by useResource.
The resource may also be selected for garbage collection by the pool.
- STATE_DESTROYED -- The resource has been destroyed by the pool.
There may be a lag here between pool destruction and JVM finalization
if the resource was referenced at the time that it is destroyed.
- STATE_INVALID -- Not used.
Extended states:
- STATE_RELEASED -- The resource is not "used". A resource is only
used if a thread has invoked useResource and has not yet invoked a matching
releaseResource. For useexclusive mode the ApplicationPool should not
transition a resource to released state until the last referencing
thread has released that resource.
- STATE_REFERENCED -- The resource is not referenced. The resource has
a positive ref count. This state actually tracks with RELEASED (a
released resource is always unreferenced and a referenced resource is
always not released) but the state is used by a different subsystem
(useexclusive). I think we could polish this by combining the two. The
historical reason for the two is simply that the two states evolved from
different implementations -- REFERENCED has always been a ResourcePool
state while RELEASED was only promoted to a ResourcePool state recently.
After checkout the following states are expected:
- useexclusive=true. STATE_REFERENCED
- useexclusive=false. STATE_REFERENCED | STATE_AVAILABLE.
After checkin the following states are expected:
- Reserved checkin (useexclusive=false). STATE_RELEASED
- Shared checkin (useexclusive=true). STATE_AVAILABLE | STATE_RELEASED
- useexclusive=true. n-1st referencing thread release - STATE_AVAILABLE | STATE_REFERENCED
- useexclusive=true. nth referencing thread release - STATE_AVAILABLE | STATE_RELEASED