View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.builder;
18  
19  import org.apache.commons.lang3.ObjectUtils;
20  import org.apache.commons.lang3.Validate;
21  
22  /**
23   * <p>Assists in implementing {@link Object#toString()} methods.</p>
24   *
25   * <p>This class enables a good and consistent <code>toString()</code> to be built for any
26   * class or object. This class aims to simplify the process by:</p>
27   * <ul>
28   *  <li>allowing field names</li>
29   *  <li>handling all types consistently</li>
30   *  <li>handling nulls consistently</li>
31   *  <li>outputting arrays and multi-dimensional arrays</li>
32   *  <li>enabling the detail level to be controlled for Objects and Collections</li>
33   *  <li>handling class hierarchies</li>
34   * </ul>
35   *
36   * <p>To use this class write code as follows:</p>
37   *
38   * <pre>
39   * public class Person {
40   *   String name;
41   *   int age;
42   *   boolean smoker;
43   *
44   *   ...
45   *
46   *   public String toString() {
47   *     return new ToStringBuilder(this).
48   *       append("name", name).
49   *       append("age", age).
50   *       append("smoker", smoker).
51   *       toString();
52   *   }
53   * }
54   * </pre>
55   *
56   * <p>This will produce a toString of the format:
57   * <code>Person@7f54[name=Stephen,age=29,smoker=false]</code></p>
58   *
59   * <p>To add the superclass <code>toString</code>, use {@link #appendSuper}.
60   * To append the <code>toString</code> from an object that is delegated
61   * to (or any other object), use {@link #appendToString}.</p>
62   *
63   * <p>Alternatively, there is a method that uses reflection to determine
64   * the fields to test. Because these fields are usually private, the method,
65   * <code>reflectionToString</code>, uses <code>AccessibleObject.setAccessible</code> to
66   * change the visibility of the fields. This will fail under a security manager,
67   * unless the appropriate permissions are set up correctly. It is also
68   * slower than testing explicitly.</p>
69   *
70   * <p>A typical invocation for this method would look like:</p>
71   *
72   * <pre>
73   * public String toString() {
74   *   return ToStringBuilder.reflectionToString(this);
75   * }
76   * </pre>
77   *
78   * <p>You can also use the builder to debug 3rd party objects:</p>
79   *
80   * <pre>
81   * System.out.println("An object: " + ToStringBuilder.reflectionToString(anObject));
82   * </pre>
83   *
84   * <p>The exact format of the <code>toString</code> is determined by
85   * the {@link ToStringStyle} passed into the constructor.</p>
86   *
87   * @since 1.0
88   */
89  public class ToStringBuilder implements Builder<String> {
90  
91      /**
92       * The default style of output to use, not null.
93       */
94      private static volatile ToStringStyle defaultStyle = ToStringStyle.DEFAULT_STYLE;
95  
96      //----------------------------------------------------------------------------
97  
98      /**
99       * <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 }