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