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