Package de.aristaflow.adept2.util.objectpool

Interface ObjectWrapperLifeCycle<T,E extends Exception>

Type Parameters:
T - the type of object wrapped by this wrapper life cycle
E - the specific type of exceptions associated when using the objects
public interface ObjectWrapperLifeCycle<T,E extends Exception>
This interface is a companion to ObjectLifeCycle, defining and allowing to control the life cycle of an object wrapper.

Wrappers are required if object pools should not hand out references to the actual objects. This prevents that references to the real object are kept (and used) even after checking an object back into the pool. This also allows the pool to forcibly reclaim the pooled object if necessary by invalidating the wrapper. Another benefit is that objects can be returned to the pool without the user needing a reference to the pool, i.e. only the wrapper needs to have it.

Also, interfaces that provide methods to explicitly release the resource, like Connection.close(), will need to be wrapped. This allows the objects to be treated as usual, without having the user to know whether - to stick with the example - the connection is actually closed or returned to a pool behind the scenes.

AbstractObjectWrapper is a convenient base class for wrapper implementations.

Author:
Patrick Schmidt

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    getLastActiveTime(T wrapper)
    Returns the time of the wrapped object's last recorded activity (i.e.
    void
    invalidate(T wrapper)
    Invalidates the given wrapper.
    boolean
    isWrapper(T object)
    Returns whether the given object is a wrapper (as returned by wrap(ObjectPool,Object)).
    T
    unwrap(T wrapper)
    Returns the object that is wrapped by the given wrapper (as returned by wrap(ObjectPool,Object)).
    T
    wrap(ObjectPool<T,E> objectPool, T object)
    Wraps the given object and returns the created wrapper.

  • Method Details

    • wrap

      T wrap(ObjectPool<T,E> objectPool, T object)
      Wraps the given object and returns the created wrapper.

      This method is not supposed to call any methods on the given object pool. Instead the reference is just passed on to the wrapper if it needs it.

      Parameters:
      objectPool - the object pool calling this method
      object - the object to be wrapped
      Returns:
      the wrapper for the given object

    • unwrap

      T unwrap(T wrapper)
      Returns the object that is wrapped by the given wrapper (as returned by wrap(ObjectPool,Object)). This will not invalidate the wrapper!
      Parameters:
      wrapper - the wrapper for which to return the contained object
      Returns:
      the object that is wrapped by the given wrapper
      Throws:
      ClassCastException - if the given object is no wrapper
      IllegalArgumentException - if the wrapper has already been invalidated

    • isWrapper

      boolean isWrapper(T object)
      Returns whether the given object is a wrapper (as returned by wrap(ObjectPool,Object)).
      Parameters:
      object - the object to be tested
      Returns:
      whether the given object is a wrapper

    • invalidate

      void invalidate(T wrapper)
      Invalidates the given wrapper. I.e. all subsequent attempts to use the object through that wrapper must fail, e.g. by throwing an IllegalStateException.
      Parameters:
      wrapper - the wrapper to be invalidated
      Throws:
      IllegalArgumentException - if the given object is no wrapper

    • getLastActiveTime

      long getLastActiveTime(T wrapper)
      Returns the time of the wrapped object's last recorded activity (i.e. the last time, the wrapped object was used by the borrower). This information may be present in the wrapped object directly or provided by the wrapper. If this information is not available at all, -1 is returned.
      Parameters:
      wrapper - the wrapper of the object
      Returns:
      the time of the wrapped object's last recorded activity or -1 if this information is not available; other negative numbers are not allowed
      Throws:
      IllegalArgumentException - if the given object is no wrapper or the wrapper has already been invalidated