Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.lang.builder
Class ReflectionToStringBuilder

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

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.

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.

Since:
  2.0
Version:
  $Id: ReflectionToStringBuilder.java 583666 2007-10-11 01:38:13Z ggregory $
Author:
  Gary Gregory, Stephen Colebourne, Pete Gieser

Constructor Summary
`ReflectionToStringBuilder(java.lang.Object object)` Constructor.
`ReflectionToStringBuilder(java.lang.Object object, ToStringStyle style)` Constructor.
`ReflectionToStringBuilder(java.lang.Object object, ToStringStyle style, java.lang.StringBuffer buffer)` Constructor.
`ReflectionToStringBuilder(java.lang.Object object, ToStringStyle style, java.lang.StringBuffer buffer, java.lang.Class reflectUpToClass, boolean outputTransients)` Deprecated. Use `ReflectionToStringBuilder(Object,ToStringStyle,StringBuffer,Class,boolean,boolean)`.
`ReflectionToStringBuilder(java.lang.Object object, ToStringStyle style, java.lang.StringBuffer buffer, java.lang.Class reflectUpToClass, boolean outputTransients, boolean outputStatics)` Constructor.

Method Summary
`protected boolean` | `accept(java.lang.reflect.Field field)` Returns whether or not to append the given `Field`.
`protected void` | `appendFieldsIn(java.lang.Class clazz)` Appends the fields and values defined by the given object of the given Class.
`java.lang.String[]` | `getExcludeFieldNames()`
`java.lang.Class` | `getUpToClass()` Gets the last super class to stop appending fields for.
`protected java.lang.Object` | `getValue(java.lang.reflect.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.
`ToStringBuilder` | `reflectionAppendArray(java.lang.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(java.lang.String[] excludeFieldNamesParam)` Sets the field names to exclude.
`void` | `setUpToClass(java.lang.Class clazz)` Sets the last super class to stop appending fields for.
`java.lang.String` | `toString()` Gets the String built by this builder.
`static java.lang.String` | `toString(java.lang.Object object)` Builds a `toString` value using the default `ToStringStyle` through reflection.
`static java.lang.String` | `toString(java.lang.Object object, ToStringStyle style)` Builds a `toString` value through reflection.
`static java.lang.String` | `toString(java.lang.Object object, ToStringStyle style, boolean outputTransients)` Builds a `toString` value through reflection.
`static java.lang.String` | `toString(java.lang.Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics)` Builds a `toString` value through reflection.
`static java.lang.String` | `toString(java.lang.Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics, java.lang.Class reflectUpToClass)` Builds a `toString` value through reflection.
`static java.lang.String` | `toString(java.lang.Object object, ToStringStyle style, boolean outputTransients, java.lang.Class reflectUpToClass)` Deprecated. Use `toString(Object,ToStringStyle,boolean,boolean,Class)`
`static java.lang.String` | `toStringExclude(java.lang.Object object, java.util.Collection excludeFieldNames)` Builds a String for a toString method excluding the given field names.
`static java.lang.String` | `toStringExclude(java.lang.Object object, java.lang.String excludeFieldName)` Builds a String for a toString method excluding the given field name.
`static java.lang.String` | `toStringExclude(java.lang.Object object, java.lang.String[] excludeFieldNames)` Builds a String for a toString method excluding the given field names.

Methods inherited from class org.apache.commons.lang.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, 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`

Constructor Detail

### ReflectionToStringBuilder

    public ReflectionToStringBuilder(java.lang.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:
  `java.lang.IllegalArgumentException` - if the Object passed in is `null`

### ReflectionToStringBuilder

    public ReflectionToStringBuilder(java.lang.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:
  `java.lang.IllegalArgumentException` - if the Object passed in is `null`

### ReflectionToStringBuilder

    public ReflectionToStringBuilder(java.lang.Object object,
                                     ToStringStyle style,
                                     java.lang.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:
  `java.lang.IllegalArgumentException` - if the Object passed in is `null`

### ReflectionToStringBuilder

    public ReflectionToStringBuilder(java.lang.Object object,
                                     ToStringStyle style,
                                     java.lang.StringBuffer buffer,
                                     java.lang.Class reflectUpToClass,
                                     boolean outputTransients)

  Deprecated. Use `ReflectionToStringBuilder(Object,ToStringStyle,StringBuffer,Class,boolean,boolean)`.

  Constructor.

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

### ReflectionToStringBuilder

    public ReflectionToStringBuilder(java.lang.Object object,
                                     ToStringStyle style,
                                     java.lang.StringBuffer buffer,
                                     java.lang.Class reflectUpToClass,
                                     boolean outputTransients,
                                     boolean outputStatics)

  Constructor.

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 java.lang.String toString(java.lang.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` - if the Object is `null`

### toString

    public static java.lang.String toString(java.lang.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` - if the Object or `ToStringStyle` is `null`

### toString

    public static java.lang.String toString(java.lang.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` - if the Object is `null`

### toString

    public static java.lang.String toString(java.lang.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:
    `java.lang.IllegalArgumentException` - if the Object is `null`
  Since:
    2.1

### toString

    public static java.lang.String toString(java.lang.Object object,
                                            ToStringStyle style,
                                            boolean outputTransients,
                                            boolean outputStatics,
                                            java.lang.Class 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.

  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` - if the Object is `null`
  Since:
    2.1

### toString

    public static java.lang.String toString(java.lang.Object object,
                                            ToStringStyle style,
                                            boolean outputTransients,
                                            java.lang.Class reflectUpToClass)

  Deprecated. Use `toString(Object,ToStringStyle,boolean,boolean,Class)`

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

  Parameters:
    `object` - the Object to be output
    `style` - the style of the `toString` to create, may be `null`
    `outputTransients` - whether to include transient fields
    `reflectUpToClass` - the superclass to reflect up to (inclusive), may be `null`
  Returns:
    the String result
  Throws:
    `java.lang.IllegalArgumentException` - if the Object is `null`
  Since:
    2.0

### toStringExclude

    public static java.lang.String toStringExclude(java.lang.Object object,
                                                   java.lang.String excludeFieldName)

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

  Parameters:
    `object` - The object to "toString".
    `excludeFieldName` - The field name to exclude
  Returns:
    The toString value.

### toStringExclude

    public static java.lang.String toStringExclude(java.lang.Object object,
                                                   java.util.Collection 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 java.lang.String toStringExclude(java.lang.Object object,
                                                   java.lang.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(java.lang.reflect.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 appened.

  Parameters:
    `field` - The Field to test.
  Returns:
    Whether or not to append the given `Field`.

### appendFieldsIn

    protected void appendFieldsIn(java.lang.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 java.lang.String[] getExcludeFieldNames()

  Returns:
    Returns the excludeFieldNames.

### getUpToClass

    public java.lang.Class getUpToClass()

  Gets the last super class to stop appending fields for.

  Returns:
    The last super class to stop appending fields for.

### getValue

    protected java.lang.Object getValue(java.lang.reflect.Field field)
                                 throws java.lang.IllegalArgumentException,
                                        java.lang.IllegalAccessException

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

  Parameters:
    `field` - The Field to query.
  Returns:
    The Object from the given Field.
  Throws:
    `java.lang.IllegalArgumentException` - see `Field.get(Object)`
    `java.lang.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 ToStringBuilder reflectionAppendArray(java.lang.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(java.lang.String[] excludeFieldNamesParam)

  Sets the field names to exclude.

  Parameters:
    `excludeFieldNamesParam` - The excludeFieldNames to excluding from toString or `null`.
  Returns:
    `this`

### setUpToClass

    public void setUpToClass(java.lang.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 java.lang.String toString()

  Gets the String built by this builder.

  Overrides:
    `toString` in class `ToStringBuilder`
  Returns:
    the built string

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.