ReflectionToStringBuilder (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.builder, class: ReflectionToStringBuilder

Package org.apache.commons.lang3.builder

# Class ReflectionToStringBuilder

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();
     }

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

  Fields
  Modifier and Type
  Field
  Description
  `protected String[]`
  `excludeFieldNames`
  Which field names to exclude from output.
  `protected String[]`
  `includeFieldNames`
  Field names that will be included in the output.

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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()`
  Gets the excludeFieldNames.
  `String[]`
  `getIncludeFieldNames()`
  Gets the includeFieldNames
  `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.
  `boolean`
  `isExcludeNullValues()`
  Gets whether or not to append fields whose values are null.
  `ReflectionToStringBuilder`
  `reflectionAppendArray(Object array)`
  Appends 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`
  `setExcludeNullValues(boolean excludeNullValues)`
  Sets whether or not to append fields whose values are null.
  `ReflectionToStringBuilder`
  `setIncludeFieldNames(String... includeFieldNamesParam)`
  Sets the field names to include.
  `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, boolean excludeNullValues, Class<? super T> reflectUpToClass)`
  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, String... excludeFieldNames)`
  Builds a String for a toString method excluding the given field names.
  `static String`
  `toStringExclude(Object object, Collection<String> excludeFieldNames)`
  Builds a String for a toString method excluding the given field names.
  `static String`
  `toStringInclude(Object object, String... includeFieldNames)`
  Builds a String for a toString method including the given field names.
  `static String`
  `toStringInclude(Object object, Collection<String> includeFieldNames)`
  Builds a String for a toString method including 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 Details

  - ### 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

  - ### includeFieldNames

    protected String[] includeFieldNames
    Field names that will be included in the output. All fields are included by default.
    Since:
      3.13.0

- ## Constructor Details

  - ### ReflectionToStringBuilder

    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`

  - ### ReflectionToStringBuilder

    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`

  - ### ReflectionToStringBuilder

    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`

  - ### ReflectionToStringBuilder

    public 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

  - ### ReflectionToStringBuilder

    public 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

- ## Method Details

  - ### 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`
    See Also:
      - `ToStringExclude`
      - `ToStringSummary`

  - ### 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`
    See Also:
      - `ToStringExclude`
      - `ToStringSummary`

  - ### 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`
    See Also:
      - `ToStringExclude`
      - `ToStringSummary`

  - ### 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 static fields
    Returns:
      the String result
    Throws:
      `IllegalArgumentException` - if the Object is `null`
    Since:
      2.1
    See Also:
      - `ToStringExclude`
      - `ToStringSummary`

  - ### toString

    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:
      `IllegalArgumentException` - if the Object is `null`
    Since:
      3.6
    See Also:
      - `ToStringExclude`
      - `ToStringSummary`

  - ### 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 `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
    See Also:
      - `ToStringExclude`
      - `ToStringSummary`

  - ### 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.

  - ### toStringInclude

    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

  - ### toStringInclude

    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

  - ### 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()
    Gets the excludeFieldNames.
    Returns:
      the excludeFieldNames.

  - ### getIncludeFieldNames

    public String[] getIncludeFieldNames()
    Gets the includeFieldNames
    Returns:
      the includeFieldNames.
    Since:
      3.13.0

  - ### 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 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.

  - ### isExcludeNullValues

    public boolean isExcludeNullValues()
    Gets whether or not to append fields whose values are null.
    Returns:
      Whether or not to append fields whose values are null.
    Since:
      3.6

  - ### reflectionAppendArray

    public ReflectionToStringBuilder reflectionAppendArray(Object array)
    Appends to the `toString` an `Object` array.
    Parameters:
      `array` - the array to add to the `toString`
    Returns:
      `this` instance.

  - ### 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`

  - ### setExcludeNullValues

    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

  - ### setIncludeFieldNames

    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

  - ### 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