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