ReflectionToStringBuilder (Apache Commons Lang 3.3 API)

java.lang.Object
- org.apache.commons.lang3.builder.ToStringBuilder
- - org.apache.commons.lang3.builder.ReflectionToStringBuilder

All Implemented Interfaces:

Builder<String>
```
public class 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 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();
 }
 
```
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

Version:

$Id: ReflectionToStringBuilder.java 1569028 2014-02-17 15:45:17Z kinow $

Field Summary

Fields
Modifier and Type Field and Description

protected String[] excludeFieldNames
Which field names to exclude from output.

Fields
Modifier and Type	Field and Description
`protected String[]`	`excludeFieldNames` Which field names to exclude from output.

Constructor Summary

Constructors
Constructor and Description
`ReflectionToStringBuilder(Object object)` Constructor.
`ReflectionToStringBuilder(Object object, ToStringStyle style)` Constructor.
`ReflectionToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer)` Constructor.
`ReflectionToStringBuilder(T object, ToStringStyle style, StringBuffer buffer, Class<? super T> reflectUpToClass, boolean outputTransients, boolean outputStatics)` Constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`protected boolean`	`accept(Field field)` 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.
`String[]`	`getExcludeFieldNames()`
`Class<?>`	`getUpToClass()` Gets the last super class to stop appending fields for.
`protected Object`	`getValue(Field field)` Calls `java.lang.reflect.Field.get(Object)`.
`boolean`	`isAppendStatics()` Gets whether or not to append static fields.
`boolean`	`isAppendTransients()` Gets whether or not to append transient fields.
`ReflectionToStringBuilder`	`reflectionAppendArray(Object array)` Append to the `toString` an `Object` array.
`void`	`setAppendStatics(boolean appendStatics)` Sets whether or not to append static fields.
`void`	`setAppendTransients(boolean appendTransients)` Sets whether or not to append transient fields.
`ReflectionToStringBuilder`	`setExcludeFieldNames(String... excludeFieldNamesParam)` Sets the field names to exclude.
`void`	`setUpToClass(Class<?> clazz)` Sets the last super class to stop appending fields for.
`String`	`toString()` Gets the String built by this builder.
`static String`	`toString(Object object)` Builds a `toString` value using the default `ToStringStyle` through reflection.
`static String`	`toString(Object object, ToStringStyle style)` Builds a `toString` value through reflection.
`static String`	`toString(Object object, ToStringStyle style, boolean outputTransients)` Builds a `toString` value through reflection.
`static String`	`toString(Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics)` Builds a `toString` value through reflection.
`static <T> String`	`toString(T object, ToStringStyle style, boolean outputTransients, boolean outputStatics, Class<? super T> reflectUpToClass)` Builds a `toString` value through reflection.
`static String`	`toStringExclude(Object object, Collection<String> excludeFieldNames)` Builds a String for a toString method excluding the given field names.
`static String`	`toStringExclude(Object object, String... excludeFieldNames)` Builds a String for a toString method excluding the given field names.

Methods inherited from class org.apache.commons.lang3.builder.ToStringBuilder
append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, append, appendAsObjectToString, appendSuper, appendToString, build, getDefaultStyle, getObject, getStringBuffer, getStyle, reflectionToString, reflectionToString, reflectionToString, reflectionToString, setDefaultStyle

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - excludeFieldNames
```
protected String[] excludeFieldNames
```
    Which field names to exclude from output. Intended for fields like "password".
    
    Since:
    
    3.0 this is protected instead of private
- Constructor Detail
  - ReflectionToStringBuilder
```
public ReflectionToStringBuilder(Object object)
```
    Constructor.
    
    This constructor outputs using the default style set with setDefaultStyle.
    
    Parameters:
    object - the Object to build a toString for, must not be null
    
    Throws:
    
    IllegalArgumentException - if the Object passed in is null
  - ReflectionToStringBuilder
```
public ReflectionToStringBuilder(Object object,
                         ToStringStyle style)
```
    Constructor.
    
    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
    
    Throws:
    
    IllegalArgumentException - if the Object passed in is null
  - ReflectionToStringBuilder
