Utility for preventing primitive parameter values from being auto-boxed. Auto-boxing creates temporary objects which contribute to pressure on the garbage collector. With this utility users can convert primitive values directly into text without allocating temporary objects.

Example usage:

import static org.apache.logging.log4j.util.Unbox.box;
...
long longValue = 123456L;
double doubleValue = 3.14;
// prevent primitive values from being auto-boxed
logger.debug("Long value={}, double value={}", box(longValue), box(doubleValue));

This class manages a small thread-local ring buffer of StringBuilders. Each time one of the box() methods is called, the next slot in the ring buffer is used, until the ring buffer is full and the first slot is reused. By default the Unbox ring buffer has 32 slots, so user code can have up to 32 boxed primitives in a single logger call.

If more slots are required, set system property log4j.unbox.ringbuffer.size to the desired ring buffer size. Note that the specified number will be rounded up to the nearest power of 2.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	Unbox.State
private static class	Unbox.WebSafeState State implementation that only puts JDK classes in ThreadLocals, so this is safe to be used from web applications.

Field Summary

Modifier and Type	Field and Description
private static final int	BITS_PER_INT
private static final Logger	LOGGER
private static final int	MASK
private static final int	RINGBUFFER_MIN_SIZE
private static final int	RINGBUFFER_SIZE
private static ThreadLocal<Unbox.State>	threadLocalState
private static Unbox.WebSafeState	webSafeState

Constructor Summary

Access	Constructor and Description
private	Unbox()

Method Summary

Modifier and Type	Method and Description
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final float the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final double the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final short the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final int the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final char the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final long the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final byte the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
public static StringBuilder	Returns: a `StringBuilder` containing the text representation of the specified primitive value box(final boolean the value whose text representation to return value) Returns a `StringBuilder` containing the text representation of the specified primitive value.
private static int	calculateRingBufferSize(final String propertyName)
private static int	Returns: The next power of 2 from x inclusive ceilingNextPowerOfTwo(final int Value to round up x) Calculate the next power of 2, greater than or equal to x.
pack-priv static int	getRingbufferSize() For testing.
private static StringBuilder	getSB()
private static Unbox.State	getState()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

BITS_PER_INT	back to summary
private static final int BITS_PER_INT

LOGGER	back to summary
private static final Logger LOGGER

MASK	back to summary
private static final int MASK

RINGBUFFER_MIN_SIZE	back to summary
private static final int RINGBUFFER_MIN_SIZE

RINGBUFFER_SIZE	back to summary
private static final int RINGBUFFER_SIZE

threadLocalState	back to summary
private static ThreadLocal<Unbox.State> threadLocalState

webSafeState	back to summary
private static Unbox.WebSafeState webSafeState

Constructor Detail

Unbox	back to summary
private Unbox()

Method Detail

box back to summary

box	back to summary
public static StringBuilder box(final float value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:float the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final float value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:float: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

box back to summary

box	back to summary
public static StringBuilder box(final double value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:double the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final double value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:double: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

box back to summary

box	back to summary
public static StringBuilder box(final short value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:short the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final short value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:short: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

box back to summary

box	back to summary
public static StringBuilder box(final int value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:int the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final int value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:int: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

box back to summary

box	back to summary
public static StringBuilder box(final char value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:char the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final char value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:char: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

box back to summary

box	back to summary
public static StringBuilder box(final long value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:long the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final long value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:long: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

box back to summary

box	back to summary
public static StringBuilder box(final byte value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:byte the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final byte value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:byte: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

box back to summary

box	back to summary
public static StringBuilder box(final boolean value) Returns a `StringBuilder` containing the text representation of the specified primitive value. This method will not allocate temporary objects. Parameters value:boolean the value whose text representation to return Returns:StringBuilder a `StringBuilder` containing the text representation of the specified primitive value Annotations @PerformanceSensitive:allocation

public static StringBuilder box(final boolean value)

Returns a StringBuilder containing the text representation of the specified primitive value. This method will not allocate temporary objects.

Parameters

value:boolean: the value whose text representation to return

Returns:StringBuilder

a StringBuilder containing the text representation of the specified primitive value

Annotations

@PerformanceSensitive:allocation

calculateRingBufferSize	back to summary
private static int calculateRingBufferSize(final String propertyName)

ceilingNextPowerOfTwo	back to summary
private static int ceilingNextPowerOfTwo(final int x) Calculate the next power of 2, greater than or equal to x. From Hacker's Delight, Chapter 3, Harry S. Warren Jr. Parameters x:int Value to round up Returns:int The next power of 2 from x inclusive

ceilingNextPowerOfTwo

back to summary

private static int ceilingNextPowerOfTwo(final int x)

Calculate the next power of 2, greater than or equal to x.

From Hacker's Delight, Chapter 3, Harry S. Warren Jr.

Parameters

x:int: Value to round up

Returns:int

The next power of 2 from x inclusive

getRingbufferSize	back to summary
pack-priv static int getRingbufferSize() For testing.

getSB	back to summary
private static StringBuilder getSB()

getState	back to summary
private static Unbox.State getState()

org.apache.logging.log4j.util back to summary

private Class Unbox.State

Class Inheritance

extends Object

java.lang.Object
org.apache.logging.log4j.util.Unbox.State

Field Summary

Modifier and Type	Field and Description
private int	current
private final StringBuilder[]	ringBuffer

Constructor Summary

Access	Constructor and Description
pack-priv	State()

Method Summary

Modifier and Type	Method and Description
public StringBuilder	getStringBuilder()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

current	back to summary
private int current

ringBuffer	back to summary
private final StringBuilder[] ringBuffer

Constructor Detail

State	back to summary
pack-priv State()

Method Detail

getStringBuilder	back to summary
public StringBuilder getStringBuilder()

org.apache.logging.log4j.util back to summary

private Class Unbox.WebSafeState

Class Inheritance

extends Object

java.lang.Object
org.apache.logging.log4j.util.Unbox.WebSafeState

Annotations

@SuppressWarnings:ThreadLocalUsage

State implementation that only puts JDK classes in ThreadLocals, so this is safe to be used from web applications. Web application containers have thread pools that may hold on to ThreadLocal objects after the application was stopped. This may prevent the classes of the application from being unloaded, causing memory leaks.

Such memory leaks will not occur if only JDK classes are stored in ThreadLocals.

Field Summary

Modifier and Type	Field and Description
private final ThreadLocal<int[]>	current
private final ThreadLocal<StringBuilder[]>	ringBuffer

Constructor Summary

Access	Constructor and Description
private	WebSafeState()

Method Summary

Modifier and Type	Method and Description
public StringBuilder	getStringBuilder()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

current	back to summary
private final ThreadLocal<int[]> current

ringBuffer	back to summary
private final ThreadLocal<StringBuilder[]> ringBuffer

Constructor Detail

WebSafeState	back to summary
private WebSafeState()

Method Detail

getStringBuilder	back to summary
public StringBuilder getStringBuilder()

public Class Unbox

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class Unbox.State

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class Unbox.WebSafeState

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail