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