Class ReflectionToStringBuilder
Assists in implementing Object.toString()
methods using reflection.
This class uses reflection to determine the fields to append. Because these fields are usually private, the class
uses AccessibleObject.setAccessible(java.lang.reflect.AccessibleObject[], boolean)
to
change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions are
set up correctly.
Using reflection to access (private) fields circumvents any synchronization protection guarding access to these fields. If a toString method cannot safely read a field, you should exclude it from the toString method, or use synchronization consistent with the class' lock management around the invocation of the method. Take special care to exclude non-thread-safe collection classes, because these classes may throw ConcurrentModificationException if modified while the toString method is executing.
A typical invocation for this method would look like:
public String toString() { return ReflectionToStringBuilder.toString(this); }
You can also use the builder to debug 3rd party objects:
System.out.println("An object: " + ReflectionToStringBuilder.toString(anObject));
A subclass can control field output by overriding the methods:
For example, this method does not include the password
field in the returned String
:
public String toString() { return (new ReflectionToStringBuilder(this) { protected boolean accept(Field f) { return super.accept(f) && !f.getName().equals("password"); } }).toString(); }
Alternatively the ToStringExclude
annotation can be used to exclude fields from being incorporated in the
result.
It is also possible to use the ToStringSummary
annotation to output the summary information instead of the
detailed information of a field.
The exact format of the toString
is determined by the ToStringStyle
passed into the constructor.
Note: the default ToStringStyle
will only do a "shallow" formatting, i.e. composed objects are not
further traversed. To get "deep" formatting, use an instance of RecursiveToStringStyle
.
- Since:
- 2.0
-
Field Summary
-
Constructor Summary
ConstructorDescriptionReflectionToStringBuilder
(Object object) Constructor.ReflectionToStringBuilder
(Object object, ToStringStyle style) Constructor.ReflectionToStringBuilder
(Object object, ToStringStyle style, StringBuffer buffer) Constructor.ReflectionToStringBuilder
(T object, ToStringStyle style, StringBuffer buffer, Class<? super T> reflectUpToClass, boolean outputTransients, boolean outputStatics) Constructor.ReflectionToStringBuilder
(T object, ToStringStyle style, StringBuffer buffer, Class<? super T> reflectUpToClass, boolean outputTransients, boolean outputStatics, boolean excludeNullValues) Constructor. -
Method Summary
Modifier and TypeMethodDescriptionprotected boolean
Returns whether or not to append the givenField
.protected void
appendFieldsIn
(Class<?> clazz) Appends the fields and values defined by the given object of the given Class.String[]
Class<?>
Gets the last super class to stop appending fields for.protected Object
Callsjava.lang.reflect.Field.get(Object)
.boolean
Gets whether or not to append static fields.boolean
Gets whether or not to append transient fields.boolean
Gets whether or not to append fields whose values are null.reflectionAppendArray
(Object array) Append to thetoString
anObject
array.void
setAppendStatics
(boolean appendStatics) Sets whether or not to append static fields.void
setAppendTransients
(boolean appendTransients) Sets whether or not to append transient fields.setExcludeFieldNames
(String... excludeFieldNamesParam) Sets the field names to exclude.void
setExcludeNullValues
(boolean excludeNullValues) Sets whether or not to append fields whose values are null.void
setUpToClass
(Class<?> clazz) Sets the last super class to stop appending fields for.toString()
Gets the String built by this builder.static String
Builds atoString
value using the defaultToStringStyle
through reflection.static String
toString
(Object object, ToStringStyle style) Builds atoString
value through reflection.static String
toString
(Object object, ToStringStyle style, boolean outputTransients) Builds atoString
value through reflection.static String
toString
(Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics) Builds atoString
value through reflection.static <T> String
toString
(T object, ToStringStyle style, boolean outputTransients, boolean outputStatics, boolean excludeNullValues, Class<? super T> reflectUpToClass) Builds atoString
value through reflection.static <T> String
toString
(T object, ToStringStyle style, boolean outputTransients, boolean outputStatics, Class<? super T> reflectUpToClass) Builds atoString
value through reflection.static String
toStringExclude
(Object object, String... excludeFieldNames) Builds a String for a toString method excluding the given field names.static String
toStringExclude
(Object object, Collection<String> excludeFieldNames) Builds a String for a toString method excluding the given field names.Methods inherited from class edu.internet2.middleware.grouperClientExt.org.apache.commons.lang3.builder.ToStringBuilder
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, build, getDefaultStyle, getObject, getStringBuffer, getStyle, reflectionToString, reflectionToString, reflectionToString, reflectionToString, setDefaultStyle
-
Field Details
-
excludeFieldNames
Which field names to exclude from output. Intended for fields like"password"
.- Since:
- 3.0 this is protected instead of private
-
-
Constructor Details
-
ReflectionToStringBuilder
Constructor.
This constructor outputs using the default style set with
setDefaultStyle
.- Parameters:
object
- the Object to build atoString
for, must not benull
- Throws:
IllegalArgumentException
- if the Object passed in isnull
-
ReflectionToStringBuilder
Constructor.
If the style is
null
, the default style is used.- Parameters:
object
- the Object to build atoString
for, must not benull
style
- the style of thetoString
to create, may benull
- Throws:
IllegalArgumentException
- if the Object passed in isnull
-
ReflectionToStringBuilder
Constructor.
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 atoString
forstyle
- the style of thetoString
to create, may benull
buffer
- theStringBuffer
to populate, may benull
- Throws:
IllegalArgumentException
- if the Object passed in isnull
-
ReflectionToStringBuilder
public ReflectionToStringBuilder(T object, ToStringStyle style, StringBuffer buffer, Class<? super T> reflectUpToClass, boolean outputTransients, boolean outputStatics) Constructor.- Type Parameters:
T
- the type of the object- Parameters:
object
- the Object to build atoString
forstyle
- the style of thetoString
to create, may benull
buffer
- theStringBuffer
to populate, may benull
reflectUpToClass
- the superclass to reflect up to (inclusive), may benull
outputTransients
- whether to include transient fieldsoutputStatics
- whether to include static fields- Since:
- 2.1
-
ReflectionToStringBuilder
public ReflectionToStringBuilder(T object, ToStringStyle style, StringBuffer buffer, Class<? super T> reflectUpToClass, boolean outputTransients, boolean outputStatics, boolean excludeNullValues) Constructor.- Type Parameters:
T
- the type of the object- Parameters:
object
- the Object to build atoString
forstyle
- the style of thetoString
to create, may benull
buffer
- theStringBuffer
to populate, may benull
reflectUpToClass
- the superclass to reflect up to (inclusive), may benull
outputTransients
- whether to include transient fieldsoutputStatics
- whether to include static fieldsexcludeNullValues
- whether to exclude fields who value is null- Since:
- 3.6
-
-
Method Details
-
toString
Builds a
toString
value using the defaultToStringStyle
through reflection.It uses
AccessibleObject.setAccessible
to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.Transient members will be not be included, as they are likely derived. Static fields will not be included. Superclass fields will be appended.
- Parameters:
object
- the Object to be output- Returns:
- the String result
- Throws:
IllegalArgumentException
- if the Object isnull
- See Also:
-
toString
Builds a
toString
value through reflection.It uses
AccessibleObject.setAccessible
to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.Transient members will be not be included, as they are likely derived. Static fields will not be included. Superclass fields will be appended.
If the style is
null
, the defaultToStringStyle
is used.- Parameters:
object
- the Object to be outputstyle
- the style of thetoString
to create, may benull
- Returns:
- the String result
- Throws:
IllegalArgumentException
- if the Object orToStringStyle
isnull
- See Also:
-
toString
Builds a
toString
value through reflection.It uses
AccessibleObject.setAccessible
to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.If the
outputTransients
istrue
, 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 included. Superclass fields will be appended.
If the style is
null
, the defaultToStringStyle
is used.- Parameters:
object
- the Object to be outputstyle
- the style of thetoString
to create, may benull
outputTransients
- whether to include transient fields- Returns:
- the String result
- Throws:
IllegalArgumentException
- if the Object isnull
- See Also:
-
toString
public static String toString(Object object, ToStringStyle style, boolean outputTransients, boolean outputStatics) Builds a
toString
value through reflection.It uses
AccessibleObject.setAccessible
to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.If the
outputTransients
istrue
, transient fields will be output, otherwise they are ignored, as they are likely derived fields, and not part of the value of the Object.If the
outputStatics
istrue
, static fields will be output, otherwise they are ignored.Static fields will not be included. Superclass fields will be appended.
If the style is
null
, the defaultToStringStyle
is used.- Parameters:
object
- the Object to be outputstyle
- the style of thetoString
to create, may benull
outputTransients
- whether to include transient fieldsoutputStatics
- whether to include static fields- Returns:
- the String result
- Throws:
IllegalArgumentException
- if the Object isnull
- Since:
- 2.1
- See Also:
-
toString
public static <T> String toString(T object, ToStringStyle style, boolean outputTransients, boolean outputStatics, Class<? super T> reflectUpToClass) Builds a
toString
value through reflection.It uses
AccessibleObject.setAccessible
to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.If the
outputTransients
istrue
, transient fields will be output, otherwise they are ignored, as they are likely derived fields, and not part of the value of the Object.If the
outputStatics
istrue
, static fields will be output, otherwise they are ignored.Superclass fields will be appended up to and including the specified superclass. A null superclass is treated as
java.lang.Object
.If the style is
null
, the defaultToStringStyle
is used.- Type Parameters:
T
- the type of the object- Parameters:
object
- the Object to be outputstyle
- the style of thetoString
to create, may benull
outputTransients
- whether to include transient fieldsoutputStatics
- whether to include static fieldsreflectUpToClass
- the superclass to reflect up to (inclusive), may benull
- Returns:
- the String result
- Throws:
IllegalArgumentException
- if the Object isnull
- Since:
- 2.1
- See Also:
-
toString
public static <T> String toString(T object, ToStringStyle style, boolean outputTransients, boolean outputStatics, boolean excludeNullValues, Class<? super T> reflectUpToClass) Builds a
toString
value through reflection.It uses
AccessibleObject.setAccessible
to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. It is also not as efficient as testing explicitly.If the
outputTransients
istrue
, transient fields will be output, otherwise they are ignored, as they are likely derived fields, and not part of the value of the Object.If the
outputStatics
istrue
, static fields will be output, otherwise they are ignored.Superclass fields will be appended up to and including the specified superclass. A null superclass is treated as
java.lang.Object
.If the style is
null
, the defaultToStringStyle
is used.- Type Parameters:
T
- the type of the object- Parameters:
object
- the Object to be outputstyle
- the style of thetoString
to create, may benull
outputTransients
- whether to include transient fieldsoutputStatics
- whether to include static fieldsexcludeNullValues
- whether to exclude fields whose values are nullreflectUpToClass
- the superclass to reflect up to (inclusive), may benull
- Returns:
- the String result
- Throws:
IllegalArgumentException
- if the Object isnull
- Since:
- 3.6
- See Also:
-
toStringExclude
Builds a String for a toString method excluding the given field names.- Parameters:
object
- The object to "toString".excludeFieldNames
- The field names to exclude. Null excludes nothing.- Returns:
- The toString value.
-
toStringExclude
Builds a String for a toString method excluding the given field names.- Parameters:
object
- The object to "toString".excludeFieldNames
- The field names to exclude- Returns:
- The toString value.
-
accept
Returns whether or not to append the givenField
.- Transient fields are appended only if
isAppendTransients()
returnstrue
. - Static fields are appended only if
isAppendStatics()
returnstrue
. - Inner class fields are not appended.
- Parameters:
field
- The Field to test.- Returns:
- Whether or not to append the given
Field
.
- Transient fields are appended only if
-
appendFieldsIn
Appends the fields and values defined by the given object of the given Class.
If a cycle is detected as an object is "toString()'ed", such an object is rendered as if
Object.toString()
had been called and not implemented by the object.- Parameters:
clazz
- The class of object parameter
-
getExcludeFieldNames
- Returns:
- Returns the excludeFieldNames.
-
getUpToClass
Gets the last super class to stop appending fields for.
- Returns:
- The last super class to stop appending fields for.
-
getValue
Calls
java.lang.reflect.Field.get(Object)
.- Parameters:
field
- The Field to query.- Returns:
- The Object from the given Field.
- Throws:
IllegalArgumentException
- seeField.get(Object)
IllegalAccessException
- seeField.get(Object)
- See Also:
-
isAppendStatics
public boolean isAppendStatics()Gets whether or not to append static fields.
- Returns:
- Whether or not to append static fields.
- Since:
- 2.1
-
isAppendTransients
public boolean isAppendTransients()Gets whether or not to append transient fields.
- Returns:
- Whether or not to append transient fields.
-
isExcludeNullValues
public boolean isExcludeNullValues()Gets whether or not to append fields whose values are null.
- Returns:
- Whether or not to append fields whose values are null.
- Since:
- 3.6
-
reflectionAppendArray
Append to the
toString
anObject
array.- Parameters:
array
- the array to add to thetoString
- Returns:
- this
-
setAppendStatics
public void setAppendStatics(boolean appendStatics) Sets whether or not to append static fields.
- Parameters:
appendStatics
- Whether or not to append static fields.- Since:
- 2.1
-
setAppendTransients
public void setAppendTransients(boolean appendTransients) Sets whether or not to append transient fields.
- Parameters:
appendTransients
- Whether or not to append transient fields.
-
setExcludeNullValues
public void setExcludeNullValues(boolean excludeNullValues) Sets whether or not to append fields whose values are null.
- Parameters:
excludeNullValues
- Whether or not to append fields whose values are null.- Since:
- 3.6
-
setExcludeFieldNames
Sets the field names to exclude.- Parameters:
excludeFieldNamesParam
- The excludeFieldNames to excluding from toString ornull
.- Returns:
this
-
setUpToClass
Sets the last super class to stop appending fields for.
- Parameters:
clazz
- The last super class to stop appending fields for.
-
toString
Gets the String built by this builder.
- Overrides:
toString
in classToStringBuilder
- Returns:
- the built string
-