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 ToStringBuilder

java.lang.Object
  extended by org.apache.commons.lang.builder.ToStringBuilder
Direct Known Subclasses:
ReflectionToStringBuilder
public class ToStringBuilder
extends Object

Assists in implementing Object.toString() methods.

This class enables a good and consistent toString() to be built for any class or object. This class aims to simplify the process by:

To use this class write code as follows:

 public class Person {
   String name;
   int age;
   boolean smoker;
 
   ...
 
   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]

To add the superclass toString, use appendSuper(java.lang.String). To append the toString from an object that is delegated to (or any other object), use appendToString(java.lang.String).

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

A typical invocation for this method would look like:

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

You can also use the builder to debug 3rd party objects:

 System.out.println("An object: " + ToStringBuilder.reflectionToString(anObject));

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

Since:
1.0
Version:
$Id: ToStringBuilder.java 492354 2007-01-03 23:48:10Z scolebourne $
Author:
Stephen Colebourne, Gary Gregory, Pete Gieser

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 an 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 obj)
          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 to the toString 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 an byte value.
 ToStringBuilder append(String fieldName, byte[] array)
          Append to the toString 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 to the toString 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 to the toString 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 an float value.
 ToStringBuilder append(String fieldName, float[] array)
          Append to the toString 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 to the toString 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 to the toString a long array.
 ToStringBuilder append(String fieldName, long[] array, boolean fullDetail)
          Append to the toString a long array.
 ToStringBuilder append(String fieldName, Object obj)
          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 obj, boolean fullDetail)
          Append to the toString an Object value.
 ToStringBuilder append(String fieldName, short value)
          Append to the toString an short value.
 ToStringBuilder append(String fieldName, short[] array)
          Append to the toString a short array.
 ToStringBuilder append(String fieldName, short[] array, boolean fullDetail)
          Append to the toString a short array.
 ToStringBuilder appendAsObjectToString(Object object)
          Appends with the same format as the default Object toString() method.
 ToStringBuilder appendSuper(String superToString)
          Append the toString from the superclass.
 ToStringBuilder appendToString(String toString)
          Append the toString from another object.
static ToStringStyle getDefaultStyle()
          Gets the default ToStringStyle to use.
 Object getObject()
          Returns the Object being output.
 StringBuffer getStringBuffer()
          Gets the StringBuffer being populated.
 ToStringStyle getStyle()
          Gets the ToStringStyle being used.
static String reflectionToString(Object object)
          Forwards to ReflectionToStringBuilder.
static String reflectionToString(Object object, ToStringStyle style)
          Forwards to ReflectionToStringBuilder.
static String reflectionToString(Object object, ToStringStyle style, boolean outputTransients)
          Forwards to ReflectionToStringBuilder.
static String reflectionToString(Object object, ToStringStyle style, boolean outputTransients, Class reflectUpToClass)
          Forwards to ReflectionToStringBuilder.
static void setDefaultStyle(ToStringStyle style)
          Sets the default ToStringStyle 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
 

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
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
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
style - the style of the toString to create, may be null
buffer - the StringBuffer to populate, may be null
Method Detail

getDefaultStyle

public static ToStringStyle getDefaultStyle()

Gets the default ToStringStyle to use.

This could allow the ToStringStyle to be controlled for an entire application with one call.

This might be used to have a verbose ToStringStyle during development and a compact ToStringStyle in production.

Returns:
the default ToStringStyle

reflectionToString

public static String reflectionToString(Object object)

Forwards to ReflectionToStringBuilder.

Parameters:
object - the Object to be output
Returns:
the String result
See Also:
ReflectionToStringBuilder.toString(Object)

reflectionToString

public static String reflectionToString(Object object,
                                        ToStringStyle style)

Forwards to ReflectionToStringBuilder.

Parameters:
object - the Object to be output
style - the style of the toString to create, may be null
Returns:
the String result
See Also:
ReflectionToStringBuilder.toString(Object,ToStringStyle)

reflectionToString

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

Forwards to ReflectionToStringBuilder.

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
See Also:
ReflectionToStringBuilder.toString(Object,ToStringStyle,boolean)

reflectionToString

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

Forwards to ReflectionToStringBuilder.

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
Since:
2.0
See Also:
ReflectionToStringBuilder.toString(Object,ToStringStyle,boolean,boolean,Class)

setDefaultStyle

public static void setDefaultStyle(ToStringStyle style)

