ReflectionToStringBuilder

public class org.apache.commons.lang3.builder.ReflectionToStringBuilder extends ToStringBuilder

Assists in implementing Object#toString() methods using reflection.

This class uses reflection to determine the fields to append. Because these fields are usually private, the class uses java.lang.reflect.AccessibleObject#setAccessible(java.lang.reflect.AccessibleObject[], boolean) to change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions are set up correctly.

Using reflection to access (private) fields circumvents any synchronization protection guarding access to these fields. If a toString method cannot safely read a field, you should exclude it from the toString method, or use synchronization consistent with the class’ lock management around the invocation of the method. Take special care to exclude non-thread-safe collection classes, because these classes may throw ConcurrentModificationException if modified while the toString method is executing.

A typical invocation for this method would look like:

public String toString() {
    return ReflectionToStringBuilder.toString(this);
}

You can also use the builder to debug 3rd party objects:

System.out.println("An object: " + ReflectionToStringBuilder.toString(anObject));

A subclass can control field output by overriding the methods:

• #accept(java.lang.reflect.Field)

• #getValue(java.lang.reflect.Field)

For example, this method does not include the password field in the returned String:

public String toString() {
    return (new ReflectionToStringBuilder(this) {
        protected boolean accept(Field f) {
            return super.accept(f) && !f.getName().equals("password");
        }
    }).toString();
}

Alternatively the ToStringExclude annotation can be used to exclude fields from being incorporated in the result.

It is also possible to use the ToStringSummary annotation to output the summary information instead of the detailed information of a field.

The exact format of the toString is determined by the ToStringStyle passed into the constructor.

Note: the default ToStringStyle will only do a “shallow” formatting, i.e. composed objects are not further traversed. To get “deep” formatting, use an instance of RecursiveToStringStyle.

Since:

2.0

Constructors

ReflectionToStringBuilder(Object)	Constructs a new instance.
ReflectionToStringBuilder(Object, ToStringStyle)	Constructs a new instance.
ReflectionToStringBuilder(Object, ToStringStyle, StringBuffer)	Constructs a new instance.
ReflectionToStringBuilder(Object, ToStringStyle, StringBuffer, Class, boolean, boolean)	Constructs a new instance.
ReflectionToStringBuilder(Object, ToStringStyle, StringBuffer, Class, boolean, boolean, boolean)	Constructs a new instance.

public ReflectionToStringBuilder(Object object)

Constructs a new instance.

This constructor outputs using the default style set with setDefaultStyle.

Parameters:

object – the Object to build a toString for, must not be null

public ReflectionToStringBuilder(Object object, ToStringStyle style)

Constructs a new instance.

If the style is null, the default style is used.

Parameters:

• object – the Object to build a toString for, must not be null

• style – the style of the toString to create, may be null

public ReflectionToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer)

Constructs a new instance.

If the style is null, the default style is used.

If the buffer is null, a new one is created.

Parameters:

• object – the Object to build a toString for

• style – the style of the toString to create, may be null

• buffer – the StringBuffer to populate, may be null

public <T> ReflectionToStringBuilder(T object, ToStringStyle style, StringBuffer buffer, Class<? super T> reflectUpToClass, boolean outputTransients, boolean outputStatics)

Constructs a new instance.

Type parameters:

<T> – the type of the object

Parameters:

• object – the Object to build a toString for

• style – the style of the toString to create, may be null

• buffer – the StringBuffer to populate, may be null

• reflectUpToClass – the superclass to reflect up to (inclusive), may be null

• outputTransients – whether to include transient fields

• outputStatics – whether to include static fields

Since:

2.1

public <T> ReflectionToStringBuilder(T object, ToStringStyle style, StringBuffer buffer, Class<? super T> reflectUpToClass, boolean outputTransients, boolean outputStatics, boolean excludeNullValues)

Constructs a new instance.

Type parameters:

<T> – the type of the object

Parameters:

• object – the Object to build a toString for

• style – the style of the toString to create, may be null

• buffer – the StringBuffer to populate, may be null

• reflectUpToClass – the superclass to reflect up to (inclusive), may be null

• outputTransients – whether to include transient fields

• outputStatics – whether to include static fields

• excludeNullValues – whether to exclude fields who value is null

Since:

3.6

Fields and constants

excludeFieldNames	Which field names to exclude from output.
includeFieldNames	Field names that will be included in the output.

protected String[] excludeFieldNames

Which field names to exclude from output. Intended for fields like "password".

Since:

3.0 this is protected instead of private

protected String[] includeFieldNames

Field names that will be included in the output. All fields are included by default.

Since:

3.13.0

Methods

