Top Description Fields Constructors Methods
org.apache.commons.lang3.builder

public Class ReflectionToStringBuilder

extends ToStringBuilder
Class Inheritance
Imports
java.lang.reflect.AccessibleObject, .Field, .Modifier, java.util.Arrays, .Collection, .Comparator, .Objects, org.apache.commons.lang3.ArraySorter, .ArrayUtils, .ClassUtils, org.apache.commons.lang3.stream.Streams
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:

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

Field Summary

Modifier and TypeField and Description
private boolean
appendStatics

Whether or not to append static fields.

private boolean
appendTransients

Whether or not to append transient fields.

protected String[]
excludeFieldNames

Which field names to exclude from output.

private boolean
excludeNullValues

Whether or not to append fields that are null.

protected String[]
includeFieldNames

Field names that will be included in the output.

private Class<?>
upToClass

The last super class to stop appending fields for.

Constructor Summary

AccessConstructor and Description
public
ReflectionToStringBuilder(final Object
the Object to build a toString for, must not be null
object)

Constructs a new instance.

public
ReflectionToStringBuilder(final Object
the Object to build a toString for, must not be null
object, final ToStringStyle
the style of the toString to create, may be null
style)

Constructs a new instance.

public
ReflectionToStringBuilder(final Object
the Object to build a toString for
object, final ToStringStyle
the style of the toString to create, may be null
style, final StringBuffer
the StringBuffer to populate, may be null
buffer)

Constructs a new instance.

public <
the type of the object
T>
ReflectionToStringBuilder(final T
the Object to build a toString for
object, final ToStringStyle
the style of the toString to create, may be null
style, final StringBuffer
the StringBuffer to populate, may be null
buffer, final Class<? super T>
the superclass to reflect up to (inclusive), may be null
reflectUpToClass, final boolean
whether to include transient fields
outputTransients, final boolean
whether to include static fields
outputStatics)

Constructs a new instance.

public <
the type of the object
T>
ReflectionToStringBuilder(final T
the Object to build a toString for
object, final ToStringStyle
the style of the toString to create, may be null
style, final StringBuffer
the StringBuffer to populate, may be null
buffer, final Class<? super T>
the superclass to reflect up to (inclusive), may be null
reflectUpToClass, final boolean
whether to include transient fields
outputTransients, final boolean
whether to include static fields
outputStatics, final boolean
whether to exclude fields who value is null
excludeNullValues)

Constructs a new instance.

Method Summary

Modifier and TypeMethod and Description
protected boolean

Returns:

Whether or not to append the given Field.
accept(final Field
The Field to test.
field)

Returns whether or not to append the given Field.

protected void
appendFieldsIn(final Class<?>
The class of object parameter
clazz)

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

public String[]

Returns:

the excludeFieldNames.
getExcludeFieldNames()

Gets the excludeFieldNames.

public String[]

Returns:

the includeFieldNames.
getIncludeFieldNames()

Gets the includeFieldNames

public Class<?>

Returns:

The last super class to stop appending fields for.
getUpToClass()

Gets the last super class to stop appending fields for.

protected Object

Returns:

The Object from the given Field.
getValue(final Field
The Field to query.
field)

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

public boolean

Returns:

Whether or not to append static fields.
isAppendStatics()

Gets whether or not to append static fields.

public boolean

Returns:

Whether or not to append transient fields.
isAppendTransients()

Gets whether or not to append transient fields.

public boolean

Returns:

Whether or not to append fields whose values are null.
isExcludeNullValues()

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

public ReflectionToStringBuilder

Returns:

this instance.
reflectionAppendArray(final Object
the array to add to the toString
array)

Appends to the toString an Object array.

public void
setAppendStatics(final boolean
Whether or not to append static fields.
appendStatics)

Sets whether or not to append static fields.

public void
setAppendTransients(final boolean
Whether or not to append transient fields.
appendTransients)

Sets whether or not to append transient fields.

public ReflectionToStringBuilder

Returns:

this
setExcludeFieldNames(final String...
The excludeFieldNames to excluding from toString or null.
excludeFieldNamesParam)

Sets the field names to exclude.

public void
setExcludeNullValues(final boolean
Whether or not to append fields whose values are null.
excludeNullValues)

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

public ReflectionToStringBuilder

Returns:

this
setIncludeFieldNames(final String...
The includeFieldNames that must be on toString or null.
includeFieldNamesParam)

Sets the field names to include.

public void
setUpToClass(final Class<?>
The last super class to stop appending fields for.
clazz)

