org.apache.commons.lang.builder
Class ToStringBuilder

java.lang.Object
  |
  +--org.apache.commons.lang.builder.ToStringBuilder

public class ToStringBuilder

extends Object

ToString generation routine.

This class enables a good toString to be built for any class. This class aims to simplify the process by:

• allowing field names
• handling all types consistently
• handling nulls consistently
• outputting arrays and multi-dimensional arrays
• enabling the detail level to be controlled for objects and collections

To use this class write code as follows:

 public class Person {
   String name;
   int age;
   boolean isSmoker;
 
   ...
 
   public String toString() {
     return new ToStringBuilder(this).
       append(name, "name").
       append(age, "age").
       append(smoker, "smoker").
       toString();
   }
 }
 

This will produce a toString of the format: Person@7f54[name=Stephen,age=29,smoker=false]

Alternatively, there is a method that uses reflection to determine the fields to test. Because these fields are usually private, the method, reflectionToString, uses Field.setAccessible to change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions are set. It is also slower than testing explicitly.

A typical invocation for this method would look like:

 public String toString() {
   return ToStringBuilder.reflectionToString(this);
 }
 

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

Version:

$Id: ToStringBuilder.java,v 1.6 2002/10/01 20:03:04 stevencaswell Exp $

Author:

Stephen Colebourne

Field Summary

private StringBuffer	buffer Current toString buffer
private static ToStringStyle	defaultStyle The default style of output to use
private Object	object The object being output
private ToStringStyle	style The style of output to use

Constructor Summary

ToStringBuilder(Object object)
Constructor for ToStringBuilder.

ToStringBuilder(Object object, ToStringStyle style)
Constructor for ToStringBuilder specifying the output style.

ToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer)
Constructor for ToStringBuilder.

Method Summary

ToStringBuilder	append(boolean value) Append to the toString a boolean value.
ToStringBuilder	append(boolean[] array) Append to the toString a boolean array.
ToStringBuilder	append(byte value) Append to the toString a byte value.
ToStringBuilder	append(byte[] array) Append to the toString a byte array.
ToStringBuilder	append(char value) Append to the toString a char value.
ToStringBuilder	append(char[] array) Append to the toString a char array.
ToStringBuilder	append(double value) Append to the toString a double value.
ToStringBuilder	append(double[] array) Append to the toString a double array.
ToStringBuilder	append(float value) Append to the toString a float value.
ToStringBuilder	append(float[] array) Append to the toString a float array.
ToStringBuilder	append(int value) Append to the toString an int value.
ToStringBuilder	append(int[] array) Append to the toString a int array.
ToStringBuilder	append(long value) Append to the toString a long value.
ToStringBuilder	append(long[] array) Append to the toString a long array.
ToStringBuilder	append(Object object) Append to the toString an Object value.
ToStringBuilder	append(Object[] array) Append to the toString an Object array.
ToStringBuilder	append(short value) Append to the toString a short value.
ToStringBuilder	append(short[] array) Append to the toString a short array.
ToStringBuilder	append(String fieldName, boolean value) Append to the toString a boolean value.
ToStringBuilder	append(String fieldName, boolean[] array) Append a hashCode for a boolean array.
ToStringBuilder	append(String fieldName, boolean[] array, boolean fullDetail) Append to the toString a boolean array.
ToStringBuilder	append(String fieldName, byte value) Append to the toString a byte value.
ToStringBuilder	append(String fieldName, byte[] array) Append a hashCode for a byte array.
ToStringBuilder	append(String fieldName, byte[] array, boolean fullDetail) Append to the toString a byte array.
ToStringBuilder	append(String fieldName, char value) Append to the toString a char value.
ToStringBuilder	append(String fieldName, char[] array) Append a hashCode for a char array.
ToStringBuilder	append(String fieldName, char[] array, boolean fullDetail) Append to the toString a char array.
ToStringBuilder	append(String fieldName, double value) Append to the toString a double value.
ToStringBuilder	append(String fieldName, double[] array) Append a hashCode for a double array.
ToStringBuilder	append(String fieldName, double[] array, boolean fullDetail) Append to the toString a double array.
ToStringBuilder	append(String fieldName, float value) Append to the toString a float value.
ToStringBuilder	append(String fieldName, float[] array) Append a hashCode for a float array.
ToStringBuilder	append(String fieldName, float[] array, boolean fullDetail) Append to the toString a float array.
ToStringBuilder	append(String fieldName, int value) Append to the toString an int value.
ToStringBuilder	append(String fieldName, int[] array) Append a hashCode for an int array.
ToStringBuilder	append(String fieldName, int[] array, boolean fullDetail) Append to the toString an int array.
ToStringBuilder	append(String fieldName, long value) Append to the toString a long value.
ToStringBuilder	append(String fieldName, long[] array) Append a hashCode for a long array.
ToStringBuilder	append(String fieldName, long[] array, boolean fullDetail) Append to the toString a long array.
ToStringBuilder	append(String fieldName, Object object) Append to the toString an Object value.
ToStringBuilder	append(String fieldName, Object[] array) Append to the toString an Object array.
ToStringBuilder	append(String fieldName, Object[] array, boolean fullDetail) Append to the toString an Object array.
ToStringBuilder	append(String fieldName, Object object, boolean fullDetail) Append to the toString an Object value.
ToStringBuilder	append(String fieldName, short value) Append to the toString a short value.
ToStringBuilder	append(String fieldName, short[] array) Append a hashCode for a short array.
ToStringBuilder	append(String fieldName, short[] array, boolean fullDetail) Append to the toString a short array.
static ToStringStyle	getDefaultStyle() Gets the default style to use.
StringBuffer	getStringBuffer() Gets the buffer being populated
static String	reflectionToString(Object object) This method uses reflection to build a suitable toString using the default style.
static String	reflectionToString(Object object, ToStringStyle style) This method uses reflection to build a suitable toString.
static String	reflectionToString(Object object, ToStringStyle style, boolean outputTransients) This method uses reflection to build a suitable toString.
static void	setDefaultStyle(ToStringStyle style) Sets the default style to use.
String	toString() Returns the built toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

