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