Save This Page
Home » commons-lang-2.4-src » org.apache.commons » lang » builder » [javadoc | source]
org.apache.commons.lang.builder
public class: ToStringBuilder [javadoc | source]
java.lang.Object
   org.apache.commons.lang.builder.ToStringBuilder

Direct Known Subclasses:
    ReflectionToStringBuilder

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 . To append the toString from an object that is delegated to (or any other object), use #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 ToStringStyle passed into the constructor.

Constructor:
 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
 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
 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 from org.apache.commons.lang.builder.ToStringBuilder Summary:
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,   toString
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.commons.lang.builder.ToStringBuilder Detail:
 public ToStringBuilder append(boolean value) 

    Append to the toString a boolean value.

 public ToStringBuilder append(boolean[] array) 

    Append to the toString a boolean array.

 public ToStringBuilder append(byte value) 

    Append to the toString a byte value.

 public ToStringBuilder append(byte[] array) 

    Append to the toString a byte array.

 public ToStringBuilder append(char value) 

    Append to the toString a char value.

 public ToStringBuilder append(char[] array) 

    Append to the toString a char array.

 public ToStringBuilder append(double value) 

    Append to the toString a double value.

 public ToStringBuilder append(double[] array) 

    Append to the toString a double array.

 public ToStringBuilder append(float value) 

    Append to the toString a float value.

 public ToStringBuilder append(float[] array) 

    Append to the toString a float array.

 public ToStringBuilder append(int value) 

    Append to the toString an int value.

 public ToStringBuilder append(int[] array) 

    Append to the toString an int array.

 public ToStringBuilder append(long value) 

    Append to the toString a long value.

 public ToStringBuilder append(long[] array) 

    Append to the toString a long array.

 public ToStringBuilder append(Object obj) 

    Append to the toString an Object value.

 public ToStringBuilder append(Object[] array) 

    Append to the toString an Object array.

 public ToStringBuilder append(short value) 

    Append to the toString a short value.

 public ToStringBuilder append(short[] array) 

    Append to the toString a short array.

 public ToStringBuilder append(String fieldName,
    boolean value) 

    Append to the toString a boolean value.

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

    Append to the toString a boolean array.

 public ToStringBuilder append(String fieldName,
    byte value) 

    Append to the toString an byte value.

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

    Append to the toString a byte array.

 public ToStringBuilder append(String fieldName,
    char value) 

    Append to the toString a char value.

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

    Append to the toString a char array.

 public ToStringBuilder append(String fieldName,
    double value) 

    Append to the toString a double value.

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

    Append to the toString a double array.

 public ToStringBuilder append(String fieldName,
    float value) 

    Append to the toString an float value.

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

    Append to the toString a float array.

 public ToStringBuilder append(String fieldName,
    int value) 

    Append to the toString an int value.

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

    Append to the toString an int array.

 public ToStringBuilder append(String fieldName,
    long value) 

    Append to the toString a long value.

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

    Append to the toString a long array.

 public ToStringBuilder append(String fieldName,
    Object obj) 

    Append to the toString an Object value.

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

    Append to the toString an Object array.

 public ToStringBuilder append(String fieldName,
    short value) 

    Append to the toString an short value.

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

    Append to the toString a short array.

 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.

 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.

 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.

 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.

 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.

 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.

 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.

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

    Append to the toString an Object value.

 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.

 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.

 public ToStringBuilder appendAsObjectToString(Object object) 
 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.

 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.

 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.

 public Object getObject() 

    Returns the Object being output.

 public StringBuffer getStringBuffer() 

    Gets the StringBuffer being populated.

 public ToStringStyle getStyle() 

    Gets the ToStringStyle being used.

 public static String reflectionToString(Object object) 

    Forwards to ReflectionToStringBuilder.

 public static String reflectionToString(Object object,
    ToStringStyle style) 

    Forwards to ReflectionToStringBuilder.

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

    Forwards to ReflectionToStringBuilder.

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

    Forwards to ReflectionToStringBuilder.

 public static  void setDefaultStyle(ToStringStyle style) 

    Sets the default ToStringStyle to use.

 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