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