defaultStyle

private static ToStringStyle defaultStyle

The default style of output to use

buffer

private final StringBuffer buffer

Current toString buffer

style

private final ToStringStyle style

The style of output to use

object

private final Object object

The object being output

Constructor Detail

ToStringBuilder

public ToStringBuilder(Object object)

Constructor for ToStringBuilder. 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

ToStringBuilder

public ToStringBuilder(Object object,
                       ToStringStyle style)

Constructor for ToStringBuilder specifying the output style.

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

ToStringBuilder

public ToStringBuilder(Object object,
                       ToStringStyle style,
                       StringBuffer buffer)

Constructor for ToStringBuilder.

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, must not be null

style - the style of the toString to create, may be null

buffer - the string buffer to populate, may be null

Throws:

IllegalArgumentException - if the object passed in is null

Method Detail

getDefaultStyle

public static ToStringStyle getDefaultStyle()

Gets the default style to use.

This could allow the toString style to be controlled for an entire application with one call. This might be used to have a verbose toString during development and a compact toString in production.

Returns:

the default toString style

setDefaultStyle

public static void setDefaultStyle(ToStringStyle style)

Sets the default style to use.

Parameters:

style - the default toString style

Throws:

IllegalArgumentException - if the style is null

reflectionToString

public static String reflectionToString(Object object)

This method uses reflection to build a suitable toString using the default style.

It uses Field.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manger, if the permissions are not set up. It is also not as efficient as testing explicitly. Transient members will be not be included, as they are likely derived. Static fields will be not be included. fields, and not part of the value of the object.

Parameters:

object - the object to be output

Returns:

the String result

Throws:

IllegalArgumentException - if the object is null

reflectionToString

public static String reflectionToString(Object object,
                                        ToStringStyle style)

