1 /*
2 * Copyright 2001-2005 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.time.format;
17
18 import java.io.IOException;
19 import java.io.Writer;
20 import java.util.Locale;
21
22 import org.joda.time.Chronology;
23 import org.joda.time.DateTimeZone;
24 import org.joda.time.ReadablePartial;
25
26 /**
27 * Internal interface for creating textual representations of datetimes.
28 * <p>
29 * Application users will rarely use this class directly. Instead, you
30 * will use one of the factory classes to create a {@link DateTimeFormatter}.
31 * <p>
32 * The factory classes are:<br />
33 * - {@link DateTimeFormatterBuilder}<br />
34 * - {@link DateTimeFormat}<br />
35 * - {@link ISODateTimeFormat}<br />
36 *
37 * @author Brian S O'Neill
38 * @author Stephen Colebourne
39 * @see DateTimeFormatterBuilder
40 * @see DateTimeFormat
41 * @see ISODateTimeFormat
42 * @since 1.0
43 */
44 public interface DateTimePrinter {
45
46 /**
47 * Returns the expected maximum number of characters produced.
48 * The actual amount should rarely exceed this estimate.
49 *
50 * @return the estimated length
51 */
52 int estimatePrintedLength();
53
54 //-----------------------------------------------------------------------
55 /**
56 * Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
57 * using the given Chronology.
58 *
59 * @param buf formatted instant is appended to this buffer, not null
60 * @param instant millis since 1970-01-01T00:00:00Z
61 * @param chrono the chronology to use, not null
62 * @param displayOffset if a time zone offset is printed, force it to use
63 * this millisecond value
64 * @param displayZone the time zone to use, null means local time
65 * @param locale the locale to use, null means default locale
66 */
67 void printTo(StringBuffer buf, long instant, Chronology chrono,
68 int displayOffset, DateTimeZone displayZone, Locale locale);
69
70 /**
71 * Prints an instant from milliseconds since 1970-01-01T00:00:00Z,
72 * using the given Chronology.
73 *
74 * @param out formatted instant is written out
75 * @param instant millis since 1970-01-01T00:00:00Z
76 * @param chrono the chronology to use, not null
77 * @param displayOffset if a time zone offset is printed, force it to use
78 * this millisecond value
79 * @param displayZone the time zone to use, null means local time
80 * @param locale the locale to use, null means default locale
81 */
82 void printTo(Writer out, long instant, Chronology chrono,
83 int displayOffset, DateTimeZone displayZone, Locale locale) throws IOException;
84
85 //-----------------------------------------------------------------------
86 /**
87 * Prints a ReadablePartial.
88 *
89 * @param buf formatted partial is appended to this buffer, not null
90 * @param partial partial to format, not null
91 * @param locale the locale to use, null means default locale
92 */
93 void printTo(StringBuffer buf, ReadablePartial partial, Locale locale);
94
95 /**
96 * Prints a ReadablePartial.
97 *
98 * @param out formatted partial is written out, not null
99 * @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 }