de.ipcon.tools

Class StringBuilderPool

java.lang.Object

de.ipcon.tools.StringBuilderPool

public final class StringBuilderPool
extends java.lang.Object

A utility class designed to optimize the usage of StringBuilder objects.

This pool helps reduce object creation overhead by providing a mechanism to either reuse existing StringBuilder instances or create new ones when requested via getInstance().

After use, StringBuilder instances can be returned to the pool (implicitly by calling StringBuilderPool#finalToString(), which empties the instance and makes it available for reuse). This reuses previously allocated instances, reducing garbage collection pressure, assuming the pool has capacity to store them.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	finalToString(java.lang.StringBuilder b) Builds the final String from the provided StringBuilder and then resets (empties) the StringBuilder before attempting to return it to the pool.
static java.lang.StringBuilder	getInstance() Call this method to create or reuse an empty StringBuilder instance from the pool.
static java.lang.StringBuilder	getInstance(java.lang.String s) /** Call this method to create or reuse an empty StringBuilder instance from the pool, and immediately append the given string for convenience.
static boolean	isNull(java.lang.String s) Checks if the given string is considered null within the context of the StringBuilderPool class.
static void	release(java.lang.StringBuilder b) Releases a StringBuilder instance back to the pool for potential reuse.

Methods inherited from class java.lang.Object

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

Method Detail

isNull

public static final boolean isNull(java.lang.String s)

Checks if the given string is considered null within the context of the StringBuilderPool class. A string is considered null if it is a Java null or if its value is the specific string literal "null" (case-sensitive).

Parameters:

s - The String to check.

Returns:

true if the string is null or equals the NULL_STRING literal, false otherwise.

getInstance

public static final java.lang.StringBuilder getInstance()

Call this method to create or reuse an empty StringBuilder instance from the pool.

It is crucial to call finalToString(StringBuilder) or release(StringBuilder) to free the resource and return it to the pool once you have finished using it. Failure to do so will lead to resource leaks.

Returns:

An empty StringBuilder instance, ready for use.

See Also:

getInstance(String), finalToString(StringBuilder), release(StringBuilder)

getInstance

public static final java.lang.StringBuilder getInstance(java.lang.String s)

/** Call this method to create or reuse an empty StringBuilder instance from the pool, and immediately append the given string for convenience.

It is crucial to call finalToString(StringBuilder) or release(StringBuilder) to free the resource and return it to the pool once you have finished using it. Failure to do so will lead to resource leaks.

Parameters:

s - The String to append to the newly obtained StringBuilder instance.

Returns:

A StringBuilder instance with the given string already appended.

See Also:

getInstance(), finalToString(StringBuilder), release(StringBuilder)

release

public static final void release(java.lang.StringBuilder b)

Releases a StringBuilder instance back to the pool for potential reuse.

The instance is returned to the pool only if it is not null, the pool has not exceeded its POOL_SIZE limit, and the StringBuilder's capacity does not exceed MAXIMUM_CAPACITY. If any of these conditions are not met, the StringBuilder is simply discarded, allowing for garbage collection.

Before being returned to the pool, the StringBuilder's length is set to 0 to ensure it is empty for the next use. An IllegalArgumentException is thrown if the instance is detected to have been already released to the pool.

Parameters:

b - The StringBuilder instance to release.

Throws:

java.lang.IllegalArgumentException - If the provided StringBuilder instance is already in the pool.

finalToString

public static final java.lang.String finalToString(java.lang.StringBuilder b)

Builds the final String from the provided StringBuilder and then resets (empties) the StringBuilder before attempting to return it to the pool. This method is a convenience for the common pattern of converting a StringBuilder's content to a String and then disposing of the StringBuilder resource.

Parameters:

b - The StringBuilder instance to finalize.

Returns:

The finalized String created from the StringBuilder's content. If the provided StringBuilder is null, the string literal "null" (as defined by NULL_STRING) is returned.