Sets the last super class to stop appending fields for.

pack-priv static String[]

Returns:

A new array of Strings.
toNoNullStringArray(final Collection<String>
The collection to convert
collection)

Converts the given Collection into an array of Strings.

pack-priv static String[]

Returns:

The given array or a new array without null.
toNoNullStringArray(final Object[]
The array to check
array)

Returns a new array of Strings without null elements.

public static String

Returns:

the String result
toString(final Object
the Object to be output
object)

Builds a toString value using the default ToStringStyle through reflection.

public static String

Returns:

the String result
toString(final Object
the Object to be output
object, final ToStringStyle
the style of the toString to create, may be null
style)

Builds a toString value through reflection.

public static String

Returns:

the String result
toString(final Object
the Object to be output
object, final ToStringStyle
the style of the toString to create, may be null
style, final boolean
whether to include transient fields
outputTransients)

Builds a toString value through reflection.

public static String

Returns:

the String result
toString(final Object
the Object to be output
object, final ToStringStyle
the style of the toString to create, may be null
style, final boolean
whether to include transient fields
outputTransients, final boolean
whether to include static fields
outputStatics)

Builds a toString value through reflection.

public static <
the type of the object
T> String

Returns:

the String result
toString(final T
the Object to be output
object, final ToStringStyle
the style of the toString to create, may be null
style, final boolean
whether to include transient fields
outputTransients, final boolean
whether to include static fields
outputStatics, final boolean
whether to exclude fields whose values are null
excludeNullValues, final Class<? super T>
the superclass to reflect up to (inclusive), may be null
reflectUpToClass)

Builds a toString value through reflection.

public static <
the type of the object
T> String

Returns:

the String result
toString(final T
the Object to be output
object, final ToStringStyle
the style of the toString to create, may be null
style, final boolean
whether to include transient fields
outputTransients, final boolean
whether to include static fields
outputStatics, final Class<? super T>
the superclass to reflect up to (inclusive), may be null
reflectUpToClass)

Builds a toString value through reflection.

public String

Returns:

the built string
toString()

Overrides org.apache.commons.lang3.builder.ToStringBuilder.toString.

Gets the String built by this builder.

public static String

Returns:

The toString value.
toStringExclude(final Object
The object to "toString".
object, final Collection<String>
The field names to exclude. Null excludes nothing.
excludeFieldNames)

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

public static String

Returns:

The toString value.
toStringExclude(final Object
The object to "toString".
object, final String...
The field names to exclude
excludeFieldNames)

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

public static String

Returns:

The toString value.
toStringInclude(final Object
The object to "toString".
object, final Collection<String>
null or empty means all fields are included. All fields are included by default. This method will override the default behavior.
includeFieldNames)

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

public static String

Returns:

The toString value.
toStringInclude(final Object
The object to "toString".
object, final String...
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.
includeFieldNames)

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

private void
validate()

Validates that include and exclude names do not intersect.

Inherited from org.apache.commons.lang3.builder.ToStringBuilder:
appendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendappendAsObjectToStringappendSuperappendToStringbuildgetDefaultStylegetObjectgetStringBuffergetStylereflectionToStringreflectionToStringreflectionToStringreflectionToStringsetDefaultStyle

Field Detail

appendStaticsback to summary
private boolean appendStatics

Whether or not to append static fields.

appendTransientsback to summary
private boolean appendTransients

Whether or not to append transient fields.

excludeFieldNamesback to summary
protected String[] excludeFieldNames

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

Since
3.0 this is protected instead of private
excludeNullValuesback to summary
private boolean excludeNullValues

Whether or not to append fields that are null.

includeFieldNamesback to summary
protected String[] includeFieldNames

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

Since
3.13.0
upToClassback to summary
private Class<?> upToClass

The last super class to stop appending fields for.

Constructor Detail

ReflectionToStringBuilderback to summary
public ReflectionToStringBuilder(final Object object)

Constructs a new instance.

This constructor outputs using the default style set with setDefaultStyle.

Parameters
object:Object

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

ReflectionToStringBuilderback to summary
public ReflectionToStringBuilder(final Object object, final ToStringStyle style)

Constructs a new instance.

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

Parameters
object:Object

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

style:ToStringStyle

the style of the toString to create, may be null