This method uses reflection to build a suitable toString.

It uses Field.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manger, if the permissions are not set up. It is also not as efficient as testing explicitly. Transient members will be not be included, as they are likely derived. Static fields will be not be included. fields, and not part of the value of the object.

If the style is null, the default style 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 style is null

reflectionToString

public static String reflectionToString(Object object,
                                        ToStringStyle style,
                                        boolean outputTransients)

This method uses reflection to build a suitable toString.

It uses Field.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manger, if the permissions are not set up. It is also not as efficient as testing explicitly. If the outputTransients parameter is set to 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 tested.

If the style is null, the default style 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

append

public ToStringBuilder append(Object object)

Append to the toString an Object value.

Parameters:

object - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              Object object)

Append to the toString an Object value.

Parameters:

object - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              Object object,
                              boolean fullDetail)

Append to the toString an Object value.

Parameters:

object - the value to add to the toString

fieldName - the field name

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(long value)

Append to the toString a long value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              long value)

Append to the toString a long value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(int value)

Append to the toString an int value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              int value)

Append to the toString an int value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(short value)

Append to the toString a short value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              short value)

Append to the toString a short value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(char value)

Append to the toString a char value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              char value)

Append to the toString a char value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(byte value)

Append to the toString a byte value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              byte value)

Append to the toString a byte value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(double value)

Append to the toString a double value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              double value)

Append to the toString a double value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(float value)

Append to the toString a float value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              float value)

Append to the toString a float value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(boolean value)

Append to the toString a boolean value.

Parameters:

value - the value to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              boolean value)

Append to the toString a boolean value.

Parameters:

value - the value to add to the toString

fieldName - the field name

Returns:

this

append

public ToStringBuilder append(Object[] array)

Append to the toString an Object array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              Object[] array)

Append to the toString an Object array.

Parameters:

fieldName - the field name

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              Object[] array,
                              boolean fullDetail)

Append to the toString an Object array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(long[] array)

Append to the toString a long array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              long[] array)

Append a hashCode for a long array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              long[] array,
                              boolean fullDetail)

Append to the toString a long array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(int[] array)

Append to the toString a int array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              int[] array)

Append a hashCode for an int array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              int[] array,
                              boolean fullDetail)

Append to the toString an int array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(short[] array)

Append to the toString a short array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              short[] array)

Append a hashCode for a short array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              short[] array,
                              boolean fullDetail)

Append to the toString a short array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(char[] array)

Append to the toString a char array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              char[] array)

Append a hashCode for a char array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              char[] array,
                              boolean fullDetail)

Append to the toString a char array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(byte[] array)

Append to the toString a byte array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              byte[] array)

Append a hashCode for a byte array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              byte[] array,
                              boolean fullDetail)

Append to the toString a byte array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(double[] array)

Append to the toString a double array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              double[] array)

Append a hashCode for a double array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              double[] array,
                              boolean fullDetail)

Append to the toString a double array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(float[] array)

Append to the toString a float array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              float[] array)

Append a hashCode for a float array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              float[] array,
                              boolean fullDetail)

Append to the toString a float array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

append

public ToStringBuilder append(boolean[] array)

Append to the toString a boolean array.

Parameters:

array - the array to add to the toString

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              boolean[] array)

Append a hashCode for a boolean array.

Parameters:

fieldName - the field name

array - the array to add to the hashCode

Returns:

this

append

public ToStringBuilder append(String fieldName,
                              boolean[] array,
                              boolean fullDetail)

Append to the toString a boolean array.

A boolean parameter controls the level of detail to show. Setting true will output the array in full. Setting false will output a summary, typically the size of the array.

Parameters:

fieldName - the field name

array - the array to add to the toString

fullDetail - true for detail, false for summary info

Returns:

this

getStringBuffer

public StringBuffer getStringBuffer()

Gets the buffer being populated

Returns:

the StringBuffer being populated

toString

public String toString()

Returns the built toString

Overrides:

toString in class Object

Returns:

the String toString