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 */
016package org.joda.time.format;
017
018import java.io.IOException;
019import java.io.Writer;
020import java.util.Locale;
021
022import org.joda.time.Chronology;
023import org.joda.time.DateTimeZone;
024import 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 */
044public 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}