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