ToStringBuilder (Reflection utility library 1.0.2 API)

java.lang.Object
- nl.talsmasoftware.reflection.strings.ToStringBuilder

All Implemented Interfaces:

Serializable, Appendable, CharSequence
```
public class ToStringBuilder
extends Object
implements Appendable, CharSequence, Serializable
```
A builder for 'toString' for objects that can append their named or unnamed properties to this builder.
The builder is very customizable, but has some sensible defaults:
- Any result wil start with some 'prefix' which by default is the simple name of the class being handled.
- All appended properties will be included within brackets, by default '{' and '}'.
- Properties will by default be separated from each-other by the separator string ", ".
- null values will by default not be included.
- brackets will by default only be added to the prefix if there is content within them.
An example of a default result could be: "TypeName{field=\"String value\", otherField=0, booleanField=false}".
Class diagram:
Author:

Sjoerd Talsma

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type Field Description

protected StringBuilder fields

protected String prefix

Fields
Modifier and Type	Field	Description
`protected StringBuilder`	`fields`
`protected String`	`prefix`

Constructor Summary

Constructors
Modifier	Constructor	Description
	`ToStringBuilder(Object source)`	Constructor to create a new ToStringBuilder for a particular object or type.
`protected`	`ToStringBuilder(ToStringBuilder parent, Object source)`	Constructor to create a new ToStringBuilder for a `source` object, while copying all customizable behaviour from another `parent` builder such as: brackets, separator, includeNulls and forceBrackets.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`ToStringBuilder`	`append(char c)`	Implementation of `Appendable.append(char)` to append a single character as a field value to this builder.
`ToStringBuilder`	`append(CharSequence value)`	Implementation of `Appendable.append(CharSequence)`, delegated to `append(Object)` to add a field value without prefixing it with a field name.
`ToStringBuilder`	`append(CharSequence csq, int start, int end)`	Implementation of `Appendable.append(CharSequence, int, int)` to append a partial value to this builder without prefixing it with a field name.
`ToStringBuilder`	`append(CharSequence name, Object value)`	This method is the only main 'append' method for this builder.
`ToStringBuilder`	`append(Object value)`	This method adds the value of a field to this builder, without prefixing it with a field name.
`ToStringBuilder`	`appendSuper(CharSequence superToStringResult)`	This method attempts to add the appended properties from a finished `toString()` result to this builder.
`protected void`	`appendValue(Object value)`	Delegate method that appends a property 'value' to this builder.
`ToStringBuilder`	`brackets(String openingBracket, String closingBracket)`	Configuration method that defines a custom set of brackets around the appended properties.
`char`	`charAt(int index)`	Implementation of `CharSequence.charAt(int)` that returns a single character from the current state of this builder.
`ToStringBuilder`	`forceBrackets(String openingBracket, String closingBracket)`	Forces brackets being added to this builder, even if there are no appended properties.
`protected boolean`	`hasContent()`	This method returns whether 'content' must be rendered (between the brackets).
`ToStringBuilder`	`includeNulls()`	Tells the builder that `null` properties must be added (which is `false` by default).
`ToStringBuilder`	`includeNulls(boolean includeNulls)`	Tells the builder whether `null` property values should be appended.
`int`	`length()`
`static ToStringBuilder`	`reflect(Object source)`	This method creates a `ToStringBuilder` where all public fields and property accessor methods from the source object have been reflected.
`ToStringBuilder`	`separator(CharSequence separator)`	Configuration method that allows the builder to use another separator between the appended properties (`", "` by default).
`CharSequence`	`subSequence(int start, int end)`	Implementation of `CharSequence.subSequence(int, int)` that returns a subsequence of the current state of this builder.
`String`	`toString()`

Methods inherited from interface java.lang.CharSequence
chars, codePoints

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - prefix
```
protected final String prefix
```
  - fields
```
protected final StringBuilder fields
```
- Constructor Detail
  - ToStringBuilder
```
public ToStringBuilder(Object source)
```
    Constructor to create a new ToStringBuilder for a particular object or type.
    
    Parameters:
    
    source - The object or type to create the ToStringBuilder for (Object, Class or a name).
  - ToStringBuilder
