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