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