    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()} 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]}</p>
    058 *
    059 * <p>To add the superclass {@code toString}, use {@link #appendSuper}.
    060 * To append the {@code toString} 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}, uses {@code AccessibleObject.setAccessible} 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} 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} 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} 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} 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}, never null
    115     */
    116    public static ToStringStyle getDefaultStyle() {
    117        return defaultStyle;
    118    }
    119
    120    /**
    121     * <p>Sets the default {@code ToStringStyle} 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} 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} 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}
    133     * @throws IllegalArgumentException if the style is {@code null}
    134     */
    135    public static void setDefaultStyle(final ToStringStyle style) {
    136        defaultStyle = Validate.notNull(style, "The style must not be null");
    137    }
    138
    139    //----------------------------------------------------------------------------
    140    /**
    141     * <p>Uses {@code ReflectionToStringBuilder} to generate a
    142     * {@code toString} for the specified object.</p>
    143     *
    144     * @param object  the Object to be output
    145     * @return the String result
    146     * @see ReflectionToStringBuilder#toString(Object)
    147     */
    148    public static String reflectionToString(final Object object) {
    149        return ReflectionToStringBuilder.toString(object);
    150    }
    151
    152    /**
    153     * <p>Uses {@code ReflectionToStringBuilder} to generate a
    154     * {@code toString} for the specified object.</p>
    155     *
    156     * @param object  the Object to be output
    157     * @param style  the style of the {@code toString} to create, may be {@code null}
    158     * @return the String result
    159     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle)
    160     */
    161    public static String reflectionToString(final Object object, final ToStringStyle style) {
    162        return ReflectionToStringBuilder.toString(object, style);
    163    }
    164
    165    /**
    166     * <p>Uses {@code ReflectionToStringBuilder} to generate a
    167     * {@code toString} for the specified object.</p>
    168     *
    169     * @param object  the Object to be output
    170     * @param style  the style of the {@code toString} to create, may be {@code null}
    171     * @param outputTransients  whether to include transient fields
    172     * @return the String result
    173     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean)
    174     */
    175    public static String reflectionToString(final Object object, final ToStringStyle style, final boolean outputTransients) {
    176        return ReflectionToStringBuilder.toString(object, style, outputTransients, false, null);
    177    }
    178
    179    /**
    180     * <p>Uses {@code ReflectionToStringBuilder} to generate a
    181     * {@code toString} for the specified object.</p>
    182     *
    183     * @param <T> the type of the object
    184     * @param object  the Object to be output
    185     * @param style  the style of the {@code toString} to create, may be {@code null}
    186     * @param outputTransients  whether to include transient fields
    187     * @param reflectUpToClass  the superclass to reflect up to (inclusive), may be {@code null}
    188     * @return the String result
    189     * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean,boolean,Class)
    190     * @since 2.0
    191     */
    192    public static <T> String reflectionToString(
    193        final T object,
    194        final ToStringStyle style,
    195        final boolean outputTransients,
    196        final Class<? super T> reflectUpToClass) {
    197        return ReflectionToStringBuilder.toString(object, style, outputTransients, false, reflectUpToClass);
    198    }
    199
    200    //----------------------------------------------------------------------------
    201
    202    /**
    203     * Current toString buffer, not null.
    204     */
    205    private final StringBuffer buffer;
    206    /**
    207     * The object being output, may be null.
    208     */
    209    private final Object object;
    210    /**
    211     * The style of output to use, not null.
    212     */
    213    private final ToStringStyle style;
    214
    215    /**
    216     * <p>Constructs a builder for the specified object using the default output style.</p>
    217     *
    218     * <p>This default style is obtained from {@link #getDefaultStyle()}.</p>
    219     *
    220     * @param object  the Object to build a {@code toString} for, not recommended to be null
    221     */
    222    public ToStringBuilder(final Object object) {
    223        this(object, null, null);
    224    }
    225
    226    /**
    227     * <p>Constructs a builder for the specified object using the defined output style.</p>
    228     *
    229     * <p>If the style is {@code null}, the default style is used.</p>
    230     *
    231     * @param object  the Object to build a {@code toString} for, not recommended to be null
    232     * @param style  the style of the {@code toString} to create, null uses the default style
    233     */
    234    public ToStringBuilder(final Object object, final ToStringStyle style) {
    235        this(object, style, null);
    236    }
    237
    238    /**
    239     * <p>Constructs a builder for the specified object.</p>
    240     *
    241     * <p>If the style is {@code null}, the default style is used.</p>
    242     *
    243     * <p>If the buffer is {@code null}, a new one is created.</p>
    244     *
    245     * @param object  the Object to build a {@code toString} for, not recommended to be null
    246     * @param style  the style of the {@code toString} to create, null uses the default style
    247     * @param buffer  the {@code StringBuffer} to populate, may be null
    248     */
    249    public ToStringBuilder(final Object object, ToStringStyle style, StringBuffer buffer) {
    250        if (style == null) {
    251            style = getDefaultStyle();
    252        }
    253        if (buffer == null) {
    254            buffer = new StringBuffer(512);
    255        }
    256        this.buffer = buffer;
    257        this.style = style;
    258        this.object = object;
    259
    260        style.appendStart(buffer, object);
    261    }
    262
    263    //----------------------------------------------------------------------------
    264
    265    /**
    266     * <p>Append to the {@code toString} a {@code boolean}
    267     * value.</p>
    268     *
    269     * @param value  the value to add to the {@code toString}
    270     * @return this
    271     */
    272    public ToStringBuilder append(final boolean value) {
    273        style.append(buffer, null, value);
    274        return this;
    275    }
    276
    277    //----------------------------------------------------------------------------
    278
    279    /**
    280     * <p>Append to the {@code toString} a {@code boolean}
    281     * array.</p>
    282     *
    283     * @param array  the array to add to the {@code toString}
    284     * @return this
    285     */
    286    public ToStringBuilder append(final boolean[] array) {
    287        style.append(buffer, null, array, null);
    288        return this;
    289    }
    290
    291    //----------------------------------------------------------------------------
    292
    293    /**
    294     * <p>Append to the {@code toString} a {@code byte}
    295     * value.</p>
    296     *
    297     * @param value  the value to add to the {@code toString}
    298     * @return this
    299     */
    300    public ToStringBuilder append(final byte value) {
    301        style.append(buffer, null, value);
    302        return this;
    303    }
    304
    305    //----------------------------------------------------------------------------
    306
    307    /**
    308     * <p>Append to the {@code toString} a {@code byte}
    309     * array.</p>
    310     *
    311     * @param array  the array to add to the {@code toString}
    312     * @return this
    313     */
    314    public ToStringBuilder append(final byte[] array) {
    315        style.append(buffer, null, array, null);
    316        return this;
    317    }
    318
    319    //----------------------------------------------------------------------------
    320
    321    /**
    322     * <p>Append to the {@code toString} a {@code char}
    323     * value.</p>
    324     *
    325     * @param value  the value to add to the {@code toString}
    326     * @return this
    327     */
    328    public ToStringBuilder append(final char value) {
    329        style.append(buffer, null, value);
    330        return this;
    331    }
    332
    333    //----------------------------------------------------------------------------
    334
    335    /**
    336     * <p>Append to the {@code toString} a {@code char}
    337     * array.</p>
    338     *
    339     * @param array  the array to add to the {@code toString}
    340     * @return this
    341     */
    342    public ToStringBuilder append(final char[] array) {
    343        style.append(buffer, null, array, null);
    344        return this;
    345    }
    346
    347    //----------------------------------------------------------------------------
    348
    349    /**
    350     * <p>Append to the {@code toString} a {@code double}
    351     * value.</p>
    352     *
    353     * @param value  the value to add to the {@code toString}
    354     * @return this
    355     */
    356    public ToStringBuilder append(final double value) {
    357        style.append(buffer, null, value);
    358        return this;
    359    }
    360
    361    //----------------------------------------------------------------------------
    362
    363    /**
    364     * <p>Append to the {@code toString} a {@code double}
    365     * array.</p>
    366     *
    367     * @param array  the array to add to the {@code toString}
    368     * @return this
    369     */
    370    public ToStringBuilder append(final double[] array) {
    371        style.append(buffer, null, array, null);
    372        return this;
    373    }
    374
    375    //----------------------------------------------------------------------------
    376
    377    /**
    378     * <p>Append to the {@code toString} a {@code float}
    379     * value.</p>
    380     *
    381     * @param value  the value to add to the {@code toString}
    382     * @return this
    383     */
    384    public ToStringBuilder append(final float value) {
    385        style.append(buffer, null, value);
    386        return this;
    387    }
    388
    389    //----------------------------------------------------------------------------
    390
    391    /**
    392     * <p>Append to the {@code toString} a {@code float}
    393     * array.</p>
    394     *
    395     * @param array  the array to add to the {@code toString}
    396     * @return this
    397     */
    398    public ToStringBuilder append(final float[] array) {
    399        style.append(buffer, null, array, null);
    400        return this;
    401    }
    402
    403    //----------------------------------------------------------------------------
    404
    405    /**
    406     * <p>Append to the {@code toString} an {@code int}
    407     * value.</p>
    408     *
    409     * @param value  the value to add to the {@code toString}
    410     * @return this
    411     */
    412    public ToStringBuilder append(final int value) {
    413        style.append(buffer, null, value);
    414        return this;
    415    }
    416
    417    //----------------------------------------------------------------------------
    418
    419    /**
    420     * <p>Append to the {@code toString} an {@code int}
    421     * array.</p>
    422     *
    423     * @param array  the array to add to the {@code toString}
    424     * @return this
    425     */
    426    public ToStringBuilder append(final int[] array) {
    427        style.append(buffer, null, array, null);
    428        return this;
    429    }
    430
    431    //----------------------------------------------------------------------------
    432
    433    /**
    434     * <p>Append to the {@code toString} a {@code long}
    435     * value.</p>
    436     *
    437     * @param value  the value to add to the {@code toString}
    438     * @return this
    439     */
    440    public ToStringBuilder append(final long value) {
    441        style.append(buffer, null, value);
    442        return this;
    443    }
    444
    445    //----------------------------------------------------------------------------
    446
    447    /**
    448     * <p>Append to the {@code toString} a {@code long}
    449     * array.</p>
    450     *
    451     * @param array  the array to add to the {@code toString}
    452     * @return this
    453     */
    454    public ToStringBuilder append(final long[] array) {
    455        style.append(buffer, null, array, null);
    456        return this;
    457    }
    458
    459    //----------------------------------------------------------------------------
    460
    461    /**
    462     * <p>Append to the {@code toString} an {@code Object}
    463     * value.</p>
    464     *
    465     * @param obj  the value to add to the {@code toString}
    466     * @return this
    467     */
    468    public ToStringBuilder append(final Object obj) {
    469        style.append(buffer, null, obj, null);
    470        return this;
    471    }
    472
    473    //----------------------------------------------------------------------------
    474
    475    /**
    476     * <p>Append to the {@code toString} an {@code Object}
    477     * array.</p>
    478     *
    479     * @param array  the array to add to the {@code toString}
    480     * @return this
    481     */
    482    public ToStringBuilder append(final Object[] array) {
    483        style.append(buffer, null, array, null);
    484        return this;
    485    }
    486
    487    //----------------------------------------------------------------------------
    488
    489    /**
    490     * <p>Append to the {@code toString} a {@code short}
    491     * value.</p>
    492     *
    493     * @param value  the value to add to the {@code toString}
    494     * @return this
    495     */
    496    public ToStringBuilder append(final short value) {
    497        style.append(buffer, null, value);
    498        return this;
    499    }
    500
    501    //----------------------------------------------------------------------------
    502
    503    /**
    504     * <p>Append to the {@code toString} a {@code short}
    505     * array.</p>
    506     *
    507     * @param array  the array to add to the {@code toString}
    508     * @return this
    509     */
    510    public ToStringBuilder append(final short[] array) {
    511        style.append(buffer, null, array, null);
    512        return this;
    513    }
    514
    515    /**
    516     * <p>Append to the {@code toString} a {@code boolean}
    517     * value.</p>
    518     *
    519     * @param fieldName  the field name
    520     * @param value  the value to add to the {@code toString}
    521     * @return this
    522     */
    523    public ToStringBuilder append(final String fieldName, final boolean value) {
    524        style.append(buffer, fieldName, value);
    525        return this;
    526    }
    527
    528    /**
    529     * <p>Append to the {@code toString} a {@code boolean}
    530     * array.</p>
    531     *
    532     * @param fieldName  the field name
    533     * @param array  the array to add to the {@code hashCode}
    534     * @return this
    535     */
    536    public ToStringBuilder append(final String fieldName, final boolean[] array) {
    537        style.append(buffer, fieldName, array, null);
    538        return this;
    539    }
    540
    541    /**
    542     * <p>Append to the {@code toString} a {@code boolean}
    543     * array.</p>
    544     *
    545     * <p>A boolean parameter controls the level of detail to show.
    546     * Setting {@code true} will output the array in full. Setting
    547     * {@code false} will output a summary, typically the size of
    548     * the array.</p>
    549     *
    550     * @param fieldName  the field name
    551     * @param array  the array to add to the {@code toString}
    552     * @param fullDetail  {@code true} for detail, {@code false}
    553     *  for summary info
    554     * @return this
    555     */
    556    public ToStringBuilder append(final String fieldName, final boolean[] array, final boolean fullDetail) {
    557        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    558        return this;
    559    }
    560
    561    /**
    562     * <p>Append to the {@code toString} an {@code byte}
    563     * value.</p>
    564     *
    565     * @param fieldName  the field name
    566     * @param value  the value to add to the {@code toString}
    567     * @return this
    568     */
    569    public ToStringBuilder append(final String fieldName, final byte value) {
    570        style.append(buffer, fieldName, value);
    571        return this;
    572    }
    573
    574    /**
    575     * <p>Append to the {@code toString} a {@code byte} array.</p>
    576     *
    577     * @param fieldName  the field name
    578     * @param array  the array to add to the {@code toString}
    579     * @return this
    580     */
    581    public ToStringBuilder append(final String fieldName, final byte[] array) {
    582        style.append(buffer, fieldName, array, null);
    583        return this;
    584    }
    585
    586    /**
    587     * <p>Append to the {@code toString} a {@code byte}
    588     * array.</p>
    589     *
    590     * <p>A boolean parameter controls the level of detail to show.
    591     * Setting {@code true} will output the array in full. Setting
    592     * {@code false} will output a summary, typically the size of
    593     * the array.
    594     *
    595     * @param fieldName  the field name
    596     * @param array  the array to add to the {@code toString}
    597     * @param fullDetail  {@code true} for detail, {@code false}
    598     *  for summary info
    599     * @return this
    600     */
    601    public ToStringBuilder append(final String fieldName, final byte[] array, final boolean fullDetail) {
    602        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    603        return this;
    604    }
    605
    606    /**
    607     * <p>Append to the {@code toString} a {@code char}
    608     * value.</p>
    609     *
    610     * @param fieldName  the field name
    611     * @param value  the value to add to the {@code toString}
    612     * @return this
    613     */
    614    public ToStringBuilder append(final String fieldName, final char value) {
    615        style.append(buffer, fieldName, value);
    616        return this;
    617    }
    618
    619    /**
    620     * <p>Append to the {@code toString} a {@code char}
    621     * array.</p>
    622     *
    623     * @param fieldName  the field name
    624     * @param array  the array to add to the {@code toString}
    625     * @return this
    626     */
    627    public ToStringBuilder append(final String fieldName, final char[] array) {
    628        style.append(buffer, fieldName, array, null);
    629        return this;
    630    }
    631
    632    /**
    633     * <p>Append to the {@code toString} a {@code char}
    634     * array.</p>
    635     *
    636     * <p>A boolean parameter controls the level of detail to show.
    637     * Setting {@code true} will output the array in full. Setting
    638     * {@code false} will output a summary, typically the size of
    639     * the array.</p>
    640     *
    641     * @param fieldName  the field name
    642     * @param array  the array to add to the {@code toString}
    643     * @param fullDetail  {@code true} for detail, {@code false}
    644     *  for summary info
    645     * @return this
    646     */
    647    public ToStringBuilder append(final String fieldName, final char[] array, final boolean fullDetail) {
    648        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    649        return this;
    650    }
    651
    652    /**
    653     * <p>Append to the {@code toString} a {@code double}
    654     * value.</p>
    655     *
    656     * @param fieldName  the field name
    657     * @param value  the value to add to the {@code toString}
    658     * @return this
    659     */
    660    public ToStringBuilder append(final String fieldName, final double value) {
    661        style.append(buffer, fieldName, value);
    662        return this;
    663    }
    664
    665    /**
    666     * <p>Append to the {@code toString} a {@code double}
    667     * array.</p>
    668     *
    669     * @param fieldName  the field name
    670     * @param array  the array to add to the {@code toString}
    671     * @return this
    672     */
    673    public ToStringBuilder append(final String fieldName, final double[] array) {
    674        style.append(buffer, fieldName, array, null);
    675        return this;
    676    }
    677
    678    /**
    679     * <p>Append to the {@code toString} a {@code double}
    680     * array.</p>
    681     *
    682     * <p>A boolean parameter controls the level of detail to show.
    683     * Setting {@code true} will output the array in full. Setting
    684     * {@code false} will output a summary, typically the size of
    685     * the array.</p>
    686     *
    687     * @param fieldName  the field name
    688     * @param array  the array to add to the {@code toString}
    689     * @param fullDetail  {@code true} for detail, {@code false}
    690     *  for summary info
    691     * @return this
    692     */
    693    public ToStringBuilder append(final String fieldName, final double[] array, final boolean fullDetail) {
    694        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    695        return this;
    696    }
    697
    698    /**
    699     * <p>Append to the {@code toString} an {@code float}
    700     * value.</p>
    701     *
    702     * @param fieldName  the field name
    703     * @param value  the value to add to the {@code toString}
    704     * @return this
    705     */
    706    public ToStringBuilder append(final String fieldName, final float value) {
    707        style.append(buffer, fieldName, value);
    708        return this;
    709    }
    710
    711    /**
    712     * <p>Append to the {@code toString} a {@code float}
    713     * array.</p>
    714     *
    715     * @param fieldName  the field name
    716     * @param array  the array to add to the {@code toString}
    717     * @return this
    718     */
    719    public ToStringBuilder append(final String fieldName, final float[] array) {
    720        style.append(buffer, fieldName, array, null);
    721        return this;
    722    }
    723
    724    /**
    725     * <p>Append to the {@code toString} a {@code float}
    726     * array.</p>
    727     *
    728     * <p>A boolean parameter controls the level of detail to show.
    729     * Setting {@code true} will output the array in full. Setting
    730     * {@code false} will output a summary, typically the size of
    731     * the array.</p>
    732     *
    733     * @param fieldName  the field name
    734     * @param array  the array to add to the {@code toString}
    735     * @param fullDetail  {@code true} for detail, {@code false}
    736     *  for summary info
    737     * @return this
    738     */
    739    public ToStringBuilder append(final String fieldName, final float[] array, final boolean fullDetail) {
    740        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    741        return this;
    742    }
    743
    744    /**
    745     * <p>Append to the {@code toString} an {@code int}
    746     * value.</p>
    747     *
    748     * @param fieldName  the field name
    749     * @param value  the value to add to the {@code toString}
    750     * @return this
    751     */
    752    public ToStringBuilder append(final String fieldName, final int value) {
    753        style.append(buffer, fieldName, value);
    754        return this;
    755    }
    756
    757    /**
    758     * <p>Append to the {@code toString} an {@code int}
    759     * array.</p>
    760     *
    761     * @param fieldName  the field name
    762     * @param array  the array to add to the {@code toString}
    763     * @return this
    764     */
    765    public ToStringBuilder append(final String fieldName, final int[] array) {
    766        style.append(buffer, fieldName, array, null);
    767        return this;
    768    }
    769
    770    /**
    771     * <p>Append to the {@code toString} an {@code int}
    772     * array.</p>
    773     *
    774     * <p>A boolean parameter controls the level of detail to show.
    775     * Setting {@code true} will output the array in full. Setting
    776     * {@code false} will output a summary, typically the size of
    777     * the array.</p>
    778     *
    779     * @param fieldName  the field name
    780     * @param array  the array to add to the {@code toString}
    781     * @param fullDetail  {@code true} for detail, {@code false}
    782     *  for summary info
    783     * @return this
    784     */
    785    public ToStringBuilder append(final String fieldName, final int[] array, final boolean fullDetail) {
    786        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    787        return this;
    788    }
    789
    790    /**
    791     * <p>Append to the {@code toString} a {@code long}
    792     * value.</p>
    793     *
    794     * @param fieldName  the field name
    795     * @param value  the value to add to the {@code toString}
    796     * @return this
    797     */
    798    public ToStringBuilder append(final String fieldName, final long value) {
    799        style.append(buffer, fieldName, value);
    800        return this;
    801    }
    802
    803    /**
    804     * <p>Append to the {@code toString} a {@code long}
    805     * array.</p>
    806     *
    807     * @param fieldName  the field name
    808     * @param array  the array to add to the {@code toString}
    809     * @return this
    810     */
    811    public ToStringBuilder append(final String fieldName, final long[] array) {
    812        style.append(buffer, fieldName, array, null);
    813        return this;
    814    }
    815
    816    /**
    817     * <p>Append to the {@code toString} a {@code long}
    818     * array.</p>
    819     *
    820     * <p>A boolean parameter controls the level of detail to show.
    821     * Setting {@code true} will output the array in full. Setting
    822     * {@code false} will output a summary, typically the size of
    823     * the array.</p>
    824     *
    825     * @param fieldName  the field name
    826     * @param array  the array to add to the {@code toString}
    827     * @param fullDetail  {@code true} for detail, {@code false}
    828     *  for summary info
    829     * @return this
    830     */
    831    public ToStringBuilder append(final String fieldName, final long[] array, final boolean fullDetail) {
    832        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    833        return this;
    834    }
    835
    836    /**
    837     * <p>Append to the {@code toString} an {@code Object}
    838     * value.</p>
    839     *
    840     * @param fieldName  the field name
    841     * @param obj  the value to add to the {@code toString}
    842     * @return this
    843     */
    844    public ToStringBuilder append(final String fieldName, final Object obj) {
    845        style.append(buffer, fieldName, obj, null);
    846        return this;
    847    }
    848
    849    /**
    850     * <p>Append to the {@code toString} an {@code Object}
    851     * value.</p>
    852     *
    853     * @param fieldName  the field name
    854     * @param obj  the value to add to the {@code toString}
    855     * @param fullDetail  {@code true} for detail,
    856     *  {@code false} for summary info
    857     * @return this
    858     */
    859    public ToStringBuilder append(final String fieldName, final Object obj, final boolean fullDetail) {
    860        style.append(buffer, fieldName, obj, Boolean.valueOf(fullDetail));
    861        return this;
    862    }
    863
    864    /**
    865     * <p>Append to the {@code toString} an {@code Object}
    866     * array.</p>
    867     *
    868     * @param fieldName  the field name
    869     * @param array  the array to add to the {@code toString}
    870     * @return this
    871     */
    872    public ToStringBuilder append(final String fieldName, final Object[] array) {
    873        style.append(buffer, fieldName, array, null);
    874        return this;
    875    }
    876
    877    /**
    878     * <p>Append to the {@code toString} an {@code Object}
    879     * array.</p>
    880     *
    881     * <p>A boolean parameter controls the level of detail to show.
    882     * Setting {@code true} will output the array in full. Setting
    883     * {@code false} will output a summary, typically the size of
    884     * the array.</p>
    885     *
    886     * @param fieldName  the field name
    887     * @param array  the array to add to the {@code toString}
    888     * @param fullDetail  {@code true} for detail, {@code false}
    889     *  for summary info
    890     * @return this
    891     */
    892    public ToStringBuilder append(final String fieldName, final Object[] array, final boolean fullDetail) {
    893        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    894        return this;
    895    }
    896
    897    /**
    898     * <p>Append to the {@code toString} an {@code short}
    899     * value.</p>
    900     *
    901     * @param fieldName  the field name
    902     * @param value  the value to add to the {@code toString}
    903     * @return this
    904     */
    905    public ToStringBuilder append(final String fieldName, final short value) {
    906        style.append(buffer, fieldName, value);
    907        return this;
    908    }
    909
    910    /**
    911     * <p>Append to the {@code toString} a {@code short}
    912     * array.</p>
    913     *
    914     * @param fieldName  the field name
    915     * @param array  the array to add to the {@code toString}
    916     * @return this
    917     */
    918    public ToStringBuilder append(final String fieldName, final short[] array) {
    919        style.append(buffer, fieldName, array, null);
    920        return this;
    921    }
    922
    923    /**
    924     * <p>Append to the {@code toString} a {@code short}
    925     * array.</p>
    926     *
    927     * <p>A boolean parameter controls the level of detail to show.
    928     * Setting {@code true} will output the array in full. Setting
    929     * {@code false} will output a summary, typically the size of
    930     * the array.
    931     *
    932     * @param fieldName  the field name
    933     * @param array  the array to add to the {@code toString}
    934     * @param fullDetail  {@code true} for detail, {@code false}
    935     *  for summary info
    936     * @return this
    937     */
    938    public ToStringBuilder append(final String fieldName, final short[] array, final boolean fullDetail) {
    939        style.append(buffer, fieldName, array, Boolean.valueOf(fullDetail));
    940        return this;
    941    }
    942
    943    /**
    944     * <p>Appends with the same format as the default <code>Object toString()
    945     * </code> method. Appends the class name followed by
    946     * {@link System#identityHashCode(java.lang.Object)}.</p>
    947     *
    948     * @param srcObject  the {@code Object} whose class name and id to output
    949     * @return this
    950     * @since 2.0
    951     */
    952    public ToStringBuilder appendAsObjectToString(final Object srcObject) {
    953        ObjectUtils.identityToString(this.getStringBuffer(), srcObject);
    954        return this;
    955    }
    956
    957    //----------------------------------------------------------------------------
    958
    959    /**
    960     * <p>Append the {@code toString} from the superclass.</p>
    961     *
    962     * <p>This method assumes that the superclass uses the same {@code ToStringStyle}
    963     * as this one.</p>
    964     *
    965     * <p>If {@code superToString} is {@code null}, no change is made.</p>
    966     *
    967     * @param superToString  the result of {@code super.toString()}
    968     * @return this
    969     * @since 2.0
    970     */
    971    public ToStringBuilder appendSuper(final String superToString) {
    972        if (superToString != null) {
    973            style.appendSuper(buffer, superToString);
    974        }
    975        return this;
    976    }
    977
    978    /**
    979     * <p>Append the {@code toString} from another object.</p>
    980     *
    981     * <p>This method is useful where a class delegates most of the implementation of
    982     * its properties to another class. You can then call {@code toString()} on
    983     * the other class and pass the result into this method.</p>
    984     *
    985     * <pre>
    986     *   private AnotherObject delegate;
    987     *   private String fieldInThisClass;
    988     *
    989     *   public String toString() {
    990     *     return new ToStringBuilder(this).
    991     *       appendToString(delegate.toString()).
    992     *       append(fieldInThisClass).
    993     *       toString();
    994     *   }</pre>
    995     *
    996     * <p>This method assumes that the other object uses the same {@code ToStringStyle}
    997     * as this one.</p>
    998     *
    999     * <p>If the {@code toString} is {@code null}, no change is made.</p>
    1000     *
    1001     * @param toString  the result of {@code toString()} on another object
    1002     * @return this
    1003     * @since 2.0
    1004     */
    1005    public ToStringBuilder appendToString(final String toString) {
    1006        if (toString != null) {
    1007            style.appendToString(buffer, toString);
    1008        }
    1009        return this;
    1010    }
    1011
    1012    /**
    1013     * <p>Returns the {@code Object} being output.</p>
    1014     *
    1015     * @return The object being output.
    1016     * @since 2.0
    1017     */
    1018    public Object getObject() {
    1019        return object;
    1020    }
    1021
    1022    /**
    1023     * <p>Gets the {@code StringBuffer} being populated.</p>
    1024     *
    1025     * @return the {@code StringBuffer} being populated
    1026     */
    1027    public StringBuffer getStringBuffer() {
    1028        return buffer;
    1029    }
    1030
    1031    //----------------------------------------------------------------------------
    1032
    1033    /**
    1034     * <p>Gets the {@code ToStringStyle} being used.</p>
    1035     *
    1036     * @return the {@code ToStringStyle} being used
    1037     * @since 2.0
    1038     */
    1039    public ToStringStyle getStyle() {
    1040        return style;
    1041    }
    1042
    1043    /**
    1044     * <p>Returns the built {@code toString}.</p>
    1045     *
    1046     * <p>This method appends the end of data indicator, and can only be called once.
    1047     * Use {@link #getStringBuffer} to get the current string state.</p>
    1048     *
    1049     * <p>If the object is {@code null}, return the style's {@code nullText}</p>
    1050     *
    1051     * @return the String {@code toString}
    1052     */
    1053    @Override
    1054    public String toString() {
    1055        if (this.getObject() == null) {
    1056            this.getStringBuffer().append(this.getStyle().getNullText());
    1057        } else {
    1058            style.appendEnd(this.getStringBuffer(), this.getObject());
    1059        }
    1060        return this.getStringBuffer().toString();
    1061    }
    1062
    1063    /**
    1064     * Returns the String that was build as an object representation. The
    1065     * default implementation utilizes the {@link #toString()} implementation.
    1066     *
    1067     * @return the String {@code toString}
    1068     *
    1069     * @see #toString()
    1070     *
    1071     * @since 3.0
    1072     */
    1073    @Override
    1074    public String build() {
    1075        return toString();
    1076    }
    1077}