```
protected ToStringBuilder(ToStringBuilder parent,
                          Object source)
```
    Constructor to create a new ToStringBuilder for a source object, while copying all customizable behaviour from another parent builder such as: brackets, separator, includeNulls and forceBrackets.
    
    Parameters:
    
    parent - The parent builder to copy settings from (optional, don't copy any settings when null).
    
    source - The object to create the string for (or a custom prefix string).
- Method Detail
  - reflect
```
public static ToStringBuilder reflect(Object source)
```
    This method creates a ToStringBuilder where all public fields and property accessor methods from the source object have been reflected.
    
    Parameters:
    
    source - The source object for which a toString() builder will be created based on its public fields and property accessor methods.
    
    Returns:
    
    The builder that already has all public properties included in it, never null.
  - includeNulls
```
public ToStringBuilder includeNulls()
```
    Tells the builder that null properties must be added (which is false by default).
    
    Returns:
    
    Reference to this builder for method-chaining with updated 'includeNulls' setting.
  - includeNulls
```
public ToStringBuilder includeNulls(boolean includeNulls)
```
    Tells the builder whether null property values should be appended. (false by default).
    
    Parameters:
    
    includeNulls - Whether null properties should be appended.
    
    Returns:
    
    Reference to this builder for method-chaining with updated 'includeNulls' setting.
  - separator
```
public ToStringBuilder separator(CharSequence separator)
```
    Configuration method that allows the builder to use another separator between the appended properties (", " by default).
    Please note that this separator has no influence on previously appended properties.
    
    Parameters:
    
    separator - The new separator that should be used when appending additional properties to this builder, or null to omit the separator altogether.
    
    Returns:
    
    Reference to this builder for method-chaining with updated 'separator' setting.
  - forceBrackets
```
public ToStringBuilder forceBrackets(String openingBracket,
                                     String closingBracket)
```
    Forces brackets being added to this builder, even if there are no appended properties. The method also specifies which brackets will be used.
    It is also possible to merely modify the brackets being used without forcing them into the end-result using the brackets(String, String) configuration method.
    
    Parameters:
    
    openingBracket - The opening bracket to use for the resulting string.
    
    closingBracket - The closing bracket to use for the resulting string.
    
    Returns:
    
    Reference to this builder for method-chaining with updated brackets settings.
    
    See Also:
    
    brackets(String, String)
  - brackets
```
public ToStringBuilder brackets(String openingBracket,
                                String closingBracket)
```
    Configuration method that defines a custom set of brackets around the appended properties.
    It is also possible to force brackets being added even if no properties were added by using the forceBrackets(String, String) method.
    
    Parameters:
    
    openingBracket - The opening bracket to use for the resulting string ("{" is default, specify null to omit this bracket).
    
    closingBracket - The closing bracket to use for the resulting string ("}" is default, specify null to omit this bracket).
    
    Returns:
    
    Reference to this builder for method-chainining with updated brackets settings.
    
    See Also:
    
    forceBrackets(String, String)
  - appendSuper
```
public ToStringBuilder appendSuper(CharSequence superToStringResult)
```
    This method attempts to add the appended properties from a finished toString() result to this builder. This could be from a superclass toString result for example.
    For this parsing the builder will use the configured brackets settings to attempt to find the appended properties.
    When in control of the superclass, it may be better to 'design it for extension' by letting it return the non-finalized builder in a protected method so it can be appended to by a subclass without having to parse the end-result.
    
    protected ToStringBuilder toStringBuilder() { return super.toStringBuilder().append("fieldname", "Field value"); }
    
    Parameters:
    
    superToStringResult - The toString result from the superclass from which the appended properties will be extracted if possible.
    
    Returns:
    
    Reference to this builder for method-chaining with the properties from the superclass appended to it.
  - append
```
public ToStringBuilder append(CharSequence name,
                              Object value)
```
    This method is the only main 'append' method for this builder. All other append calls eventually route back to this method.
    
    Parameters:
    
    name - The name of the property being added (optional).
    
    value - The value of the property being added.
    
    Returns:
    
    Reference to this builder for method-chaining.
    
    See Also:
    
    includeNulls()
  - appendValue
```
protected void appendValue(Object value)
```
    Delegate method that appends a property 'value' to this builder. Is is made protected to allow subclasses to map Objects to custom String representations if required.
    This method gets called after a decision was made to append the value, so it will not be called in vain.
    The method does not need to take separators or field names into account. That has all been taken care of before this method call by append(CharSequence, Object). Therefore it is not normally necessary to call this method by yourself.
    Some specifics on how objects are rendered by default:
    - null: <null>.
    - CharSequence: "value".
    - any other Object: value.toString(), except:
    - for objects with the 'default' java.lang.Object string representation (class@hash) the reflected String representation is used.
    Parameters:
    
    value - The property value to be added to this builder.
  - append
```
public ToStringBuilder append(Object value)
```
    This method adds the value of a field to this builder, without prefixing it with a field name.
    
    Parameters:
    
    value - The field value to be added to this builder.
    
    Returns:
    
    Reference to this builder for method-chaining.
    
    See Also:
    
    append(CharSequence, Object)
  - append
```
public ToStringBuilder append(CharSequence value)
```
    Implementation of Appendable.append(CharSequence), delegated to append(Object) to add a field value without prefixing it with a field name.
    
    Specified by:
    
    append in interface Appendable
    
    Parameters:
    
    value - The field value to be added to this builder.
    
    Returns:
    
    Reference to this builder for method-chaining.
    
    See Also:
    
    append(CharSequence, Object)
  - append
```
public ToStringBuilder append(CharSequence csq,
                              int start,
                              int end)
```
    Implementation of Appendable.append(CharSequence, int, int) to append a partial value to this builder without prefixing it with a field name.
    
    Specified by:
    
    append in interface Appendable
    
    Parameters:
    
    csq - The sequence to be partially appended to this builder.
    
    start - The start index, inclusive.
    
    end - The end index, exclusive.
    
    Returns:
    
    Reference to this builder for method-chaining.
    
    See Also:
    
    append(CharSequence, Object)
  - append
```
public ToStringBuilder append(char c)
```
    Implementation of Appendable.append(char) to append a single character as a field value to this builder.
    
    Specified by:
    
    append in interface Appendable
    
    Parameters:
    
    c - The character to be appended as a field value in this builder.
    
    Returns:
    
    Reference to this builder for method-chaining.
    
    See Also:
    
    append(CharSequence, Object)
  - subSequence
```
public CharSequence subSequence(int start,
                                int end)
```
    Implementation of CharSequence.subSequence(int, int) that returns a subsequence of the current state of this builder.
    
    Specified by:
    
    subSequence in interface CharSequence
    
    Parameters:
    
    start - The start index, inclusive.
    
    end - The end index, exclusive.
    
    Returns:
    
    The requested subsequence for the current state of this builder.
  - hasContent
```
protected boolean hasContent()
```
    This method returns whether 'content' must be rendered (between the brackets).
    
    Returns:
    
    Whether there should be content rendered between the brackets.
  - toString
```
public String toString()
```
    Specified by:
    
    toString in interface CharSequence
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    The String representation of the current state of this builder.
  - length
```
public int length()
```
    Specified by:
    
    length in interface CharSequence
    
    Returns:
    
    The current length of this builder.
  - charAt
```
public char charAt(int index)
```
    Implementation of CharSequence.charAt(int) that returns a single character from the current state of this builder.
    
    Specified by:
    
    charAt in interface CharSequence
    
    Parameters:
    
    index - The index of the requested character.
    
    Returns:
    
    The character that is on position index in the current state of this builder.

Class ToStringBuilder

Field Summary

Constructor Summary

Method Summary

Methods inherited from interface java.lang.CharSequence

Methods inherited from class java.lang.Object

Field Detail

prefix

fields

Constructor Detail

ToStringBuilder

ToStringBuilder

Method Detail

reflect

includeNulls

includeNulls

separator

forceBrackets

brackets

appendSuper

append

appendValue

append

append

append

append

subSequence

hasContent

toString

length

charAt