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