001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one
003     *  or more contributor license agreements.  See the NOTICE file
004     *  distributed with this work for additional information
005     *  regarding copyright ownership.  The ASF licenses this file
006     *  to you under the Apache License, Version 2.0 (the
007     *  "License"); you may not use this file except in compliance
008     *  with the License.  You may obtain a copy of the License at
009     *  
010     *    http://www.apache.org/licenses/LICENSE-2.0
011     *  
012     *  Unless required by applicable law or agreed to in writing,
013     *  software distributed under the License is distributed on an
014     *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     *  KIND, either express or implied.  See the License for the
016     *  specific language governing permissions and limitations
017     *  under the License. 
018     *  
019     */
020    package org.apache.directory.shared.ldap.util;
021    
022    import org.apache.directory.shared.i18n.I18n;
023    
024    
025    /**
026     * <p>
027     * Assists in implementing {@link Object#toString()} methods.
028     * </p>
029     * <p>
030     * This class enables a good and consistent <code>toString()</code> to be
031     * built for any class or object. This class aims to simplify the process by:
032     * </p>
033     * <ul>
034     * <li>allowing field names</li>
035     * <li>handling all types consistently</li>
036     * <li>handling nulls consistently</li>
037     * <li>outputting arrays and multi-dimensional arrays</li>
038     * <li>enabling the detail level to be controlled for Objects and Collections</li>
039     * <li>handling class hierarchies</li>
040     * </ul>
041     * <p>
042     * To use this class write code as follows:
043     * </p>
044     * 
045     * <pre>
046     *  public class Person {
047     *    String name;
048     *    int age;
049     *    boolean isSmoker;
050     *  
051     *    ...
052     *  
053     *    public String toString() {
054     *      return new ToStringBuilder(this).
055     *        append(&quot;name&quot;, name).
056     *        append(&quot;age&quot;, age).
057     *        append(&quot;smoker&quot;, smoker).
058     *        toString();
059     *    }
060     *  }
061     * </pre>
062     * 
063     * <p>
064     * This will produce a toString of the format:
065     * <code>Person@7f54[name=Stephen,age=29,smoker=false]</code>
066     * </p>
067     * <p>
068     * To add the superclass <code>toString</code>, use {@link #appendSuper}. To
069     * append the <code>toString</code> from an object that is delegated to (or
070     * any other object), use {@link #appendToString}.
071     * </p>
072     * <p>
073     * Alternatively, there is a method that uses reflection to determine the fields
074     * to test. Because these fields are usually private, the method,
075     * <code>reflectionToString</code>, uses
076     * <code>AccessibleObject.setAccessible</code> to change the visibility of the
077     * fields. This will fail under a security manager, unless the appropriate
078     * permissions are set up correctly. It is also slower than testing explicitly.
079     * </p>
080     * <p>
081     * A typical invocation for this method would look like:
082     * </p>
083     * 
084     * <pre>
085     * public String toString()
086     * {
087     *     return ToStringBuilder.reflectionToString( this );
088     * }
089     * </pre>
090     * 
091     * <p>
092     * You can also use the builder to debug 3rd party objects:
093     * </p>
094     * 
095     * <pre>
096     * System.out.println( &quot;An object: &quot; + ToStringBuilder.reflectionToString( anObject ) );
097     * </pre>
098     * 
099     * <p>
100     * The exact format of the <code>toString</code> is determined by the
101     * {@link ToStringStyle} passed into the constructor.
102     * </p>
103     * 
104     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
105     */
106    public class ToStringBuilder
107    {
108    
109        /**
110         * The default style of output to use.
111         */
112        private static ToStringStyle defaultStyle = ToStringStyle.DEFAULT_STYLE;
113    
114    
115        // ----------------------------------------------------------------------------
116    
117        /**
118         * <p>
119         * Gets the default <code>ToStringStyle</code> to use.
120         * </p>
121         * <p>
122         * This could allow the <code>ToStringStyle</code> to be controlled for an
123         * entire application with one call.
124         * </p>
125         * <p>
126         * This might be used to have a verbose <code>ToStringStyle</code> during
127         * development and a compact <code>ToStringStyle</code> in production.
128         * </p>
129         * 
130         * @return the default <code>ToStringStyle</code>
131         */
132        public static ToStringStyle getDefaultStyle()
133        {
134            return defaultStyle;
135        }
136    
137    
138        /**
139         * <p>
140         * Forwards to <code>ReflectionToStringBuilder</code>.
141         * </p>
142         * 
143         * @see ReflectionToStringBuilder#toString(Object)
144         */
145        public static String reflectionToString( Object object )
146        {
147            return ReflectionToStringBuilder.toString( object );
148        }
149    
150    
151        /**
152         * <p>
153         * Forwards to <code>ReflectionToStringBuilder</code>.
154         * </p>
155         * 
156         * @see ReflectionToStringBuilder#toString(Object,ToStringStyle)
157         */
158        public static String reflectionToString( Object object, ToStringStyle style )
159        {
160            return ReflectionToStringBuilder.toString( object, style );
161        }
162    
163    
164        /**
165         * <p>
166         * Forwards to <code>ReflectionToStringBuilder</code>.
167         * </p>
168         * 
169         * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean)
170         */
171        public static String reflectionToString( Object object, ToStringStyle style, boolean outputTransients )
172        {
173            return ReflectionToStringBuilder.toString( object, style, outputTransients, false, null );
174        }
175    
176    
177        /**
178         * <p>
179         * Forwards to <code>ReflectionToStringBuilder</code>.
180         * </p>
181         * 
182         * @see ReflectionToStringBuilder#toString(Object,ToStringStyle,boolean,boolean,Class)
183         * @since 2.0
184         */
185        public static String reflectionToString( Object object, ToStringStyle style, boolean outputTransients,
186            Class reflectUpToClass )
187        {
188            return ReflectionToStringBuilder.toString( object, style, outputTransients, false, reflectUpToClass );
189        }
190    
191    
192        /**
193         * <p>
194         * Sets the default <code>ToStringStyle</code> to use.
195         * </p>
196         * 
197         * @param style
198         *            the default <code>ToStringStyle</code>
199         * @throws IllegalArgumentException
200         *             if the style is <code>null</code>
201         */
202        public static void setDefaultStyle( ToStringStyle style )
203        {
204            if ( style == null )
205            {
206                throw new IllegalArgumentException( I18n.err( I18n.ERR_04438 ) );
207            }
208            defaultStyle = style;
209        }
210    
211        /**
212         * Current toString buffer.
213         */
214        private final StringBuffer buffer;
215    
216        /**
217         * The object being output.
218         */
219        private final Object object;
220    
221        /**
222         * The style of output to use.
223         */
224        private final ToStringStyle style;
225    
226    
227        /**
228         * <p>
229         * Constructor for <code>ToStringBuilder</code>.
230         * </p>
231         * <p>
232         * This constructor outputs using the default style set with
233         * <code>setDefaultStyle</code>.
234         * </p>
235         * 
236         * @param object
237         *            the Object to build a <code>toString</code> for
238         * @throws IllegalArgumentException
239         *             if the Object passed in is <code>null</code>
240         */
241        public ToStringBuilder(Object object)
242        {
243            this( object, getDefaultStyle(), null );
244        }
245    
246    
247        /**
248         * <p>
249         * Constructor for <code>ToStringBuilder</code> specifying the output
250         * style.
251         * </p>
252         * <p>
253         * If the style is <code>null</code>, the default style is used.
254         * </p>
255         * 
256         * @param object
257         *            the Object to build a <code>toString</code> for
258         * @param style
259         *            the style of the <code>toString</code> to create, may be
260         *            <code>null</code>
261         * @throws IllegalArgumentException
262         *             if the Object passed in is <code>null</code>
263         */
264        public ToStringBuilder(Object object, ToStringStyle style)
265        {
266            this( object, style, null );
267        }
268    
269    
270        /**
271         * <p>
272         * Constructor for <code>ToStringBuilder</code>.
273         * </p>
274         * <p>
275         * If the style is <code>null</code>, the default style is used.
276         * </p>
277         * <p>
278         * If the buffer is <code>null</code>, a new one is created.
279         * </p>
280         * 
281         * @param object
282         *            the Object to build a <code>toString</code> for
283         * @param style
284         *            the style of the <code>toString</code> to create, may be
285         *            <code>null</code>
286         * @param buffer
287         *            the <code>StringBuffer</code> to populate, may be
288         *            <code>null</code>
289         */
290        public ToStringBuilder(Object object, ToStringStyle style, StringBuffer buffer)
291        {
292            if ( style == null )
293            {
294                style = getDefaultStyle();
295            }
296            if ( buffer == null )
297            {
298                buffer = new StringBuffer( 512 );
299            }
300            this.buffer = buffer;
301            this.style = style;
302            this.object = object;
303    
304            style.appendStart( buffer, object );
305        }
306    
307    
308        // ----------------------------------------------------------------------------
309    
310        /**
311         * <p>
312         * Append to the <code>toString</code> a <code>boolean</code> value.
313         * </p>
314         * 
315         * @param value
316         *            the value to add to the <code>toString</code>
317         * @return this
318         */
319        public ToStringBuilder append( boolean value )
320        {
321            style.append( buffer, null, value );
322            return this;
323        }
324    
325    
326        // ----------------------------------------------------------------------------
327    
328        /**
329         * <p>
330         * Append to the <code>toString</code> a <code>boolean</code> array.
331         * </p>
332         * 
333         * @param array
334         *            the array to add to the <code>toString</code>
335         * @return this
336         */
337        public ToStringBuilder append( boolean[] array )
338        {
339            style.append( buffer, null, array, null );
340            return this;
341        }
342    
343    
344        // ----------------------------------------------------------------------------
345    
346        /**
347         * <p>
348         * Append to the <code>toString</code> a <code>byte</code> value.
349         * </p>
350         * 
351         * @param value
352         *            the value to add to the <code>toString</code>
353         * @return this
354         */
355        public ToStringBuilder append( byte value )
356        {
357            style.append( buffer, null, value );
358            return this;
359        }
360    
361    
362        // ----------------------------------------------------------------------------
363    
364        /**
365         * <p>
366         * Append to the <code>toString</code> a <code>byte</code> array.
367         * </p>
368         * 
369         * @param array
370         *            the array to add to the <code>toString</code>
371         * @return this
372         */
373        public ToStringBuilder append( byte[] array )
374        {
375            style.append( buffer, null, array, null );
376            return this;
377        }
378    
379    
380        // ----------------------------------------------------------------------------
381    
382        /**
383         * <p>
384         * Append to the <code>toString</code> a <code>char</code> value.
385         * </p>
386         * 
387         * @param value
388         *            the value to add to the <code>toString</code>
389         * @return this
390         */
391        public ToStringBuilder append( char value )
392        {
393            style.append( buffer, null, value );
394            return this;
395        }
396    
397    
398        // ----------------------------------------------------------------------------
399    
400        /**
401         * <p>
402         * Append to the <code>toString</code> a <code>char</code> array.
403         * </p>
404         * 
405         * @param array
406         *            the array to add to the <code>toString</code>
407         * @return this
408         */
409        public ToStringBuilder append( char[] array )
410        {
411            style.append( buffer, null, array, null );
412            return this;
413        }
414    
415    
416        // ----------------------------------------------------------------------------
417    
418        /**
419         * <p>
420         * Append to the <code>toString</code> a <code>double</code> value.
421         * </p>
422         * 
423         * @param value
424         *            the value to add to the <code>toString</code>
425         * @return this
426         */
427        public ToStringBuilder append( double value )
428        {
429            style.append( buffer, null, value );
430            return this;
431        }
432    
433    
434        // ----------------------------------------------------------------------------
435    
436        /**
437         * <p>
438         * Append to the <code>toString</code> a <code>double</code> array.
439         * </p>
440         * 
441         * @param array
442         *            the array to add to the <code>toString</code>
443         * @return this
444         */
445        public ToStringBuilder append( double[] array )
446        {
447            style.append( buffer, null, array, null );
448            return this;
449        }
450    
451    
452        // ----------------------------------------------------------------------------
453    
454        /**
455         * <p>
456         * Append to the <code>toString</code> a <code>float</code> value.
457         * </p>
458         * 
459         * @param value
460         *            the value to add to the <code>toString</code>
461         * @return this
462         */
463        public ToStringBuilder append( float value )
464        {
465            style.append( buffer, null, value );
466            return this;
467        }
468    
469    
470        // ----------------------------------------------------------------------------
471    
472        /**
473         * <p>
474         * Append to the <code>toString</code> a <code>float</code> array.
475         * </p>
476         * 
477         * @param array
478         *            the array to add to the <code>toString</code>
479         * @return this
480         */
481        public ToStringBuilder append( float[] array )
482        {
483            style.append( buffer, null, array, null );
484            return this;
485        }
486    
487    
488        // ----------------------------------------------------------------------------
489    
490        /**
491         * <p>
492         * Append to the <code>toString</code> an <code>int</code> value.
493         * </p>
494         * 
495         * @param value
496         *            the value to add to the <code>toString</code>
497         * @return this
498         */
499        public ToStringBuilder append( int value )
500        {
501            style.append( buffer, null, value );
502            return this;
503        }
504    
505    
506        // ----------------------------------------------------------------------------
507    
508        /**
509         * <p>
510         * Append to the <code>toString</code> an <code>int</code> array.
511         * </p>
512         * 
513         * @param array
514         *            the array to add to the <code>toString</code>
515         * @return this
516         */
517        public ToStringBuilder append( int[] array )
518        {
519            style.append( buffer, null, array, null );
520            return this;
521        }
522    
523    
524        // ----------------------------------------------------------------------------
525    
526        /**
527         * <p>
528         * Append to the <code>toString</code> a <code>long</code> value.
529         * </p>
530         * 
531         * @param value
532         *            the value to add to the <code>toString</code>
533         * @return this
534         */
535        public ToStringBuilder append( long value )
536        {
537            style.append( buffer, null, value );
538            return this;
539        }
540    
541    
542        // ----------------------------------------------------------------------------
543    
544        /**
545         * <p>
546         * Append to the <code>toString</code> a <code>long</code> array.
547         * </p>
548         * 
549         * @param array
550         *            the array to add to the <code>toString</code>
551         * @return this
552         */
553        public ToStringBuilder append( long[] array )
554        {
555            style.append( buffer, null, array, null );
556            return this;
557        }
558    
559    
560        // ----------------------------------------------------------------------------
561    
562        /**
563         * <p>
564         * Append to the <code>toString</code> an <code>Object</code> value.
565         * </p>
566         * 
567         * @param object
568         *            the value to add to the <code>toString</code>
569         * @return this
570         */
571        public ToStringBuilder append( Object object )
572        {
573            style.append( buffer, null, object, null );
574            return this;
575        }
576    
577    
578        // ----------------------------------------------------------------------------
579    
580        /**
581         * <p>
582         * Append to the <code>toString</code> an <code>Object</code> array.
583         * </p>
584         * 
585         * @param array
586         *            the array to add to the <code>toString</code>
587         * @return this
588         */
589        public ToStringBuilder append( Object[] array )
590        {
591            style.append( buffer, null, array, null );
592            return this;
593        }
594    
595    
596        // ----------------------------------------------------------------------------
597    
598        /**
599         * <p>
600         * Append to the <code>toString</code> a <code>short</code> value.
601         * </p>
602         * 
603         * @param value
604         *            the value to add to the <code>toString</code>
605         * @return this
606         */
607        public ToStringBuilder append( short value )
608        {
609            style.append( buffer, null, value );
610            return this;
611        }
612    
613    
614        // ----------------------------------------------------------------------------
615    
616        /**
617         * <p>
618         * Append to the <code>toString</code> a <code>short</code> array.
619         * </p>
620         * 
621         * @param array
622         *            the array to add to the <code>toString</code>
623         * @return this
624         */
625        public ToStringBuilder append( short[] array )
626        {
627            style.append( buffer, null, array, null );
628            return this;
629        }
630    
631    
632        /**
633         * <p>
634         * Append to the <code>toString</code> a <code>boolean</code> value.
635         * </p>
636         * 
637         * @param fieldName
638         *            the field name
639         * @param value
640         *            the value to add to the <code>toString</code>
641         * @return this
642         */
643        public ToStringBuilder append( String fieldName, boolean value )
644        {
645            style.append( buffer, fieldName, value );
646            return this;
647        }
648    
649    
650        /**
651         * <p>
652         * Append to the <code>toString</code> a <code>boolean</code> array.
653         * </p>
654         * 
655         * @param fieldName
656         *            the field name
657         * @param array
658         *            the array to add to the <code>hashCode</code>
659         * @return this
660         */
661        public ToStringBuilder append( String fieldName, boolean[] array )
662        {
663            style.append( buffer, fieldName, array, null );
664            return this;
665        }
666    
667    
668        /**
669         * <p>
670         * Append to the <code>toString</code> a <code>boolean</code> array.
671         * </p>
672         * <p>
673         * A boolean parameter controls the level of detail to show. Setting
674         * <code>true</code> will output the array in full. Setting
675         * <code>false</code> will output a summary, typically the size of the
676         * array.
677         * </p>
678         * 
679         * @param fieldName
680         *            the field name
681         * @param array
682         *            the array to add to the <code>toString</code>
683         * @param fullDetail
684         *            <code>true</code> for detail, <code>false</code> for
685         *            summary info
686         * @return this
687         */
688        public ToStringBuilder append( String fieldName, boolean[] array, boolean fullDetail )
689        {
690            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
691            return this;
692        }
693    
694    
695        /**
696         * <p>
697         * Append to the <code>toString</code> an <code>byte</code> value.
698         * </p>
699         * 
700         * @param fieldName
701         *            the field name
702         * @param value
703         *            the value to add to the <code>toString</code>
704         * @return this
705         */
706        public ToStringBuilder append( String fieldName, byte value )
707        {
708            style.append( buffer, fieldName, value );
709            return this;
710        }
711    
712    
713        /**
714         * <p>
715         * Append to the <code>toString</code> a <code>byte</code> array.
716         * </p>
717         * 
718         * @param fieldName
719         *            the field name
720         * @param array
721         *            the array to add to the <code>toString</code>
722         * @return this
723         */
724        public ToStringBuilder append( String fieldName, byte[] array )
725        {
726            style.append( buffer, fieldName, array, null );
727            return this;
728        }
729    
730    
731        /**
732         * <p>
733         * Append to the <code>toString</code> a <code>byte</code> array.
734         * </p>
735         * <p>
736         * A boolean parameter controls the level of detail to show. Setting
737         * <code>true</code> will output the array in full. Setting
738         * <code>false</code> will output a summary, typically the size of the
739         * array.
740         * 
741         * @param fieldName
742         *            the field name
743         * @param array
744         *            the array to add to the <code>toString</code>
745         * @param fullDetail
746         *            <code>true</code> for detail, <code>false</code> for
747         *            summary info
748         * @return this
749         */
750        public ToStringBuilder append( String fieldName, byte[] array, boolean fullDetail )
751        {
752            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
753            return this;
754        }
755    
756    
757        /**
758         * <p>
759         * Append to the <code>toString</code> a <code>char</code> value.
760         * </p>
761         * 
762         * @param fieldName
763         *            the field name
764         * @param value
765         *            the value to add to the <code>toString</code>
766         * @return this
767         */
768        public ToStringBuilder append( String fieldName, char value )
769        {
770            style.append( buffer, fieldName, value );
771            return this;
772        }
773    
774    
775        /**
776         * <p>
777         * Append to the <code>toString</code> a <code>char</code> array.
778         * </p>
779         * 
780         * @param fieldName
781         *            the field name
782         * @param array
783         *            the array to add to the <code>toString</code>
784         * @return this
785         */
786        public ToStringBuilder append( String fieldName, char[] array )
787        {
788            style.append( buffer, fieldName, array, null );
789            return this;
790        }
791    
792    
793        /**
794         * <p>
795         * Append to the <code>toString</code> a <code>char</code> array.
796         * </p>
797         * <p>
798         * A boolean parameter controls the level of detail to show. Setting
799         * <code>true</code> will output the array in full. Setting
800         * <code>false</code> will output a summary, typically the size of the
801         * array.
802         * </p>
803         * 
804         * @param fieldName
805         *            the field name
806         * @param array
807         *            the array to add to the <code>toString</code>
808         * @param fullDetail
809         *            <code>true</code> for detail, <code>false</code> for
810         *            summary info
811         * @return this
812         */
813        public ToStringBuilder append( String fieldName, char[] array, boolean fullDetail )
814        {
815            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
816            return this;
817        }
818    
819    
820        /**
821         * <p>
822         * Append to the <code>toString</code> a <code>double</code> value.
823         * </p>
824         * 
825         * @param fieldName
826         *            the field name
827         * @param value
828         *            the value to add to the <code>toString</code>
829         * @return this
830         */
831        public ToStringBuilder append( String fieldName, double value )
832        {
833            style.append( buffer, fieldName, value );
834            return this;
835        }
836    
837    
838        /**
839         * <p>
840         * Append to the <code>toString</code> a <code>double</code> array.
841         * </p>
842         * 
843         * @param fieldName
844         *            the field name
845         * @param array
846         *            the array to add to the <code>toString</code>
847         * @return this
848         */
849        public ToStringBuilder append( String fieldName, double[] array )
850        {
851            style.append( buffer, fieldName, array, null );
852            return this;
853        }
854    
855    
856        /**
857         * <p>
858         * Append to the <code>toString</code> a <code>double</code> array.
859         * </p>
860         * <p>
861         * A boolean parameter controls the level of detail to show. Setting
862         * <code>true</code> will output the array in full. Setting
863         * <code>false</code> will output a summary, typically the size of the
864         * array.
865         * </p>
866         * 
867         * @param fieldName
868         *            the field name
869         * @param array
870         *            the array to add to the <code>toString</code>
871         * @param fullDetail
872         *            <code>true</code> for detail, <code>false</code> for
873         *            summary info
874         * @return this
875         */
876        public ToStringBuilder append( String fieldName, double[] array, boolean fullDetail )
877        {
878            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
879            return this;
880        }
881    
882    
883        /**
884         * <p>
885         * Append to the <code>toString</code> an <code>float</code> value.
886         * </p>
887         * 
888         * @param fieldName
889         *            the field name
890         * @param value
891         *            the value to add to the <code>toString</code>
892         * @return this
893         */
894        public ToStringBuilder append( String fieldName, float value )
895        {
896            style.append( buffer, fieldName, value );
897            return this;
898        }
899    
900    
901        /**
902         * <p>
903         * Append to the <code>toString</code> a <code>float</code> array.
904         * </p>
905         * 
906         * @param fieldName
907         *            the field name
908         * @param array
909         *            the array to add to the <code>toString</code>
910         * @return this
911         */
912        public ToStringBuilder append( String fieldName, float[] array )
913        {
914            style.append( buffer, fieldName, array, null );
915            return this;
916        }
917    
918    
919        /**
920         * <p>
921         * Append to the <code>toString</code> a <code>float</code> array.
922         * </p>
923         * <p>
924         * A boolean parameter controls the level of detail to show. Setting
925         * <code>true</code> will output the array in full. Setting
926         * <code>false</code> will output a summary, typically the size of the
927         * array.
928         * </p>
929         * 
930         * @param fieldName
931         *            the field name
932         * @param array
933         *            the array to add to the <code>toString</code>
934         * @param fullDetail
935         *            <code>true</code> for detail, <code>false</code> for
936         *            summary info
937         * @return this
938         */
939        public ToStringBuilder append( String fieldName, float[] array, boolean fullDetail )
940        {
941            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
942            return this;
943        }
944    
945    
946        /**
947         * <p>
948         * Append to the <code>toString</code> an <code>int</code> value.
949         * </p>
950         * 
951         * @param fieldName
952         *            the field name
953         * @param value
954         *            the value to add to the <code>toString</code>
955         * @return this
956         */
957        public ToStringBuilder append( String fieldName, int value )
958        {
959            style.append( buffer, fieldName, value );
960            return this;
961        }
962    
963    
964        /**
965         * <p>
966         * Append to the <code>toString</code> an <code>int</code> array.
967         * </p>
968         * 
969         * @param fieldName
970         *            the field name
971         * @param array
972         *            the array to add to the <code>toString</code>
973         * @return this
974         */
975        public ToStringBuilder append( String fieldName, int[] array )
976        {
977            style.append( buffer, fieldName, array, null );
978            return this;
979        }
980    
981    
982        /**
983         * <p>
984         * Append to the <code>toString</code> an <code>int</code> array.
985         * </p>
986         * <p>
987         * A boolean parameter controls the level of detail to show. Setting
988         * <code>true</code> will output the array in full. Setting
989         * <code>false</code> will output a summary, typically the size of the
990         * array.
991         * </p>
992         * 
993         * @param fieldName
994         *            the field name
995         * @param array
996         *            the array to add to the <code>toString</code>
997         * @param fullDetail
998         *            <code>true</code> for detail, <code>false</code> for
999         *            summary info
1000         * @return this
1001         */
1002        public ToStringBuilder append( String fieldName, int[] array, boolean fullDetail )
1003        {
1004            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
1005            return this;
1006        }
1007    
1008    
1009        /**
1010         * <p>
1011         * Append to the <code>toString</code> a <code>long</code> value.
1012         * </p>
1013         * 
1014         * @param fieldName
1015         *            the field name
1016         * @param value
1017         *            the value to add to the <code>toString</code>
1018         * @return this
1019         */
1020        public ToStringBuilder append( String fieldName, long value )
1021        {
1022            style.append( buffer, fieldName, value );
1023            return this;
1024        }
1025    
1026    
1027        /**
1028         * <p>
1029         * Append to the <code>toString</code> a <code>long</code> array.
1030         * </p>
1031         * 
1032         * @param fieldName
1033         *            the field name
1034         * @param array
1035         *            the array to add to the <code>toString</code>
1036         * @return this
1037         */
1038        public ToStringBuilder append( String fieldName, long[] array )
1039        {
1040            style.append( buffer, fieldName, array, null );
1041            return this;
1042        }
1043    
1044    
1045        /**
1046         * <p>
1047         * Append to the <code>toString</code> a <code>long</code> array.
1048         * </p>
1049         * <p>
1050         * A boolean parameter controls the level of detail to show. Setting
1051         * <code>true</code> will output the array in full. Setting
1052         * <code>false</code> will output a summary, typically the size of the
1053         * array.
1054         * </p>
1055         * 
1056         * @param fieldName
1057         *            the field name
1058         * @param array
1059         *            the array to add to the <code>toString</code>
1060         * @param fullDetail
1061         *            <code>true</code> for detail, <code>false</code> for
1062         *            summary info
1063         * @return this
1064         */
1065        public ToStringBuilder append( String fieldName, long[] array, boolean fullDetail )
1066        {
1067            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
1068            return this;
1069        }
1070    
1071    
1072        /**
1073         * <p>
1074         * Append to the <code>toString</code> an <code>Object</code> value.
1075         * </p>
1076         * 
1077         * @param fieldName
1078         *            the field name
1079         * @param object
1080         *            the value to add to the <code>toString</code>
1081         * @return this
1082         */
1083        public ToStringBuilder append( String fieldName, Object object )
1084        {
1085            style.append( buffer, fieldName, object, null );
1086            return this;
1087        }
1088    
1089    
1090        /**
1091         * <p>
1092         * Append to the <code>toString</code> an <code>Object</code> value.
1093         * </p>
1094         * 
1095         * @param fieldName
1096         *            the field name
1097         * @param object
1098         *            the value to add to the <code>toString</code>
1099         * @param fullDetail
1100         *            <code>true</code> for detail, <code>false</code> for
1101         *            summary info
1102         * @return this
1103         */
1104        public ToStringBuilder append( String fieldName, Object object, boolean fullDetail )
1105        {
1106            style.append( buffer, fieldName, object, BooleanUtils.toBooleanObject( fullDetail ) );
1107            return this;
1108        }
1109    
1110    
1111        /**
1112         * <p>
1113         * Append to the <code>toString</code> an <code>Object</code> array.
1114         * </p>
1115         * 
1116         * @param fieldName
1117         *            the field name
1118         * @param array
1119         *            the array to add to the <code>toString</code>
1120         * @return this
1121         */
1122        public ToStringBuilder append( String fieldName, Object[] array )
1123        {
1124            style.append( buffer, fieldName, array, null );
1125            return this;
1126        }
1127    
1128    
1129        /**
1130         * <p>
1131         * Append to the <code>toString</code> an <code>Object</code> array.
1132         * </p>
1133         * <p>
1134         * A boolean parameter controls the level of detail to show. Setting
1135         * <code>true</code> will output the array in full. Setting
1136         * <code>false</code> will output a summary, typically the size of the
1137         * array.
1138         * </p>
1139         * 
1140         * @param fieldName
1141         *            the field name
1142         * @param array
1143         *            the array to add to the <code>toString</code>
1144         * @param fullDetail
1145         *            <code>true</code> for detail, <code>false</code> for
1146         *            summary info
1147         * @return this
1148         */
1149        public ToStringBuilder append( String fieldName, Object[] array, boolean fullDetail )
1150        {
1151            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
1152            return this;
1153        }
1154    
1155    
1156        /**
1157         * <p>
1158         * Append to the <code>toString</code> an <code>short</code> value.
1159         * </p>
1160         * 
1161         * @param fieldName
1162         *            the field name
1163         * @param value
1164         *            the value to add to the <code>toString</code>
1165         * @return this
1166         */
1167        public ToStringBuilder append( String fieldName, short value )
1168        {
1169            style.append( buffer, fieldName, value );
1170            return this;
1171        }
1172    
1173    
1174        /**
1175         * <p>
1176         * Append to the <code>toString</code> a <code>short</code> array.
1177         * </p>
1178         * 
1179         * @param fieldName
1180         *            the field name
1181         * @param array
1182         *            the array to add to the <code>toString</code>
1183         * @return this
1184         */
1185        public ToStringBuilder append( String fieldName, short[] array )
1186        {
1187            style.append( buffer, fieldName, array, null );
1188            return this;
1189        }
1190    
1191    
1192        /**
1193         * <p>
1194         * Append to the <code>toString</code> a <code>short</code> array.
1195         * </p>
1196         * <p>
1197         * A boolean parameter controls the level of detail to show. Setting
1198         * <code>true</code> will output the array in full. Setting
1199         * <code>false</code> will output a summary, typically the size of the
1200         * array.
1201         * 
1202         * @param fieldName
1203         *            the field name
1204         * @param array
1205         *            the array to add to the <code>toString</code>
1206         * @param fullDetail
1207         *            <code>true</code> for detail, <code>false</code> for
1208         *            summary info
1209         * @return this
1210         */
1211        public ToStringBuilder append( String fieldName, short[] array, boolean fullDetail )
1212        {
1213            style.append( buffer, fieldName, array, BooleanUtils.toBooleanObject( fullDetail ) );
1214            return this;
1215        }
1216    
1217    
1218        /**
1219         * <p>
1220         * Appends with the same format as the default <code>Object toString()
1221         * </code>
1222         * method. Appends the class name followed by
1223         * {@link System#identityHashCode(java.lang.Object)}.
1224         * </p>
1225         * 
1226         * @param object
1227         *            the <code>Object</code> whose class name and id to output
1228         * @return this
1229         * @since 2.0
1230         */
1231        public ToStringBuilder appendAsObjectToString( Object object )
1232        {
1233            ObjectUtils.appendIdentityToString( this.getStringBuffer(), object );
1234            return this;
1235        }
1236    
1237    
1238        // ----------------------------------------------------------------------------
1239    
1240        /**
1241         * <p>
1242         * Append the <code>toString</code> from the superclass.
1243         * </p>
1244         * <p>
1245         * This method assumes that the superclass uses the same
1246         * <code>ToStringStyle</code> as this one.
1247         * </p>
1248         * <p>
1249         * If <code>superToString</code> is <code>null</code>, no change is
1250         * made.
1251         * </p>
1252         * 
1253         * @param superToString
1254         *            the result of <code>super.toString()</code>
1255         * @return this
1256         * @since 2.0
1257         */
1258        public ToStringBuilder appendSuper( String superToString )
1259        {
1260            if ( superToString != null )
1261            {
1262                style.appendSuper( buffer, superToString );
1263            }
1264            return this;
1265        }
1266    
1267    
1268        /**
1269         * <p>
1270         * Append the <code>toString</code> from another object.
1271         * </p>
1272         * <p>
1273         * This method is useful where a class delegates most of the implementation
1274         * of its properties to another class. You can then call
1275         * <code>toString()</code> on the other class and pass the result into
1276         * this method.
1277         * </p>
1278         * 
1279         * <pre>
1280         * private AnotherObject delegate;
1281         * 
1282         * private String fieldInThisClass;
1283         * 
1284         * 
1285         * public String toString()
1286         * {
1287         *     return new ToStringBuilder( this ).appendToString( delegate.toString() ).append( fieldInThisClass ).toString();
1288         * }
1289         * </pre>
1290         * 
1291         * <p>
1292         * This method assumes that the other object uses the same
1293         * <code>ToStringStyle</code> as this one.
1294         * </p>
1295         * <p>
1296         * If the <code>toString</code> is <code>null</code>, no change is
1297         * made.
1298         * </p>
1299         * 
1300         * @param toString
1301         *            the result of <code>toString()</code> on another object
1302         * @return this
1303         * @since 2.0
1304         */
1305        public ToStringBuilder appendToString( String toString )
1306        {
1307            if ( toString != null )
1308            {
1309                style.appendToString( buffer, toString );
1310            }
1311            return this;
1312        }
1313    
1314    
1315        /**
1316         * <p>
1317         * Returns the <code>Object</code> being output.
1318         * </p>
1319         * 
1320         * @return The object being output.
1321         * @since 2.0
1322         */
1323        public Object getObject()
1324        {
1325            return object;
1326        }
1327    
1328    
1329        /**
1330         * <p>
1331         * Gets the <code>StringBuffer</code> being populated.
1332         * </p>
1333         * 
1334         * @return the <code>StringBuffer</code> being populated
1335         */
1336        public StringBuffer getStringBuffer()
1337        {
1338            return buffer;
1339        }
1340    
1341    
1342        // ----------------------------------------------------------------------------
1343    
1344        /**
1345         * <p>
1346         * Gets the <code>ToStringStyle</code> being used.
1347         * </p>
1348         * 
1349         * @return the <code>ToStringStyle</code> being used
1350         * @since 2.0
1351         */
1352        public ToStringStyle getStyle()
1353        {
1354            return style;
1355        }
1356    
1357    
1358        /**
1359         * <p>
1360         * Returns the built <code>toString</code>.
1361         * </p>
1362         * <p>
1363         * This method appends the end of data indicator, and can only be called
1364         * once. Use {@link #getStringBuffer} to get the current string state.
1365         * </p>
1366         * <p>
1367         * If the object is <code>null</code>, return the style's
1368         * <code>nullText</code>
1369         * </p>
1370         * 
1371         * @return the String <code>toString</code>
1372         */
1373        public String toString()
1374        {
1375            if ( this.getObject() == null )
1376            {
1377                this.getStringBuffer().append( this.getStyle().getNullText() );
1378            }
1379            else
1380            {
1381                style.appendEnd( this.getStringBuffer(), this.getObject() );
1382            }
1383            return this.getStringBuffer().toString();
1384        }
1385    
1386    }