Module com.github.robtimus.pool
Package com.github.robtimus.pool

Class PoolableObject<X extends Exception>

  • Type Parameters:
    X - The type of exception that operations on the object can throw.
    Direct Known Subclasses:
    ObjectWrapper
    public abstract class PoolableObject<X extends Exception>
extends Object
    An object that can be pooled. Note that the functionality to return the object back to the pool it was acquired from is not part of its public API. This allows implementations to call release() from other methods, e.g. a Closeable's close method.

    Instances of this class or sub classes are not expected to be thread-safe. Once acquired from a pool, they should usually be used in only one thread until they are released and returned back to the pool.

    Author:
    Rob Spoor

    • Constructor Detail

      • PoolableObject

        protected PoolableObject()
        Creates a new poolable object.

    • Method Detail

      • addReference

        protected final PoolableObject.Reference<X> addReference()
        Adds a reference to this object. An object will only be returned to the pool it was acquired from if all references to the object are removed. This allows objects to return other (closeable) objects like InputStream or OutputStream. For such objects, a reference should be added using this method, and the returned value should be removed or closed when the objects are no longer needed (e.g. when they are closed).
        Returns:
        An object representing the added reference.
        Since:
        2.0

      • validate

        protected abstract boolean validate()
        Checks whether or not this object is still valid. Invalid object will be removed from the pool instead of being returned from Pool.acquire() or Pool.acquireNow(). They will also have their resources released.
        Returns:
        true if this object is still valid, or false otherwise.

      • releaseResources

        protected abstract void releaseResources()
                                  throws X extends Exception
        Releases any resources associated with this object.
        Throws:
        X - If the resources could not be released.
        X extends Exception

      • release

        protected void release()
                throws X extends Exception
        Releases this object. If no more references remain, this object will be returned to the pool it was acquired from. If this object is not associated with a pool, releaseResources() will be called instead.
        Throws:
        X - If an exception is thrown when calling releaseResources().
        X extends Exception

      • logEvent

        protected final void logEvent​(String message)
        Logs a custom event for this object at debug level. The message should preferably be a compile-time constant; for calculated messages, use logEvent(Supplier) instead.

        Note: this method will use the logger of the Pool that manages this object. If this object is not pooled, this method will do nothing.

        Parameters:
        message - The event message.

      • logEvent

        protected final void logEvent​(LogLevel level,
                              String message)
        Logs a custom event for this object. The message should preferably be a compile-time constant; for calculated messages, use logEvent(LogLevel, Supplier) instead.

        Note: this method will use the logger of the Pool that manages this object. If this object is not pooled, this method will do nothing.

        Parameters:
        level - The log level to use.
        message - The event message.

      • logEvent

        protected final void logEvent​(Supplier<String> messageSupplier)
        Logs a custom event for this object at debug level.

        Note: this method will use the logger of the Pool that manages this object. If this object is not pooled, this method will do nothing.

        Parameters:
        messageSupplier - A supplier for the event message.

      • logEvent

        protected final void logEvent​(LogLevel level,
                              Supplier<String> messageSupplier)
        Logs a custom event for this object.

        Note: this method will use the logger of the Pool that manages this object. If this object is not pooled, this method will do nothing.

        Parameters:
        level - The log level to use.
        messageSupplier - A supplier for the event message.

      • isEnabled

        protected final boolean isEnabled​(LogLevel level)
        Returns whether or not logging at a specific level is enabled. This can be used to perform conditional configuration, like adding logging listeners conditionally.

        Note: this method will use the logger of the Pool that manages this object. If this object is not pooled, this method will return false.

        Parameters:
        level - The level to check.
        Returns:
        true if logging at the given level is enabled, or false otherwise.