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    }