```
public ReflectionToStringBuilder(Object object,
                         ToStringStyle style,
                         StringBuffer buffer)
```
    Constructor.
    
    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
    
    Throws:
    
    IllegalArgumentException - if the Object passed in is null
  - ReflectionToStringBuilder
```
public ReflectionToStringBuilder(T object,
                         ToStringStyle style,
                         StringBuffer buffer,
                         Class<? super T> reflectUpToClass,
                         boolean outputTransients,
                         boolean outputStatics)
```
    Constructor.
    
    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
- Method Detail
  - toString
```
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:
    
    IllegalArgumentException - if the Object is null
  - toString
```
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:
    
    IllegalArgumentException - if the Object or ToStringStyle is null
  - toString
```
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:
    
    IllegalArgumentException - if the Object is null
  - toString
```
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 transient fields
    
    Returns:
    the String result
    
    Throws:
    
    IllegalArgumentException - if the Object is null
    Since:
    
    2.1
  - toString
```
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 java.lang.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:
    
    IllegalArgumentException - if the Object is null
    Since:
    
    2.1
  - toStringExclude
```
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.
  - toStringExclude
```
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.
  - accept
```
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.
  - appendFieldsIn
```
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
  - getExcludeFieldNames
```
public String[] getExcludeFieldNames()
```
    Returns:
    Returns the excludeFieldNames.
  - getUpToClass
```
public Class<?> getUpToClass()
```
    Gets the last super class to stop appending fields for.
    
    Returns:
    The last super class to stop appending fields for.
  - getValue
```
protected Object getValue(Field field)
                   throws IllegalArgumentException,
                          IllegalAccessException
```
    Calls java.lang.reflect.Field.get(Object).
    
    Parameters:
    field - The Field to query.
    
    Returns:
    The Object from the given Field.
    
    Throws:
    
    IllegalArgumentException - see Field.get(Object)
    
    IllegalAccessException - see Field.get(Object)
    See Also:
    Field.get(Object)
  - isAppendStatics
```
public boolean isAppendStatics()
```
    Gets whether or not to append static fields.
    
    Returns:
    Whether or not to append static fields.
    Since:
    
    2.1
  - isAppendTransients
```
public boolean isAppendTransients()
```
    Gets whether or not to append transient fields.
    
    Returns:
    Whether or not to append transient fields.
  - reflectionAppendArray
```
public ReflectionToStringBuilder reflectionAppendArray(Object array)
```
    Append to the toString an Object array.
    
    Parameters:
    array - the array to add to the toString
    
    Returns:
    this
  - setAppendStatics
```
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
  - setAppendTransients
```
public void setAppendTransients(boolean appendTransients)
```
    Sets whether or not to append transient fields.
    
    Parameters:
    appendTransients - Whether or not to append transient fields.
  - setExcludeFieldNames
```
public ReflectionToStringBuilder setExcludeFieldNames(String... excludeFieldNamesParam)
```
    Sets the field names to exclude.
    
    Parameters:
    excludeFieldNamesParam - The excludeFieldNames to excluding from toString or null.
    
    Returns:
    this
  - setUpToClass
```
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.
  - toString
```
public String toString()
```
    Gets the String built by this builder.
    
    Overrides:
    
    toString in class ToStringBuilder
    
    Returns:
    the built string

Class ReflectionToStringBuilder

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.apache.commons.lang3.builder.ToStringBuilder

Methods inherited from class java.lang.Object

Field Detail

excludeFieldNames

Constructor Detail

ReflectionToStringBuilder

ReflectionToStringBuilder

ReflectionToStringBuilder

ReflectionToStringBuilder

Method Detail

toString

toString

toString

toString

toString

toStringExclude

toStringExclude

accept

appendFieldsIn

getExcludeFieldNames

getUpToClass

getValue

isAppendStatics

isAppendTransients

reflectionAppendArray

setAppendStatics

setAppendTransients

setExcludeFieldNames

setUpToClass

toString