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)
084: throws IOException;
085:
086: //-----------------------------------------------------------------------
087: /**
088: * Prints a ReadablePartial.
089: *
090: * @param buf formatted partial is appended to this buffer, not null
091: * @param partial partial to format, not null
092: * @param locale the locale to use, null means default locale
093: */
094: void printTo(StringBuffer buf, ReadablePartial partial,
095: Locale locale);
096:
097: /**
098: * Prints a ReadablePartial.
099: *
100: * @param out formatted partial is written out, not null
101: * @param partial partial to format, not null
102: * @param locale the locale to use, null means default locale
103: */
104: void printTo(Writer out, ReadablePartial partial, Locale locale)
105: throws IOException;
106:
107: }
|