    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3.builder;
    018
    019import org.apache.commons.lang3.ObjectUtils;
    020import org.apache.commons.lang3.Validate;
    021
    022/**
    023 * <p>Assists in implementing {@link Object#toString()} methods.</p>
    024 *
    025 * <p>This class enables a good and consistent <code>toString()</code> to be built for any
    026 * class or object. This class aims to simplify the process by:</p>
    027 * <ul>
    028 *  <li>allowing field names</li>
    029 *  <li>handling all types consistently</li>
    030 *  <li>handling nulls consistently</li>
    031 *  <li>outputting arrays and multi-dimensional arrays</li>
    032 *  <li>enabling the detail level to be controlled for Objects and Collections</li>
    033 *  <li>handling class hierarchies</li>
    034 * </ul>
    035 *
    036 * <p>To use this class write code as follows:</p>
    037 *
    038 * <pre>
    039 * public class Person {
    040 *   String name;
    041 *   int age;
    042 *   boolean smoker;
    043 *
    044 *   ...
    045 *
    046 *   public String toString() {
    047 *     return new ToStringBuilder(this).
    048 *       append("name", name).
    049 *       append("age", age).
    050 *       append("smoker", smoker).
    051 *       toString();
    052 *   }
    053 * }
    054 * </pre>
    055 *
    056 * <p>This will produce a toString of the format:
    057 * <code>Person@7f54[name=Stephen,age=29,smoker=false]</code></p>
    058 *
    059 * <p>To add the superclass <code>toString</code>, use {@link #appendSuper}.
    060 * To append the <code>toString</code> from an object that is delegated
    061 * to (or any other object), use {@link #appendToString}.</p>
    062 *
    063 * <p>Alternatively, there is a method that uses reflection to determine
    064 * the fields to test. Because these fields are usually private, the method,
    065 * <code>reflectionToString</code>, uses <code>AccessibleObject.setAccessible</code> to
    066 * change the visibility of the fields. This will fail under a security manager,
    067 * unless the appropriate permissions are set up correctly. It is also
    068 * slower than testing explicitly.</p>
    069 *
    070 * <p>A typical invocation for this method would look like:</p>
    071 *
    072 * <pre>
    073 * public String toString() {
    074 *   return ToStringBuilder.reflectionToString(this);
    075 * }
    076 * </pre>
    077 *
    078 * <p>You can also use the builder to debug 3rd party objects:</p>
    079 *
    080 * <pre>
    081 * System.out.println("An object: " + ToStringBuilder.reflectionToString(anObject));
    082 * </pre>
    083 *
    084 * <p>The exact format of the <code>toString</code> is determined by
    085 * the {@link ToStringStyle} passed into the constructor.</p>
    086 *
    087 * @since 1.0
    088 */
    089public class ToStringBuilder implements Builder<String> {
    090
    091    /**
    092     * The default style of output to use, not null.
    093     */
    094    private static volatile ToStringStyle defaultStyle = ToStringStyle.DEFAULT_STYLE;
    095
    096    //----------------------------------------------------------------------------
    097
    098    /**
    099     * <p>Gets the default <code>ToStringStyle</code> to use.</p>
    100     *
    101     * <p>This method gets a singleton default value, typically for the whole JVM.
    102     * Changing this default should generally only be done during application startup.
    103     * It is recommended to pass a <code>ToStringStyle</code> to the constructor instead
    104     * of using this global default.</p>
    105     *
    106     * <p>This method can be used from multiple threads.
    107     * Internally, a <code>volatile</code> variable is used to provide the guarantee
    108     * that the latest value set using {@link #setDefaultStyle} is the value returned.
    109     * It is strongly recommended that the default style is only changed during application startup.</p>
    110     *
    111     * <p>One reason for changing the default could be to have a verbose style during
    112     * development and a compact style in production.</p>
    113     *
    114     * @return the default <code>ToStringStyle</code>, never null
    115     */
    116    public static ToStringStyle getDefaultStyle() {
    117        return defaultStyle;
    118    }
    119
    120    /**
    121     * <p>Sets the default <code>ToStringStyle</code> to use.</p>
    122     *
    123     * <p>This method sets a singleton default value, typically for the whole JVM.
    124     * Changing this default should generally only be done during application startup.
    125     * It is recommended to pass a <code>ToStringStyle</code> to the constructor instead
    126     * of changing this global default.</p>
    127     *
    128     * <p>This method is not intended for use from multiple threads.
    129     * Internally, a <code>volatile</code> variable is used to provide the guarantee
    130     * that the latest value set is the value returned from {@link #getDefaultStyle}.</p>
    131     *
    132     * @param style  the default <code>ToStringStyle</code>
    133     * @throws IllegalArgumentException if the style is <code>null</code>
    134     */
    135    public static void setDefaultStyle(final ToStringStyle style) {
    136        Validate.isTrue(style != null, "The style must not be null");
    137        defaultStyle = style;
    138    }
    139
    140    //----------------------------------------------------------------------------
    141    /**
    142     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
    143     * <code>toString</code> for the specified object.</p>
    144     *
    145     * @param object  the Object to be output
    146     * @return the String result
    147     * @see ReflectionToStringBuilder#toString(Object)
    148     */
    149    public static String reflectionToString(final Object object) {
    150        return ReflectionToStringBuilder.toString(object);
    151    }
    152
    153    /**
    154     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
    155     * <code>toString</code> for the specified object.</p>
    156     *
    157     * @param object  the Object to be output
    158     * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
    159     * @return the String result
    160     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle)
    161     */
    162    public static String reflectionToString(final Object object, final ToStringStyle style) {
    163        return ReflectionToStringBuilder.toString(object, style);
    164    }
    165
    166    /**
    167     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
    168     * <code>toString</code> for the specified object.</p>
    169     *
    170     * @param object  the Object to be output
    171     * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
    172     * @param outputTransients  whether to include transient fields
    173     * @return the String result
    174     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean)
    175     */
    176    public static String reflectionToString(final Object object, final ToStringStyle style, final boolean outputTransients) {
    177        return ReflectionToStringBuilder.toString(object, style, outputTransients, false, null);
    178    }
    179
    180    /**
    181     * <p>Uses <code>ReflectionToStringBuilder</code> to generate a
    182     * <code>toString</code> for the specified object.</p>
    183     *
    184     * @param <T> the type of the object
    185     * @param object  the Object to be output
    186     * @param style  the style of the <code>toString</code> to create, may be <code>null</code>
    187     * @param outputTransients  whether to include transient fields
    188     * @param reflectUpToClass  the superclass to reflect up to (inclusive), may be <code>null</code>
    189     * @return the String result
    190     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean,boolean,Class)
    191     * @since 2.0
    192     */
    193    public static <T> String reflectionToString(
    194        final T object,
    195        final ToStringStyle style,
    196        final boolean outputTransients,
    197        final Class<? super T> reflectUpToClass) {
    198        return ReflectionToStringBuilder.toString(object, style, outputTransients, false, reflectUpToClass);
    199    }
    200
    201    //----------------------------------------------------------------------------
    202
    203    /**
    204     * Current toString buffer, not null.
    205     */
    206    private final StringBuffer buffer;
    207    /**
    208     * The object being output, may be null.
    209     */
    210    private final Object object;
    211    /**
    212     * The style of output to use, not null.
    213     */
    214    private final ToStringStyle style;
    215
    216    /**
    217     * <p>Constructs a builder for the specified object using the default output style.</p>
    218     *
    219     * <p>This default style is obtained from {@link #getDefaultStyle()}.</p>
    220     *
    221     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
    222     */
    223    public ToStringBuilder(final Object object) {
    224        this(object, null, null);
    225    }
    226
    227    /**
    228     * <p>Constructs a builder for the specified object using the defined output style.</p>
    229     *
    230     * <p>If the style is <code>null</code>, the default style is used.</p>
    231     *
    232     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
    233     * @param style  the style of the <code>toString</code> to create, null uses the default style
    234     */
    235    public ToStringBuilder(final Object object, final ToStringStyle style) {
    236        this(object, style, null);
    237    }
    238
    239    /**
    240     * <p>Constructs a builder for the specified object.</p>
    241     *
    242     * <p>If the style is <code>null</code>, the default style is used.</p>
    243     *
    244     * <p>If the buffer is <code>null</code>, a new one is created.</p>
    245     *
    246     * @param object  the Object to build a <code>toString</code> for, not recommended to be null
    247     * @param style  the style of the <code>toString</code> to create, null uses the default style
    248     * @param buffer  the <code>StringBuffer</code> to populate, may be null
    249     */
    250    public ToStringBuilder(final Object object, ToStringStyle style, StringBuffer buffer) {
    251        if (style == null) {
    252            style = getDefaultStyle();
    253        }
    254        if (buffer == null) {
    255            buffer = new StringBuffer(512);
    256        }
    257        this.buffer = buffer;
    258        this.style = style;
    259        this.object = object;
    260
    261        style.appendStart(buffer, object);
    262    }
    263
    264    //----------------------------------------------------------------------------
    265
    266    /**
    267     * <p>Append to the <code>toString</code> a <code>boolean</code>
    268     * value.</p>
    269     *
    270     * @param value  the value to add to the <code>toString</code>
    271     * @return this
    272     */
    273    public ToStringBuilder append(final boolean value) {
    274        style.append(buffer, null, value);
    275        return this;
    276    }
    277
    278    //----------------------------------------------------------------------------
    279
    280    /**
    281     * <p>Append to the <code>toString</code> a <code>boolean</code>
    282     * array.</p>
    283     *
    284     * @param array  the array to add to the <code>toString</code>
    285     * @return this
    286     */
    287    public ToStringBuilder append(final boolean[] array) {
    288        style.append(buffer, null, array, null);
    289        return this;
    290    }
    291
    292    //----------------------------------------------------------------------------
    293
    294    /**
    295     * <p>Append to the <code>toString</code> a <code>byte</code>
    296     * value.</p>
    297     *
    298     * @param value  the value to add to the <code>toString</code>
    299     * @return this
    300     */
    301    public ToStringBuilder append(final byte value) {
    302        style.append(buffer, null, value);
    303        return this;
    304    }
    305
    306    //----------------------------------------------------------------------------
    307
    308    /**
    309     * <p>Append to the <code>toString</code> a <code>byte</code>
    310     * array.</p>
    311     *
    312     * @param array  the array to add to the <code>toString</code>
    313     * @return this
    314     */
    315    public ToStringBuilder append(final byte[] array) {
    316        style.append(buffer, null, array, null);
    317        return this;
    318    }
    319
    320    //----------------------------------------------------------------------------
    321
    322    /**
    323     * <p>Append to the <code>toString</code> a <code>char</code>
    324     * value.</p>
    325     *
    326     * @param value  the value to add to the <code>toString</code>
    327     * @return this
    328     */
    329    public ToStringBuilder append(final char value) {
    330        style.append(buffer, null, value);
    331        return this;
    332    }
    333
    334    //----------------------------------------------------------------------------
    335
    336    /**
    337     * <p>Append to the <code>toString</code> a <code>char</code>
    338     * array.</p>
    339     *
    340     * @param array  the array to add to the <code>toString</code>
    341     * @return this
    342     */
    343    public ToStringBuilder append(final char[] array) {
    344        style.append(buffer, null, array, null);
    345        return this;
    346    }
    347
    348    //----------------------------------------------------------------------------
    349
    350    /**
    351     * <p>Append to the <code>toString</code> a <code>double</code>
    352     * value.</p>
    353     *
    354     * @param value  the value to add to the <code>toString</code>
    355     * @return this
    356     */
    357    public ToStringBuilder append(final double value) {
    358        style.append(buffer, null, value);
    359        return this;
    360    }
    361
    362    //----------------------------------------------------------------------------
    363
    364    /**
    365     * <p>Append to the <code>toString</code> a <code>double</code>
    366     * array.</p>
    367     *
    368     * @param array  the array to add to the <code>toString</code>
    369     * @return this
    370     */
    371    public ToStringBuilder append(final double[] array) {
    372        style.append(buffer, null, array, null);
    373        return this;
    374    }
    375
    376    //----------------------------------------------------------------------------
    377
    378    /**
    379     * <p>Append to the <code>toString</code> a <code>float</code>
    380     * value.</p>
    381     *
    382     * @param value  the value to add to the <code>toString</code>
    383     * @return this
    384     */
    385    public ToStringBuilder append(final float value) {
    386        style.append(buffer, null, value);
    387        return this;
    388    }
    389
    390    //----------------------------------------------------------------------------
    391
    392    /**
    393     * <p>Append to the <code>toString</code> a <code>float</code>
    394     * array.</p>
    395     *
    396     * @param array  the array to add to the <code>toString</code>
    397     * @return this
    398     */
    399    public ToStringBuilder append(final float[] array) {
    400        style.append(buffer, null, array, null);
    401        return this;
    402    }
    403
    404    //----------------------------------------------------------------------------
    405
    406    /**
    407     * <p>Append to the <code>toString</code> an <code>int</code>
    408     * value.</p>
    409     *
    410     * @param value  the value to add to the <code>toString</code>
    411     * @return this
    412     */
    413    public ToStringBuilder append(final int value) {
    414        style.append(buffer, null, value);
    415        return this;
    416    }
    417
    418    //----------------------------------------------------------------------------
    419
    420    /**
    421     * <p>Append to the <code>toString</code> an <code>int</code>
    422     * array.</p>
    423     *
    424     * @param array  the array to add to the <code>toString</code>
    425     * @return this
    426     */
    427    public ToStringBuilder append(final int[] array) {
    428        style.append(buffer, null, array, null);
    429        return this;
    430    }
    431
    432    //----------------------------------------------------------------------------
    433
    434    /**
    435     * <p>Append to the <code>toString</code> a <code>long</code>
    436     * value.</p>
    437     *
    438     * @param value  the value to add to the <code>toString</code>
    439     * @return this
    440     */
    441    public ToStringBuilder append(final long value) {
    442        style.append(buffer, null, value);
    443        return this;
    444    }
    445
    446    //----------------------------------------------------------------------------
    447
    448    /**
    449     * <p>Append to the <code>toString</code> a <code>long</code>
    450     * array.</p>
    451     *
    452     * @param array  the array to add to the <code>toString</code>
    453     * @return this
    454     */
    455    public ToStringBuilder append(final long[] array) {
    456        style.append(buffer, null, array, null);
    457        return this;
    458    }
    459
    460    //----------------------------------------------------------------------------
    461
    462    /**
    463     * <p>Append to the <code>toString</code> an <code>Object</code>
    464     * value.</p>
    465     *
    466     * @param obj  the value to add to the <code>toString</code>
    467     * @return this
    468     */
    469    public ToStringBuilder append(final Object obj) {
    470        style.append(buffer, null, obj, null);
    471        return this;
    472    }
    473
    474    //----------------------------------------------------------------------------
    475
    476    /**
    477     * <p>Append to the <code>toString</code> an <code>Object</code>
    478     * array.</p>
    479     *
    480     * @param array  the array to add to the <code>toString</code>
    481     * @return this
    482     */
    483    public ToStringBuilder append(final Object[] array) {
    484        style.append(buffer, null, array, null);
    485        return this;
    486    }
    487
    488    //----------------------------------------------------------------------------
    489
    490    /**
    491     * <p>Append to the <code>toString</code> a <code>short</code>
    492     * value.</p>
    493     *
    494     * @param value  the value to add to the <code>toString</code>
    495     * @return this
    496     */
    497    public ToStringBuilder append(final short value) {
    498        style.append(buffer, null, value);
    499        return this;
    500    }
    501
    502    //----------------------------------------------------------------------------
    503
    504    /**
    505     * <p>Append to the <code>toString</code> a <code>short</code>
    506     * array.</p>
    507     *
    508     * @param array  the array to add to the <code>toString</code>
    509     * @return this
    510     */
    511    public ToStringBuilder append(final short[] array) {
    512        style.append(buffer, null, array, null);
    513        return this;
    514    }
    515
    516    /**
    517     * <p>Append to the <code>toString</code> a <code>boolean</code>
    518     * value.</p>
    519     *
    520     * @param fieldName  the field name
    521     * @param value  the value to add to the <code>toString</code>
    522     * @return this
    523     */
    524    public ToStringBuilder append(final String fieldName, final boolean value) {
    525        style.append(buffer, fieldName, value);
    526        return this;
    527    }
    528
    529    /**
    530     * <p>Append to the <code>toString</code> a <code>boolean</code>
    531     * array.</p>
    532     *
    533     * @param fieldName  the field name
    534     * @param array  the array to add to the <code>hashCode</code>
    535     * @return this
    536     */
    537    public ToStringBuilder append(final String fieldName, final boolean[] array) {
    538        style.append(buffer, fieldName, array, null);
    539        return this;
    540    }
    541
    542    /**
    543     * <p>Append to the <code>toString</code> a <code>boolean</code>
    544     * array.</p>
    545     *
    546     * <p>A boolean parameter controls the level of detail to show.
    547     * Setting <code>true</code> will output the array in full. Setting
    548     * <code>false</code> will output a summary, typically the size of
    549     * the array.</p>
    550     *
    551     * @param fieldName  the field name
    552     * @param array  the array to add to the <code>toString</code>
    553     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    554     *  for summary info
    555     * @return this
    556     */
    557    public ToStringBuilder append(final String fieldName, final boolean[] array, final boolean fullDetail) {
    558        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    559        return this;
    560    }
    561
    562    /**
    563     * <p>Append to the <code>toString</code> an <code>byte</code>
    564     * value.</p>
    565     *
    566     * @param fieldName  the field name
    567     * @param value  the value to add to the <code>toString</code>
    568     * @return this
    569     */
    570    public ToStringBuilder append(final String fieldName, final byte value) {
    571        style.append(buffer, fieldName, value);
    572        return this;
    573    }
    574
    575    /**
    576     * <p>Append to the <code>toString</code> a <code>byte</code> array.</p>
    577     *
    578     * @param fieldName  the field name
    579     * @param array  the array to add to the <code>toString</code>
    580     * @return this
    581     */
    582    public ToStringBuilder append(final String fieldName, final byte[] array) {
    583        style.append(buffer, fieldName, array, null);
    584        return this;
    585    }
    586
    587    /**
    588     * <p>Append to the <code>toString</code> a <code>byte</code>
    589     * array.</p>
    590     *
    591     * <p>A boolean parameter controls the level of detail to show.
    592     * Setting <code>true</code> will output the array in full. Setting
    593     * <code>false</code> will output a summary, typically the size of
    594     * the array.
    595     *
    596     * @param fieldName  the field name
    597     * @param array  the array to add to the <code>toString</code>
    598     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    599     *  for summary info
    600     * @return this
    601     */
    602    public ToStringBuilder append(final String fieldName, final byte[] array, final boolean fullDetail) {
    603        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    604        return this;
    605    }
    606
    607    /**
    608     * <p>Append to the <code>toString</code> a <code>char</code>
    609     * value.</p>
    610     *
    611     * @param fieldName  the field name
    612     * @param value  the value to add to the <code>toString</code>
    613     * @return this
    614     */
    615    public ToStringBuilder append(final String fieldName, final char value) {
    616        style.append(buffer, fieldName, value);
    617        return this;
    618    }
    619
    620    /**
    621     * <p>Append to the <code>toString</code> a <code>char</code>
    622     * array.</p>
    623     *
    624     * @param fieldName  the field name
    625     * @param array  the array to add to the <code>toString</code>
    626     * @return this
    627     */
    628    public ToStringBuilder append(final String fieldName, final char[] array) {
    629        style.append(buffer, fieldName, array, null);
    630        return this;
    631    }
    632
    633    /**
    634     * <p>Append to the <code>toString</code> a <code>char</code>
    635     * array.</p>
    636     *
    637     * <p>A boolean parameter controls the level of detail to show.
    638     * Setting <code>true</code> will output the array in full. Setting
    639     * <code>false</code> will output a summary, typically the size of
    640     * the array.</p>
    641     *
    642     * @param fieldName  the field name
    643     * @param array  the array to add to the <code>toString</code>
    644     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    645     *  for summary info
    646     * @return this
    647     */
    648    public ToStringBuilder append(final String fieldName, final char[] array, final boolean fullDetail) {
    649        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    650        return this;
    651    }
    652
    653    /**
    654     * <p>Append to the <code>toString</code> a <code>double</code>
    655     * value.</p>
    656     *
    657     * @param fieldName  the field name
    658     * @param value  the value to add to the <code>toString</code>
    659     * @return this
    660     */
    661    public ToStringBuilder append(final String fieldName, final double value) {
    662        style.append(buffer, fieldName, value);
    663        return this;
    664    }
    665
    666    /**
    667     * <p>Append to the <code>toString</code> a <code>double</code>
    668     * array.</p>
    669     *
    670     * @param fieldName  the field name
    671     * @param array  the array to add to the <code>toString</code>
    672     * @return this
    673     */
    674    public ToStringBuilder append(final String fieldName, final double[] array) {
    675        style.append(buffer, fieldName, array, null);
    676        return this;
    677    }
    678
    679    /**
    680     * <p>Append to the <code>toString</code> a <code>double</code>
    681     * array.</p>
    682     *
    683     * <p>A boolean parameter controls the level of detail to show.
    684     * Setting <code>true</code> will output the array in full. Setting
    685     * <code>false</code> will output a summary, typically the size of
    686     * the array.</p>
    687     *
    688     * @param fieldName  the field name
    689     * @param array  the array to add to the <code>toString</code>
    690     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    691     *  for summary info
    692     * @return this
    693     */
    694    public ToStringBuilder append(final String fieldName, final double[] array, final boolean fullDetail) {
    695        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    696        return this;
    697    }
    698
    699    /**
    700     * <p>Append to the <code>toString</code> an <code>float</code>
    701     * value.</p>
    702     *
    703     * @param fieldName  the field name
    704     * @param value  the value to add to the <code>toString</code>
    705     * @return this
    706     */
    707    public ToStringBuilder append(final String fieldName, final float value) {
    708        style.append(buffer, fieldName, value);
    709        return this;
    710    }
    711
    712    /**
    713     * <p>Append to the <code>toString</code> a <code>float</code>
    714     * array.</p>
    715     *
    716     * @param fieldName  the field name
    717     * @param array  the array to add to the <code>toString</code>
    718     * @return this
    719     */
    720    public ToStringBuilder append(final String fieldName, final float[] array) {
    721        style.append(buffer, fieldName, array, null);
    722        return this;
    723    }
    724
    725    /**
    726     * <p>Append to the <code>toString</code> a <code>float</code>
    727     * array.</p>
    728     *
    729     * <p>A boolean parameter controls the level of detail to show.
    730     * Setting <code>true</code> will output the array in full. Setting
    731     * <code>false</code> will output a summary, typically the size of
    732     * the array.</p>
    733     *
    734     * @param fieldName  the field name
    735     * @param array  the array to add to the <code>toString</code>
    736     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    737     *  for summary info
    738     * @return this
    739     */
    740    public ToStringBuilder append(final String fieldName, final float[] array, final boolean fullDetail) {
    741        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    742        return this;
    743    }
    744
    745    /**
    746     * <p>Append to the <code>toString</code> an <code>int</code>
    747     * value.</p>
    748     *
    749     * @param fieldName  the field name
    750     * @param value  the value to add to the <code>toString</code>
    751     * @return this
    752     */
    753    public ToStringBuilder append(final String fieldName, final int value) {
    754        style.append(buffer, fieldName, value);
    755        return this;
    756    }
    757
    758    /**
    759     * <p>Append to the <code>toString</code> an <code>int</code>
    760     * array.</p>
    761     *
    762     * @param fieldName  the field name
    763     * @param array  the array to add to the <code>toString</code>
    764     * @return this
    765     */
    766    public ToStringBuilder append(final String fieldName, final int[] array) {
    767        style.append(buffer, fieldName, array, null);
    768        return this;
    769    }
    770
    771    /**
    772     * <p>Append to the <code>toString</code> an <code>int</code>
    773     * array.</p>
    774     *
    775     * <p>A boolean parameter controls the level of detail to show.
    776     * Setting <code>true</code> will output the array in full. Setting
    777     * <code>false</code> will output a summary, typically the size of
    778     * the array.</p>
    779     *
    780     * @param fieldName  the field name
    781     * @param array  the array to add to the <code>toString</code>
    782     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    783     *  for summary info
    784     * @return this
    785     */
    786    public ToStringBuilder append(final String fieldName, final int[] array, final boolean fullDetail) {
    787        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    788        return this;
    789    }
    790
    791    /**
    792     * <p>Append to the <code>toString</code> a <code>long</code>
    793     * value.</p>
    794     *
    795     * @param fieldName  the field name
    796     * @param value  the value to add to the <code>toString</code>
    797     * @return this
    798     */
    799    public ToStringBuilder append(final String fieldName, final long value) {
    800        style.append(buffer, fieldName, value);
    801        return this;
    802    }
    803
    804    /**
    805     * <p>Append to the <code>toString</code> a <code>long</code>
    806     * array.</p>
    807     *
    808     * @param fieldName  the field name
    809     * @param array  the array to add to the <code>toString</code>
    810     * @return this
    811     */
    812    public ToStringBuilder append(final String fieldName, final long[] array) {
    813        style.append(buffer, fieldName, array, null);
    814        return this;
    815    }
    816
    817    /**
    818     * <p>Append to the <code>toString</code> a <code>long</code>
    819     * array.</p>
    820     *
    821     * <p>A boolean parameter controls the level of detail to show.
    822     * Setting <code>true</code> will output the array in full. Setting
    823     * <code>false</code> will output a summary, typically the size of
    824     * the array.</p>
    825     *
    826     * @param fieldName  the field name
    827     * @param array  the array to add to the <code>toString</code>
    828     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    829     *  for summary info
    830     * @return this
    831     */
    832    public ToStringBuilder append(final String fieldName, final long[] array, final boolean fullDetail) {
    833        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    834        return this;
    835    }
    836
    837    /**
    838     * <p>Append to the <code>toString</code> an <code>Object</code>
    839     * value.</p>
    840     *
    841     * @param fieldName  the field name
    842     * @param obj  the value to add to the <code>toString</code>
    843     * @return this
    844     */
    845    public ToStringBuilder append(final String fieldName, final Object obj) {
    846        style.append(buffer, fieldName, obj, null);
    847        return this;
    848    }
    849
    850    /**
    851     * <p>Append to the <code>toString</code> an <code>Object</code>
    852     * value.</p>
    853     *
    854     * @param fieldName  the field name
    855     * @param obj  the value to add to the <code>toString</code>
    856     * @param fullDetail  <code>true</code> for detail,
    857     *  <code>false</code> for summary info
    858     * @return this
    859     */
    860    public ToStringBuilder append(final String fieldName, final Object obj, final boolean fullDetail) {
    861        style.append(buffer, fieldName, obj, Boolean.valueOf(fullDetail));
    862        return this;
    863    }
    864
    865    /**
    866     * <p>Append to the <code>toString</code> an <code>Object</code>
    867     * array.</p>
    868     *
    869     * @param fieldName  the field name
    870     * @param array  the array to add to the <code>toString</code>
    871     * @return this
    872     */
    873    public ToStringBuilder append(final String fieldName, final Object[] array) {
    874        style.append(buffer, fieldName, array, null);
    875        return this;
    876    }
    877
    878    /**
    879     * <p>Append to the <code>toString</code> an <code>Object</code>
    880     * array.</p>
    881     *
    882     * <p>A boolean parameter controls the level of detail to show.
    883     * Setting <code>true</code> will output the array in full. Setting
    884     * <code>false</code> will output a summary, typically the size of
    885     * the array.</p>
    886     *
    887     * @param fieldName  the field name
    888     * @param array  the array to add to the <code>toString</code>
    889     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    890     *  for summary info
    891     * @return this
    892     */
    893    public ToStringBuilder append(final String fieldName, final Object[] array, final boolean fullDetail) {
    894        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    895        return this;
    896    }
    897
    898    /**
    899     * <p>Append to the <code>toString</code> an <code>short</code>
    900     * value.</p>
    901     *
    902     * @param fieldName  the field name
    903     * @param value  the value to add to the <code>toString</code>
    904     * @return this
    905     */
    906    public ToStringBuilder append(final String fieldName, final short value) {
    907        style.append(buffer, fieldName, value);
    908        return this;
    909    }
    910
    911    /**
    912     * <p>Append to the <code>toString</code> a <code>short</code>
    913     * array.</p>
    914     *
    915     * @param fieldName  the field name
    916     * @param array  the array to add to the <code>toString</code>
    917     * @return this
    918     */
    919    public ToStringBuilder append(final String fieldName, final short[] array) {
    920        style.append(buffer, fieldName, array, null);
    921        return this;
    922    }
    923
    924    /**
    925     * <p>Append to the <code>toString</code> a <code>short</code>
    926     * array.</p>
    927     *
    928     * <p>A boolean parameter controls the level of detail to show.
    929     * Setting <code>true</code> will output the array in full. Setting
    930     * <code>false</code> will output a summary, typically the size of
    931     * the array.
    932     *
    933     * @param fieldName  the field name
    934     * @param array  the array to add to the <code>toString</code>
    935     * @param fullDetail  <code>true</code> for detail, <code>false</code>
    936     *  for summary info
    937     * @return this
    938     */
    939    public ToStringBuilder append(final String fieldName, final short[] array, final boolean fullDetail) {
    940        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    941        return this;
    942    }
    943
    944    /**
    945     * <p>Appends with the same format as the default <code>Object toString()
    946     * </code> method. Appends the class name followed by
    947     * {@link System#identityHashCode(java.lang.Object)}.</p>
    948     *
    949     * @param srcObject  the <code>Object</code> whose class name and id to output
    950     * @return this
    951     * @since 2.0
    952     */
    953    public ToStringBuilder appendAsObjectToString(final Object srcObject) {
    954        ObjectUtils.identityToString(this.getStringBuffer(), srcObject);
    955        return this;
    956    }
    957
    958    //----------------------------------------------------------------------------
    959
    960    /**
    961     * <p>Append the <code>toString</code> from the superclass.</p>
    962     *
    963     * <p>This method assumes that the superclass uses the same <code>ToStringStyle</code>
    964     * as this one.</p>
    965     *
    966     * <p>If <code>superToString</code> is <code>null</code>, no change is made.</p>
    967     *
    968     * @param superToString  the result of <code>super.toString()</code>
    969     * @return this
    970     * @since 2.0
    971     */
    972    public ToStringBuilder appendSuper(final String superToString) {
    973        if (superToString != null) {
    974            style.appendSuper(buffer, superToString);
    975        }
    976        return this;
    977    }
    978
    979    /**
    980     * <p>Append the <code>toString</code> from another object.</p>
    981     *
    982     * <p>This method is useful where a class delegates most of the implementation of
    983     * its properties to another class. You can then call <code>toString()</code> on
    984     * the other class and pass the result into this method.</p>
    985     *
    986     * <pre>
    987     *   private AnotherObject delegate;
    988     *   private String fieldInThisClass;
    989     *
    990     *   public String toString() {
    991     *     return new ToStringBuilder(this).
    992     *       appendToString(delegate.toString()).
    993     *       append(fieldInThisClass).
    994     *       toString();
    995     *   }</pre>
    996     *
    997     * <p>This method assumes that the other object uses the same <code>ToStringStyle</code>
    998     * as this one.</p>
    999     *
    1000     * <p>If the <code>toString</code> is <code>null</code>, no change is made.</p>
    1001     *
    1002     * @param toString  the result of <code>toString()</code> on another object
    1003     * @return this
    1004     * @since 2.0
    1005     */
    1006    public ToStringBuilder appendToString(final String toString) {
    1007        if (toString != null) {
    1008            style.appendToString(buffer, toString);
    1009        }
    1010        return this;
    1011    }
    1012
    1013    /**
    1014     * <p>Returns the <code>Object</code> being output.</p>
    1015     *
    1016     * @return The object being output.
    1017     * @since 2.0
    1018     */
    1019    public Object getObject() {
    1020        return object;
    1021    }
    1022
    1023    /**
    1024     * <p>Gets the <code>StringBuffer</code> being populated.</p>
    1025     *
    1026     * @return the <code>StringBuffer</code> being populated
    1027     */
    1028    public StringBuffer getStringBuffer() {
    1029        return buffer;
    1030    }
    1031
    1032    //----------------------------------------------------------------------------
    1033
    1034    /**
    1035     * <p>Gets the <code>ToStringStyle</code> being used.</p>
    1036     *
    1037     * @return the <code>ToStringStyle</code> being used
    1038     * @since 2.0
    1039     */
    1040    public ToStringStyle getStyle() {
    1041        return style;
    1042    }
    1043
    1044    /**
    1045     * <p>Returns the built <code>toString</code>.</p>
    1046     *
    1047     * <p>This method appends the end of data indicator, and can only be called once.
    1048     * Use {@link #getStringBuffer} to get the current string state.</p>
    1049     *
    1050     * <p>If the object is <code>null</code>, return the style's <code>nullText</code></p>
    1051     *
    1052     * @return the String <code>toString</code>
    1053     */
    1054    @Override
    1055    public String toString() {
    1056        if (this.getObject() == null) {
    1057            this.getStringBuffer().append(this.getStyle().getNullText());
    1058        } else {
    1059            style.appendEnd(this.getStringBuffer(), this.getObject());
    1060        }
    1061        return this.getStringBuffer().toString();
    1062    }
    1063
    1064    /**
    1065     * Returns the String that was build as an object representation. The
    1066     * default implementation utilizes the {@link #toString()} implementation.
    1067     *
    1068     * @return the String <code>toString</code>
    1069     *
    1070     * @see #toString()
    1071     *
    1072     * @since 3.0
    1073     */
    1074    @Override
    1075    public String build() {
    1076        return toString();
    1077    }
    1078}