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 }