accept(Field)	Returns whether or not to append the given Field.
appendFieldsIn(Class)	Appends the fields and values defined by the given object of the given Class.
getExcludeFieldNames()	Gets the excludeFieldNames.
getIncludeFieldNames()	Gets the includeFieldNames
getUpToClass()	Gets the last super class to stop appending fields for.
getValue(Field)	Gets the field value using java.lang.reflect.Field.get(Object).
isAppendStatics()	Tests whether or not to append static fields.
isAppendTransients()	Tests whether or not to append transient fields.
isExcludeNullValues()	Tests whether or not to append fields whose values are null.
reflectionAppendArray(Object)	Appends to the toString an Object array.
setAppendStatics(boolean)	Sets whether or not to append static fields.
setAppendTransients(boolean)	Sets whether or not to append transient fields.
setExcludeFieldNames(String[])	Sets the field names to exclude.
setExcludeNullValues(boolean)	Sets whether or not to append fields whose values are null.
setIncludeFieldNames(String[])	Sets the field names to include.
setUpToClass(Class)	Sets the last super class to stop appending fields for.
toString()	Gets the String built by this builder.
toString(Object)	Builds a toString value using the default ToStringStyle through reflection.
toString(Object, ToStringStyle)	Builds a toString value through reflection.
toString(Object, ToStringStyle, boolean)	Builds a toString value through reflection.
toString(Object, ToStringStyle, boolean, boolean)	Builds a toString value through reflection.
toString(Object, ToStringStyle, boolean, boolean, boolean, Class)	Builds a toString value through reflection.
toString(Object, ToStringStyle, boolean, boolean, Class)	Builds a toString value through reflection.
toStringExclude(Object, String[])	Builds a String for a toString method excluding the given field names.
toStringExclude(Object, Collection)	Builds a String for a toString method excluding the given field names.
toStringInclude(Object, String[])	Builds a String for a toString method including the given field names.
toStringInclude(Object, Collection)	Builds a String for a toString method including the given field names.

protected boolean accept(Field field)

Returns whether or not to append the given Field.

• Transient fields are appended only if #isAppendTransients() returns true.

• Static fields are appended only if #isAppendStatics() returns true.

• Inner class fields are not appended.

Parameters:

field – The Field to test.

Returns:

Whether or not to append the given Field.

protected void appendFieldsIn(Class<?> clazz)

Appends the fields and values defined by the given object of the given Class.

If a cycle is detected as an object is “toString()’ed”, such an object is rendered as if Object.toString() had been called and not implemented by the object.

Parameters:

clazz – The class of object parameter

public String[] getExcludeFieldNames()

Gets the excludeFieldNames.

Returns:

The excludeFieldNames.

public String[] getIncludeFieldNames()

Gets the includeFieldNames

Returns:

The includeFieldNames.

Since:

3.13.0

public Class<?> getUpToClass()

Gets the last super class to stop appending fields for.

Returns:

The last super class to stop appending fields for.

protected Object getValue(Field field) throws IllegalAccessException

Gets the field value using java.lang.reflect.Field.get(Object).

Parameters:

field – The Field to query.

Returns:

The Object from the given Field.

Throws:

• java.lang.IllegalArgumentException – Thrown as described in java.lang.reflect.Field#get(Object).

• java.lang.IllegalAccessException – Thrown as described in java.lang.reflect.Field#get(Object).

See also:

java.lang.reflect.Field#get(Object)

public boolean isAppendStatics()

Tests whether or not to append static fields.

Returns:

Whether or not to append static fields.

Since:

2.1

public boolean isAppendTransients()

Tests whether or not to append transient fields.

Returns:

Whether or not to append transient fields.

public boolean isExcludeNullValues()

Tests whether or not to append fields whose values are null.

Returns:

Whether or not to append fields whose values are null.

Since:

3.6

public ReflectionToStringBuilder reflectionAppendArray(Object array)

Appends to the toString an Object array.

Parameters:

array – the array to add to the toString

Returns:

this instance.

public void setAppendStatics(boolean appendStatics)

Sets whether or not to append static fields.

Parameters:

appendStatics – Whether or not to append static fields.

Since:

2.1

public void setAppendTransients(boolean appendTransients)

Sets whether or not to append transient fields.

Parameters:

appendTransients – Whether or not to append transient fields.

public ReflectionToStringBuilder setExcludeFieldNames(String... excludeFieldNamesParam)

Sets the field names to exclude.

Parameters:

excludeFieldNamesParam – The excludeFieldNames to excluding from toString or null.

Returns:

this

public void setExcludeNullValues(boolean excludeNullValues)

Sets whether or not to append fields whose values are null.

Parameters:

excludeNullValues – Whether or not to append fields whose values are null.

Since:

3.6

public ReflectionToStringBuilder setIncludeFieldNames(String... includeFieldNamesParam)

Sets the field names to include. null or empty means all fields are included. All fields are included by default. This method will override the default behavior.

Parameters:

includeFieldNamesParam – The includeFieldNames that must be on toString or null.

Returns:

this

Since:

3.13.0

public void setUpToClass(Class<?> clazz)

Sets the last super class to stop appending fields for.

Parameters:

clazz – The last super class to stop appending fields for.

@Override public String toString()

Gets the String built by this builder.

Returns:

The built string

public static String toString(Object object)

Builds a toString value using the default ToStringStyle through reflection.

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.

Transient members will be not be included, as they are likely derived. Static fields will not be included. Superclass fields will be appended.

Parameters:

object – the Object to be output

Returns:

The String result

