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