com.github.robtimus.pool

Class PoolableObject<X extends Exception>

java.lang.Object

com.github.robtimus.pool.PoolableObject<X>

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 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 Summary

Constructors

Modifier	Constructor and Description
protected	PoolableObject() Creates a new poolable object.

Method Summary

Modifier and Type	Method and Description
protected void	addReference(Object reference) Adds a reference to this object.
protected boolean	isEnabled(LogLevel level) Returns whether or not logging at a specific level is enabled.
protected void	logEvent(LogLevel level, String message) Logs a custom event for this object.
protected void	logEvent(LogLevel level, Supplier<String> messageSupplier) Logs a custom event for this object.
protected void	logEvent(String message) Logs a custom event for this object at debug level.
protected void	logEvent(Supplier<String> messageSupplier) Logs a custom event for this object at debug level.
protected void	release() Releases this object.
protected abstract void	releaseResources() Releases any resources associated with this object.
protected void	removeReference(Object reference) Removes a reference to this object.
protected abstract boolean	validate() Checks whether or not this object is still valid.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PoolableObject

protected PoolableObject()

Creates a new poolable object.

Method Detail

addReference

protected final void addReference(Object reference)

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. These should be added as reference, and removed when they are no longer needed (e.g. when they are closed).

Parameters:

reference - The non-null reference to add.

Throws:

NullPointerException - If the given reference is null.

removeReference

protected final void removeReference(Object reference)
                              throws X extends Exception

Removes a reference to 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.

Parameters:

reference - The non-null reference to remove.

Throws:

NullPointerException - If the given reference is null.

X - If an exception is thrown when calling releaseResources().

X extends Exception

See Also:

addReference(Object)

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.