ReflectionToStringBuilderback to summary
public ReflectionToStringBuilder(final Object object, final ToStringStyle style, final 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:Object

the Object to build a toString for

style:ToStringStyle

the style of the toString to create, may be null

buffer:StringBuffer

the StringBuffer to populate, may be null

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

Constructs a new instance.

Parameters
<T>
the type of the object
object:T

the Object to build a toString for

style:ToStringStyle

the style of the toString to create, may be null

buffer:StringBuffer

the StringBuffer to populate, may be null

reflectUpToClass:Class<? super T>

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

outputTransients:boolean

whether to include transient fields

outputStatics:boolean

whether to include static fields

Since
2.1
ReflectionToStringBuilderback to summary
public <T> ReflectionToStringBuilder(final T object, final ToStringStyle style, final StringBuffer buffer, final Class<? super T> reflectUpToClass, final boolean outputTransients, final boolean outputStatics, final boolean excludeNullValues)

Constructs a new instance.

Parameters
<T>
the type of the object
object:T

the Object to build a toString for

style:ToStringStyle

the style of the toString to create, may be null

buffer:StringBuffer

the StringBuffer to populate, may be null

reflectUpToClass:Class<? super T>

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

outputTransients:boolean

whether to include transient fields

outputStatics:boolean

whether to include static fields

excludeNullValues:boolean

whether to exclude fields who value is null

Since
3.6

Method Detail

acceptback to summary
protected boolean accept(final Field field)

Returns whether or not to append the given Field.

Parameters
field:Field

The Field to test.

Returns:boolean

Whether or not to append the given Field.

appendFieldsInback to summary
protected void appendFieldsIn(final 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:Class<?>

The class of object parameter

getExcludeFieldNamesback to summary
public String[] getExcludeFieldNames()

Gets the excludeFieldNames.

Returns:String[]

the excludeFieldNames.

getIncludeFieldNamesback to summary
public String[] getIncludeFieldNames()

Gets the includeFieldNames

Returns:String[]

the includeFieldNames.

Since
3.13.0
getUpToClassback to summary
public Class<?> getUpToClass()

Gets the last super class to stop appending fields for.

Returns:Class<?>

The last super class to stop appending fields for.

getValueback to summary
protected Object getValue(final Field field) throws IllegalAccessException

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

Parameters
field:Field

The Field to query.

Returns:Object

The Object from the given Field.

Exceptions
IllegalAccessException:
see java.lang.reflect.Field#get(Object)
IllegalArgumentException:
see java.lang.reflect.Field#get(Object)
See Also
java.lang.reflect.Field#get(Object)
isAppendStaticsback to summary
public boolean isAppendStatics()

Gets whether or not to append static fields.

Returns:boolean

Whether or not to append static fields.

Since
2.1
isAppendTransientsback to summary
public boolean isAppendTransients()

Gets whether or not to append transient fields.

Returns:boolean

Whether or not to append transient fields.

isExcludeNullValuesback to summary
public boolean isExcludeNullValues()

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

Returns:boolean

Whether or not to append fields whose values are null.

Since
3.6
reflectionAppendArrayback to summary
public ReflectionToStringBuilder reflectionAppendArray(final Object array)

Appends to the toString an Object array.

Parameters
array:Object

the array to add to the toString

Returns:ReflectionToStringBuilder

this instance.

setAppendStaticsback to summary
public void setAppendStatics(final boolean appendStatics)

Sets whether or not to append static fields.

Parameters
appendStatics:boolean

Whether or not to append static fields.

Since
2.1
setAppendTransientsback to summary
public void setAppendTransients(final boolean appendTransients)

Sets whether or not to append transient fields.

Parameters
appendTransients:boolean

Whether or not to append transient fields.

setExcludeFieldNamesback to summary
public ReflectionToStringBuilder setExcludeFieldNames(final String... excludeFieldNamesParam)

Sets the field names to exclude.

Parameters
excludeFieldNamesParam:String[]

The excludeFieldNames to excluding from toString or null.

Returns:ReflectionToStringBuilder

this

setExcludeNullValuesback to summary
public void setExcludeNullValues(final boolean excludeNullValues)

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

Parameters
excludeNullValues:boolean

Whether or not to append fields whose values are null.

Since
3.6
setIncludeFieldNamesback to summary
public ReflectionToStringBuilder setIncludeFieldNames(final 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:String[]

The includeFieldNames that must be on toString or null.

Returns:ReflectionToStringBuilder

this

Since
3.13.0
setUpToClassback to summary
public void setUpToClass(final Class<?> clazz)

Sets the last super class to stop appending fields for.

Parameters
clazz:Class<?>

The last super class to stop appending fields for.

toNoNullStringArrayback to summary
pack-priv static String[] toNoNullStringArray(final Collection<String> collection)

Converts the given Collection into an array of Strings. The returned array does not contain null entries. Note that Arrays#sort(Object[]) will throw an NullPointerException if an array element is null.

Parameters
collection:Collection<String>

The collection to convert

Returns:String[]

A new array of Strings.

toNoNullStringArrayback to summary
pack-priv static String[] toNoNullStringArray(final Object[] array)

Returns a new array of Strings without null elements. Internal method used to normalize exclude lists (arrays and collections). Note that Arrays#sort(Object[]) will throw an NullPointerException if an array element is null.

Parameters
array:Object[]

The array to check

Returns:String[]

The given array or a new array without null.

toStringback to summary
public static String toString(final 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:Object

the Object to be output

Returns:String

the String result

Exceptions
IllegalArgumentException:
if the Object is null
See Also
ToStringExclude, ToStringSummary
toStringback to summary
public static String toString(final Object object, final 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:Object

the Object to be output

style:ToStringStyle

the style of the toString to create, may be null

Returns:String

the String result

Exceptions
IllegalArgumentException:
if the Object or ToStringStyle is null
See Also
ToStringExclude, ToStringSummary
toStringback to summary
public static String toString(final Object object, final ToStringStyle style, final 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:Object

the Object to be output

style:ToStringStyle

the style of the toString to create, may be null

outputTransients:boolean

whether to include transient fields

Returns:String

the String result

Exceptions
IllegalArgumentException:
if the Object is null
See Also
ToStringExclude, ToStringSummary
toStringback to summary
public static String toString(final Object object, final ToStringStyle style, final boolean outputTransients, final 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:Object

the Object to be output

style:ToStringStyle

the style of the toString to create, may be null

outputTransients:boolean

whether to include transient fields

outputStatics:boolean

whether to include static fields

Returns:String

the String result

Exceptions
IllegalArgumentException:
if the Object is null
Since
2.1
See Also
ToStringExclude, ToStringSummary
toStringback to summary
public static <T> String toString(final T object, final ToStringStyle style, final boolean outputTransients, final boolean outputStatics, final boolean excludeNullValues, final 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.

Parameters
<T>
the type of the object
object:T

the Object to be output

style:ToStringStyle

the style of the toString to create, may be null

outputTransients:boolean

whether to include transient fields

outputStatics:boolean

whether to include static fields

excludeNullValues:boolean

whether to exclude fields whose values are null

reflectUpToClass:Class<? super T>

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

Returns:String

the String result

Exceptions
IllegalArgumentException:
if the Object is null
Since
3.6
See Also
ToStringExclude, ToStringSummary
toStringback to summary
public static <T> String toString(final T object, final ToStringStyle style, final boolean outputTransients, final boolean outputStatics, final 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.

Parameters
<T>
the type of the object
object:T

the Object to be output

style:ToStringStyle

the style of the toString to create, may be null

outputTransients:boolean

whether to include transient fields

outputStatics:boolean

whether to include static fields

reflectUpToClass:Class<? super T>

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

Returns:String

the String result

Exceptions
IllegalArgumentException:
if the Object is null
Since
2.1
See Also
ToStringExclude, ToStringSummary
toStringback to summary
public String toString()

Overrides org.apache.commons.lang3.builder.ToStringBuilder.toString.

Gets the String built by this builder.

Returns:String

the built string

Annotations
@Override
toStringExcludeback to summary
public static String toStringExclude(final Object object, final Collection<String> excludeFieldNames)

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

Parameters
object:Object

The object to "toString".

excludeFieldNames:Collection<String>

The field names to exclude. Null excludes nothing.

Returns:String

The toString value.

toStringExcludeback to summary
public static String toStringExclude(final Object object, final String... excludeFieldNames)

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

Parameters
object:Object

The object to "toString".

excludeFieldNames:String[]

The field names to exclude

Returns:String

The toString value.

toStringIncludeback to summary
public static String toStringInclude(final Object object, final Collection<String> includeFieldNames)

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

Parameters
object:Object

The object to "toString".

includeFieldNames:Collection<String>

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

Returns:String

The toString value.

Since
3.13.0
toStringIncludeback to summary
public static String toStringInclude(final Object object, final String... includeFieldNames)

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

Parameters
object:Object

The object to "toString".

includeFieldNames:String[]

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:String

The toString value.

Since
3.13.0
validateback to summary
private void validate()

Validates that include and exclude names do not intersect.