Class ToStringBuilder
- Direct Known Subclasses:
ReflectionToStringBuilder
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:
- 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
- handling class hierarchies
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
-
Constructor Summary
ConstructorsConstructorDescriptionToStringBuilder(Object object) Constructs a builder for the specified object using the default output style.ToStringBuilder(Object object, ToStringStyle style) Constructs a builder for the specified object using the defined output style.ToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer) Constructs a builder for the specified object. -
Method Summary
Modifier and TypeMethodDescriptionappend(boolean value) Append to thetoStringabooleanvalue.append(boolean[] array) Append to thetoStringabooleanarray.append(byte value) Append to thetoStringabytevalue.append(byte[] array) Append to thetoStringabytearray.append(char value) Append to thetoStringacharvalue.append(char[] array) Append to thetoStringachararray.append(double value) Append to thetoStringadoublevalue.append(double[] array) Append to thetoStringadoublearray.append(float value) Append to thetoStringafloatvalue.append(float[] array) Append to thetoStringafloatarray.append(int value) Append to thetoStringanintvalue.append(int[] array) Append to thetoStringanintarray.append(long value) Append to thetoStringalongvalue.append(long[] array) Append to thetoStringalongarray.append(short value) Append to thetoStringashortvalue.append(short[] array) Append to thetoStringashortarray.Append to thetoStringanObjectvalue.Append to thetoStringanObjectarray.Append to thetoStringabooleanvalue.Append to thetoStringabooleanarray.Append to thetoStringabooleanarray.Append to thetoStringanbytevalue.Append to thetoStringabytearray.Append to thetoStringabytearray.Append to thetoStringacharvalue.Append to thetoStringachararray.Append to thetoStringachararray.Append to thetoStringadoublevalue.Append to thetoStringadoublearray.Append to thetoStringadoublearray.Append to thetoStringanfloatvalue.Append to thetoStringafloatarray.Append to thetoStringafloatarray.Append to thetoStringanintvalue.Append to thetoStringanintarray.Append to thetoStringanintarray.Append to thetoStringalongvalue.Append to thetoStringalongarray.Append to thetoStringalongarray.Append to thetoStringanshortvalue.Append to thetoStringashortarray.Append to thetoStringashortarray.Append to thetoStringanObjectvalue.Append to thetoStringanObjectarray.Append to thetoStringanObjectarray.Append to thetoStringanObjectvalue.appendAsObjectToString(Object srcObject) Appends with the same format as the defaultObject toString()method.appendSuper(String superToString) Append thetoStringfrom the superclass.appendToString(String toString) Append thetoStringfrom another object.build()Returns the String that was build as an object representation.static ToStringStyleGets the defaultToStringStyleto use.Returns theObjectbeing output.Gets theStringBufferbeing populated.getStyle()Gets theToStringStylebeing used.static StringreflectionToString(Object object) UsesReflectionToStringBuilderto generate atoStringfor the specified object.static StringreflectionToString(Object object, ToStringStyle style) UsesReflectionToStringBuilderto generate atoStringfor the specified object.static StringreflectionToString(Object object, ToStringStyle style, boolean outputTransients) UsesReflectionToStringBuilderto generate atoStringfor the specified object.static <T> StringreflectionToString(T object, ToStringStyle style, boolean outputTransients, Class<? super T> reflectUpToClass) UsesReflectionToStringBuilderto generate atoStringfor the specified object.static voidsetDefaultStyle(ToStringStyle style) Sets the defaultToStringStyleto use.toString()Returns the builttoString.
-
Constructor Details
-
ToStringBuilder
Constructs a builder for the specified object using the default output style.This default style is obtained from
getDefaultStyle().- Parameters:
object- the Object to build atoStringfor, not recommended to be null
-
ToStringBuilder
Constructs a builder for the specified object using the defined output style.If the style is
null, the default style is used.- Parameters:
object- the Object to build atoStringfor, not recommended to be nullstyle- the style of thetoStringto create, null uses the default style
-
ToStringBuilder
Constructs a builder for the specified object.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 atoStringfor, not recommended to be nullstyle- the style of thetoStringto create, null uses the default stylebuffer- theStringBufferto populate, may be null
-
-
Method Details
-
getDefaultStyle
Gets the defaultToStringStyleto use.This method gets a singleton default value, typically for the whole JVM. Changing this default should generally only be done during application startup. It is recommended to pass a
ToStringStyleto the constructor instead of using this global default.This method can be used from multiple threads. Internally, a
volatilevariable is used to provide the guarantee that the latest value set usingsetDefaultStyle(org.apache.commons.lang3.builder.ToStringStyle)is the value returned. It is strongly recommended that the default style is only changed during application startup.One reason for changing the default could be to have a verbose style during development and a compact style in production.
- Returns:
- the default
ToStringStyle, never null
-
reflectionToString
UsesReflectionToStringBuilderto generate atoStringfor the specified object.- Parameters:
object- the Object to be output- Returns:
- the String result
- See Also:
-
reflectionToString
UsesReflectionToStringBuilderto generate atoStringfor the specified object.- Parameters:
object- the Object to be outputstyle- the style of thetoStringto create, may benull- Returns:
- the String result
- See Also:
-
reflectionToString
public static String reflectionToString(Object object, ToStringStyle style, boolean outputTransients) UsesReflectionToStringBuilderto generate atoStringfor the specified object.- Parameters:
object- the Object to be outputstyle- the style of thetoStringto create, may benulloutputTransients- whether to include transient fields- Returns:
- the String result
- See Also:
-
reflectionToString
public static <T> String reflectionToString(T object, ToStringStyle style, boolean outputTransients, Class<? super T> reflectUpToClass) UsesReflectionToStringBuilderto generate atoStringfor the specified object.- Type Parameters:
T- the type of the object- Parameters:
object- the Object to be outputstyle- the style of thetoStringto create, may benulloutputTransients- whether to include transient fieldsreflectUpToClass- the superclass to reflect up to (inclusive), may benull- Returns:
- the String result
- Since:
- 2.0
- See Also:
-
setDefaultStyle
Sets the defaultToStringStyleto use.This method sets a singleton default value, typically for the whole JVM. Changing this default should generally only be done during application startup. It is recommended to pass a
ToStringStyleto the constructor instead of changing this global default.This method is not intended for use from multiple threads. Internally, a
volatilevariable is used to provide the guarantee that the latest value set is the value returned fromgetDefaultStyle().- Parameters:
style- the defaultToStringStyle- Throws:
NullPointerException- if the style isnull
-
append
Append to thetoStringabooleanvalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringabooleanarray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringabytevalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringabytearray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringacharvalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringachararray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringadoublevalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringadoublearray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringafloatvalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringafloatarray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanintvalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanintarray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringalongvalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringalongarray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanObjectvalue.- Parameters:
obj- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanObjectarray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringashortvalue.- Parameters:
value- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringashortarray.- Parameters:
array- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringabooleanvalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringabooleanarray.- Parameters:
fieldName- the field namearray- the array to add to thehashCode- Returns:
thisinstance.
-
append
Append to thetoStringabooleanarray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringanbytevalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringabytearray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringabytearray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringacharvalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringachararray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringachararray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringadoublevalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringadoublearray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringadoublearray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringanfloatvalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringafloatarray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringafloatarray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringanintvalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanintarray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanintarray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringalongvalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringalongarray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringalongarray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringanObjectvalue.- Parameters:
fieldName- the field nameobj- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanObjectvalue.- Parameters:
fieldName- the field nameobj- the value to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringanObjectarray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringanObjectarray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
append
Append to thetoStringanshortvalue.- Parameters:
fieldName- the field namevalue- the value to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringashortarray.- Parameters:
fieldName- the field namearray- the array to add to thetoString- Returns:
thisinstance.
-
append
Append to thetoStringashortarray.A boolean parameter controls the level of detail to show. Setting
truewill output the array in full. Settingfalsewill output a summary, typically the size of the array.- Parameters:
fieldName- the field namearray- the array to add to thetoStringfullDetail-truefor detail,falsefor summary info- Returns:
thisinstance.
-
appendAsObjectToString
Appends with the same format as the defaultObject toString()method. Appends the class name followed bySystem.identityHashCode(Object).- Parameters:
srcObject- theObjectwhose class name and id to output- Returns:
thisinstance.- Throws:
NullPointerException- ifsrcObjectisnull- Since:
- 2.0
-
appendSuper
Append thetoStringfrom the superclass.This method assumes that the superclass uses the same
ToStringStyleas this one.If
superToStringisnull, no change is made.- Parameters:
superToString- the result ofsuper.toString()- Returns:
thisinstance.- Since:
- 2.0
-
appendToString
Append thetoStringfrom 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
ToStringStyleas this one.If the
toStringisnull, no change is made.- Parameters:
toString- the result oftoString()on another object- Returns:
thisinstance.- Since:
- 2.0
-
build
Returns the String that was build as an object representation. The default implementation utilizes thetoString()implementation. -
getObject
Returns theObjectbeing output.- Returns:
- The object being output.
- Since:
- 2.0
-
getStringBuffer
Gets theStringBufferbeing populated.- Returns:
- the
StringBufferbeing populated
-
getStyle
Gets theToStringStylebeing used.- Returns:
- the
ToStringStylebeing used - Since:
- 2.0
-
toString
Returns the builttoString.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'snullText
-