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