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 }