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