001    /*
002     *  Copyright 2001-2005 Stephen Colebourne
003     *
004     *  Licensed under the Apache License, Version 2.0 (the "License");
005     *  you may not use this file except in compliance with the License.
006     *  You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     *  Unless required by applicable law or agreed to in writing, software
011     *  distributed under the License is distributed on an "AS IS" BASIS,
012     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     *  See the License for the specific language governing permissions and
014     *  limitations under the License.
015     */
016    package org.joda.time.format;
017    
018    import java.io.IOException;
019    import java.io.Writer;
020    import java.util.Locale;
021    
022    import org.joda.time.Chronology;
023    import org.joda.time.DateTimeZone;
024    import org.joda.time.ReadablePartial;
025    
026    /**
027     * Internal interface for creating textual representations of datetimes.
028     * <p>
029     * Application users will rarely use this class directly. Instead, you
030     * will use one of the factory classes to create a {@link DateTimeFormatter}.
031     * <p>
032     * The factory classes are:<br />
033     * - {@link DateTimeFormatterBuilder}<br />
034     * - {@link DateTimeFormat}<br />
035     * - {@link ISODateTimeFormat}<br />
036     *
037     * @author Brian S O'Neill
038     * @author Stephen Colebourne
039     * @see DateTimeFormatterBuilder
040     * @see DateTimeFormat
041     * @see ISODateTimeFormat
042     * @since 1.0
043     */
044    public interface DateTimePrinter {
045    
046        /**
047         * Returns the expected maximum number of characters produced.
048         * The actual amount should rarely exceed this estimate.
049         * 
050         * @return the estimated length
051         */
052        int estimatePrintedLength();
053    
054        //-----------------------------------------------------------------------
055        /**
056         * Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
057         * using the given Chronology.
058         *
059         * @param buf  formatted instant is appended to this buffer, not null
060         * @param instant  millis since 1970-01-01T00:00:00Z
061         * @param chrono  the chronology to use, not null
062         * @param displayOffset  if a time zone offset is printed, force it to use
063         * this millisecond value
064         * @param displayZone  the time zone to use, null means local time
065         * @param locale  the locale to use, null means default locale
066         */
067        void printTo(StringBuffer buf, long instant, Chronology chrono,
068                     int displayOffset, DateTimeZone displayZone, Locale locale);
069    
070        /**
071         * Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
072         * using the given Chronology.
073         *
074         * @param out  formatted instant is written out
075         * @param instant  millis since 1970-01-01T00:00:00Z
076         * @param chrono  the chronology to use, not null
077         * @param displayOffset  if a time zone offset is printed, force it to use
078         * this millisecond value
079         * @param displayZone  the time zone to use, null means local time
080         * @param locale  the locale to use, null means default locale
081         */
082        void printTo(Writer out, long instant, Chronology chrono,
083                     int displayOffset, DateTimeZone displayZone, Locale locale) throws IOException;
084    
085        //-----------------------------------------------------------------------
086        /**
087         * Prints a ReadablePartial.
088         *
089         * @param buf  formatted partial is appended to this buffer, not null
090         * @param partial  partial to format, not null
091         * @param locale  the locale to use, null means default locale
092         */
093        void printTo(StringBuffer buf, ReadablePartial partial, Locale locale);
094    
095        /**
096         * Prints a ReadablePartial.
097         *
098         * @param out  formatted partial is written out, not null
099         * @param partial  partial to format, not null
100         * @param locale  the locale to use, null means default locale
101         */
102        void printTo(Writer out, ReadablePartial partial, Locale locale) throws IOException;
103    
104    }