Sets the default ToStringStyle to use.

Parameters:
style - the default ToStringStyle
Throws:
IllegalArgumentException - if the style is null

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(boolean[] array)

Append to the toString a boolean array.

Parameters:
array - the array to add to the toString
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(byte[] array)

Append to the toString a byte array.

Parameters:
array - the array to add to the toString
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(char[] array)

Append to the toString a char array.

Parameters:
array - the array to add to the toString
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(double[] array)

Append to the toString a double array.

Parameters:
array - the array to add to the toString
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(float[] array)

Append to the toString a float array.

Parameters:
array - the array to add to the toString
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(int[] array)

Append to the toString an int array.

Parameters:
array - the array to add to the toString
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(long[] array)

Append to the toString a long array.

Parameters:
array - the array to add to the toString
Returns:
this

append

public ToStringBuilder append(Object obj)

Append to the toString an Object value.

Parameters:
obj - the value to add to the toString
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(short value)

Append to the toString a short value.

Parameters:
value - the value to add to the toString
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,
                              boolean value)

Append to the toString a boolean value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString 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

append

public ToStringBuilder append(String fieldName,
                              byte value)

Append to the toString an byte value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString a byte array.

Parameters:
fieldName - the field name
array - the array to add to the toString
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(String fieldName,
                              char value)

Append to the toString a char value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString a char array.

Parameters:
fieldName - the field name
array - the array to add to the toString
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(String fieldName,
                              double value)

Append to the toString a double value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString a double array.

Parameters:
fieldName - the field name
array - the array to add to the toString
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(String fieldName,
                              float value)

Append to the toString an float value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString a float array.

Parameters:
fieldName - the field name
array - the array to add to the toString
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(String fieldName,
                              int value)

Append to the toString an int value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString an int array.

Parameters:
fieldName - the field name
array - the array to add to the toString
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(String fieldName,
                              long value)

Append to the toString a long value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString a long array.

Parameters:
fieldName - the field name
array - the array to add to the toString
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(String fieldName,
                              Object obj)

Append to the toString an Object value.

Parameters:
fieldName - the field name
obj - the value to add to the toString
Returns:
this

append

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

Append to the toString an Object value.

Parameters:
fieldName - the field name
obj - the value to add to the toString
fullDetail - true for detail, false for summary info
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(String fieldName,
                              short value)

Append to the toString an short value.

Parameters:
fieldName - the field name
value - the value to add to the toString
Returns:
this

append

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

Append to the toString a short array.

Parameters:
fieldName - the field name
array - the array to add to the toString
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

appendAsObjectToString

public ToStringBuilder appendAsObjectToString(Object object)

Appends with the same format as the default Object toString() method. Appends the class name followed by System.identityHashCode(java.lang.Object).

Parameters:
object - the Object whose class name and id to output
Returns:
this
Since:
2.0

appendSuper

public ToStringBuilder appendSuper(String superToString)

Append the toString from the superclass.

This method assumes that the superclass uses the same ToStringStyle as this one.

If superToString is null, no change is made.

Parameters:
superToString - the result of super.toString()
Returns:
this
Since:
2.0

appendToString

public ToStringBuilder appendToString(String toString)

Append the toString from another object.

This method is useful where a class delegates most of the implementation of its properties to another class. You can then call toString() on the other class and pass the result into this method.

   private AnotherObject delegate;
   private String fieldInThisClass;
 
   public String toString() {
     return new ToStringBuilder(this).
       appendToString(delegate.toString()).
       append(fieldInThisClass).
       toString();
   }

This method assumes that the other object uses the same ToStringStyle as this one.

If the toString is null, no change is made.

Parameters:
toString - the result of toString() on another object
Returns:
this
Since:
2.0

getObject

public Object getObject()

Returns the Object being output.

Returns:
The object being output.
Since:
2.0

getStringBuffer

public StringBuffer getStringBuffer()

Gets the StringBuffer being populated.

Returns:
the StringBuffer being populated

getStyle

public ToStringStyle getStyle()

Gets the ToStringStyle being used.

Returns:
the ToStringStyle being used
Since:
2.0

toString

public String toString()

Returns the built toString.

This method appends the end of data indicator, and can only be called once. Use getStringBuffer() to get the current string state.

If the object is null, return the style's nullText

Overrides:
toString in class Object
Returns:
the String toString
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-2007 The Apache Software Foundation. All Rights Reserved.