org.apache.commons.lang.builder

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

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

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

Since: 2.0

Version: $Id: ReflectionToStringBuilder.java 501986 2007-01-31 20:54:26Z bayard $

Author: Gary Gregory Stephen Colebourne Pete Gieser

Constructor Summary
ReflectionToStringBuilder(Object object)

Constructor.

ReflectionToStringBuilder(Object object, ToStringStyle style)

Constructor.

ReflectionToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer)

Constructor.

ReflectionToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer, Class reflectUpToClass, boolean outputTransients)
Constructor.
ReflectionToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer, Class reflectUpToClass, boolean outputTransients, boolean outputStatics)
Constructor.
Method Summary
protected booleanaccept(Field field)
Returns whether or not to append the given Field.
protected voidappendFieldsIn(Class clazz)

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

String[]getExcludeFieldNames()
ClassgetUpToClass()

Gets the last super class to stop appending fields for.

protected ObjectgetValue(Field field)

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

booleanisAppendStatics()

Gets whether or not to append static fields.

booleanisAppendTransients()

Gets whether or not to append transient fields.

ToStringBuilderreflectionAppendArray(Object array)

Append to the toString an Object array.

voidsetAppendStatics(boolean appendStatics)

Sets whether or not to append static fields.

voidsetAppendTransients(boolean appendTransients)

Sets whether or not to append transient fields.

ReflectionToStringBuildersetExcludeFieldNames(String[] excludeFieldNamesParam)
Sets the field names to exclude.
voidsetUpToClass(Class clazz)

Sets the last super class to stop appending fields for.

static StringtoString(Object object)

Builds a toString value using the default ToStringStyle through reflection.

static StringtoString(Object object, ToStringStyle style)

Builds a toString value through reflection.

static StringtoString(Object object, ToStringStyle style, boolean outputTransients)

Builds a toString value through reflection.

static StringtoString(Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics)

Builds a toString value through reflection.

static StringtoString(Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics, Class reflectUpToClass)

Builds a toString value through reflection.

static StringtoString(Object object, ToStringStyle style, boolean outputTransients, Class reflectUpToClass)

Builds a toString value through reflection.

StringtoString()

Gets the String built by this builder.

static StringtoStringExclude(Object object, String excludeFieldName)
Builds a String for a toString method excluding the given field name.
static StringtoStringExclude(Object object, Collection excludeFieldNames)
Builds a String for a toString method excluding the given field names.
static StringtoStringExclude(Object object, String[] excludeFieldNames)
Builds a String for a toString method excluding the given field names.

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(Object object, ToStringStyle style, StringBuffer buffer, Class reflectUpToClass, boolean outputTransients)

Deprecated: Use ReflectionToStringBuilder.

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(Object object, ToStringStyle style, StringBuffer buffer, 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

accept

protected boolean accept(Field field)
Returns whether or not to append the given Field.

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)

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

Parameters: field The Field to query.

Returns: The Object from the given Field.

Throws: IllegalArgumentException see java.lang.reflect.Field#get(Object) IllegalAccessException see java.lang.reflect.Field#get(Object)

See Also: java.lang.reflect.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(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 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 String toString(Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics, 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: IllegalArgumentException if the Object is null

Since: 2.1

toString

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

Deprecated: Use ReflectionToStringBuilder

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: IllegalArgumentException if the Object is null

Since: 2.0

toString

public String toString()

Gets the String built by this builder.

Returns: the built string

toStringExclude

public static String toStringExclude(Object object, 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 String toStringExclude(Object object, 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 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.

Copyright © 2001-2005 - Apache Software Foundation