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