Throws:

java.lang.IllegalArgumentException – Thrown if the Object is null.

See also:

• ToStringExclude

• ToStringSummary

public static String toString(Object object, ToStringStyle style)

Builds a toString value through reflection.

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.

Transient members will be not be included, as they are likely derived. Static fields will not be included. Superclass fields will be appended.

If the style is null, the default ToStringStyle is used.

Parameters:

• object – the Object to be output

• style – the style of the toString to create, may be null

Returns:

The String result

Throws:

java.lang.IllegalArgumentException – Thrown if the Object or ToStringStyle is null.

See also:

• ToStringExclude

• ToStringSummary

public static String toString(Object object, ToStringStyle style, boolean outputTransients)

Builds a toString value through reflection.

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.

If the outputTransients is true, transient members will be output, otherwise they are ignored, as they are likely derived fields, and not part of the value of the Object.

Static fields will not be included. Superclass fields will be appended.

If the style is null, the default ToStringStyle is used.

Parameters:

• object – the Object to be output

• style – the style of the toString to create, may be null

• outputTransients – whether to include transient fields

Returns:

The String result

Throws:

java.lang.IllegalArgumentException – Thrown if the Object is null.

See also:

• ToStringExclude

• ToStringSummary

public static String toString(Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics)

Builds a toString value through reflection.

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.

If the outputTransients is true, transient fields will be output, otherwise they are ignored, as they are likely derived fields, and not part of the value of the Object.

If the outputStatics is true, static fields will be output, otherwise they are ignored.

Static fields will not be included. Superclass fields will be appended.

If the style is null, the default ToStringStyle is used.

Parameters:

• object – the Object to be output

• style – the style of the toString to create, may be null

• outputTransients – whether to include transient fields

• outputStatics – whether to include static fields

Returns:

The String result

Throws:

java.lang.IllegalArgumentException – Thrown if the Object is null.

See also:

• ToStringExclude

• ToStringSummary

Since:

2.1

public static <T> String toString(T object, ToStringStyle style, boolean outputTransients, boolean outputStatics, boolean excludeNullValues, Class<? super T> reflectUpToClass)

Builds a toString value through reflection.

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.

If the outputTransients is true, transient fields will be output, otherwise they are ignored, as they are likely derived fields, and not part of the value of the Object.

If the outputStatics is true, static fields will be output, otherwise they are ignored.

Superclass fields will be appended up to and including the specified superclass. A null superclass is treated as Object.

If the style is null, the default ToStringStyle is used.

Type parameters:

<T> – the type of the object

Parameters:

• object – the Object to be output

• style – the style of the toString to create, may be null

• outputTransients – whether to include transient fields

• outputStatics – whether to include static fields

• excludeNullValues – whether to exclude fields whose values are null

• reflectUpToClass – the superclass to reflect up to (inclusive), may be null

Returns:

The String result

Throws:

java.lang.IllegalArgumentException – Thrown if the Object is null.

See also:

• ToStringExclude

• ToStringSummary

Since:

3.6

public static <T> String toString(T object, ToStringStyle style, boolean outputTransients, boolean outputStatics, Class<? super T> reflectUpToClass)

Builds a toString value through reflection.

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.

If the outputTransients is true, transient fields will be output, otherwise they are ignored, as they are likely derived fields, and not part of the value of the Object.

If the outputStatics is true, static fields will be output, otherwise they are ignored.

Superclass fields will be appended up to and including the specified superclass. A null superclass is treated as Object.

If the style is null, the default ToStringStyle is used.

Type parameters:

<T> – the type of the object

Parameters:

• object – the Object to be output

• style – the style of the toString to create, may be null

• outputTransients – whether to include transient fields

• outputStatics – whether to include static fields

• reflectUpToClass – the superclass to reflect up to (inclusive), may be null

Returns:

The String result

Throws:

java.lang.IllegalArgumentException – Thrown if the Object is null.

See also:

• ToStringExclude

• ToStringSummary

Since:

2.1

public static String toStringExclude(Object object, String... excludeFieldNames)

Builds a String for a toString method excluding the given field names.

Parameters:

• object – The object to “toString”.

• excludeFieldNames – The field names to exclude

Returns:

The toString value.

public static String toStringExclude(Object object, Collection<String> excludeFieldNames)

Builds a String for a toString method excluding the given field names.

Parameters:

• object – The object to “toString”.

• excludeFieldNames – The field names to exclude. Null excludes nothing.

Returns:

The toString value.

public static String toStringInclude(Object object, String... includeFieldNames)

Builds a String for a toString method including the given field names.

Parameters:

• object – The object to “toString”.

• includeFieldNames – The field names to include. null or empty means all fields are included. All fields are included by default. This method will override the default behavior.

Returns:

The toString value.

Since:

3.13.0

public static String toStringInclude(Object object, Collection<String> includeFieldNames)

Builds a String for a toString method including the given field names.

Parameters:

• object – The object to “toString”.

• includeFieldNames – null or empty means all fields are included. All fields are included by default. This method will override the default behavior.

Returns:

The toString value.

Since:

3.13.0