org.apache.commons.lang.builder

Class ToStringBuilder

public class ToStringBuilder extends Object

Assists in implementing {@link 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 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]

To add the superclass toString, use {@link #appendSuper}. To append the toString from an object that is delegated to (or any other object), use {@link #appendToString}.

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 {@link ToStringStyle} passed into the constructor.

Since: 1.0

Version: $Id: ToStringBuilder.java 161243 2005-04-14 04:30:28Z ggregory $

Author: Stephen Colebourne Gary Gregory Pete Gieser

Constructor Summary
ToStringBuilder(Object object)

Constructor for ToStringBuilder.

This constructor outputs using the default style set with setDefaultStyle.

ToStringBuilder(Object object, ToStringStyle style)

Constructor for ToStringBuilder specifying the output style.

If the style is null, the default style is used.

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.

Method Summary
ToStringBuilderappend(boolean value)

Append to the toString a boolean value.

ToStringBuilderappend(boolean[] array)

Append to the toString a boolean array.

ToStringBuilderappend(byte value)

Append to the toString a byte value.

ToStringBuilderappend(byte[] array)

Append to the toString a byte array.

ToStringBuilderappend(char value)

Append to the toString a char value.

ToStringBuilderappend(char[] array)

Append to the toString a char array.

ToStringBuilderappend(double value)

Append to the toString a double value.

ToStringBuilderappend(double[] array)

Append to the toString a double array.

ToStringBuilderappend(float value)

Append to the toString a float value.

ToStringBuilderappend(float[] array)

Append to the toString a float array.

ToStringBuilderappend(int value)

Append to the toString an int value.

ToStringBuilderappend(int[] array)

Append to the toString an int array.

ToStringBuilderappend(long value)

Append to the toString a long value.

ToStringBuilderappend(long[] array)

Append to the toString a long array.

ToStringBuilderappend(Object object)

Append to the toString an Object value.

ToStringBuilderappend(Object[] array)

Append to the toString an Object array.

ToStringBuilderappend(short value)

Append to the toString a short value.

ToStringBuilderappend(short[] array)

Append to the toString a short array.

ToStringBuilderappend(String fieldName, boolean value)

Append to the toString a boolean value.

ToStringBuilderappend(String fieldName, boolean[] array)

Append to the toString a boolean array.

ToStringBuilderappend(String fieldName, boolean[] array, boolean fullDetail)

Append to the toString a boolean array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, byte value)

Append to the toString an byte value.

ToStringBuilderappend(String fieldName, byte[] array)

Append to the toString a byte array.

ToStringBuilderappend(String fieldName, byte[] array, boolean fullDetail)

Append to the toString a byte array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, char value)

Append to the toString a char value.

ToStringBuilderappend(String fieldName, char[] array)

Append to the toString a char array.

ToStringBuilderappend(String fieldName, char[] array, boolean fullDetail)

Append to the toString a char array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, double value)

Append to the toString a double value.

ToStringBuilderappend(String fieldName, double[] array)

Append to the toString a double array.

ToStringBuilderappend(String fieldName, double[] array, boolean fullDetail)

Append to the toString a double array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, float value)

Append to the toString an float value.

ToStringBuilderappend(String fieldName, float[] array)

Append to the toString a float array.

ToStringBuilderappend(String fieldName, float[] array, boolean fullDetail)

Append to the toString a float array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, int value)

Append to the toString an int value.

ToStringBuilderappend(String fieldName, int[] array)

Append to the toString an int array.

ToStringBuilderappend(String fieldName, int[] array, boolean fullDetail)

Append to the toString an int array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, long value)

Append to the toString a long value.

ToStringBuilderappend(String fieldName, long[] array)

Append to the toString a long array.

ToStringBuilderappend(String fieldName, long[] array, boolean fullDetail)

Append to the toString a long array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, Object object)

Append to the toString an Object value.

ToStringBuilderappend(String fieldName, Object object, boolean fullDetail)

Append to the toString an Object value.

ToStringBuilderappend(String fieldName, Object[] array)

Append to the toString an Object array.

ToStringBuilderappend(String fieldName, Object[] array, boolean fullDetail)

Append to the toString an Object array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappend(String fieldName, short value)

Append to the toString an short value.

ToStringBuilderappend(String fieldName, short[] array)

Append to the toString a short array.

ToStringBuilderappend(String fieldName, short[] array, boolean fullDetail)

Append to the toString a short array.

A boolean parameter controls the level of detail to show.

ToStringBuilderappendAsObjectToString(Object object)

Appends with the same format as the default Object toString() method.

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

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

static ToStringStylegetDefaultStyle()

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.

ObjectgetObject()

Returns the Object being output.

StringBuffergetStringBuffer()

Gets the StringBuffer being populated.

ToStringStylegetStyle()

Gets the ToStringStyle being used.

static StringreflectionToString(Object object)

Forwards to ReflectionToStringBuilder.

static StringreflectionToString(Object object, ToStringStyle style)

Forwards to ReflectionToStringBuilder.

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

Forwards to ReflectionToStringBuilder.

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

Forwards to ReflectionToStringBuilder.

static voidsetDefaultStyle(ToStringStyle style)

Sets the default ToStringStyle to use.

StringtoString()

Returns the built toString.

This method appends the end of data indicator, and can only be called once.

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

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 object)

Append to the toString an Object value.

Parameters: object 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 object)

Append to the toString an Object value.

Parameters: fieldName the field name object the value to add to the toString

Returns: this

append

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

Append to the toString an Object value.

Parameters: fieldName the field name object 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 {@link 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

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

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

reflectionToString

public static String reflectionToString(Object object)

Forwards to ReflectionToStringBuilder.

See Also: toString

reflectionToString

public static String reflectionToString(Object object, ToStringStyle style)

Forwards to ReflectionToStringBuilder.

See Also: toString

reflectionToString

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

Forwards to ReflectionToStringBuilder.

See Also: ReflectionToStringBuilder

reflectionToString

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

Forwards to ReflectionToStringBuilder.

Since: 2.0

See Also: ReflectionToStringBuilder

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

toString

public String toString()

Returns the built toString.

This method appends the end of data indicator, and can only be called once. Use {@link #getStringBuffer} to get the current string state.

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

Returns: the String toString

Copyright © 2001-2005 - Apache Software Foundation