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