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