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