001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.time;
018
019import java.text.FieldPosition;
020import java.util.Calendar;
021import java.util.Date;
022import java.util.GregorianCalendar;
023import java.util.Locale;
024import java.util.TimeZone;
025
026/**
027 * DatePrinter is the "missing" interface for the format methods of
028 * {@link java.text.DateFormat}. You can obtain an object implementing this
029 * interface by using one of the FastDateFormat factory methods.
030 * <p>
031 * Warning: Since binary compatible methods may be added to this interface in any
032 * release, developers are not expected to implement this interface.
033 *
034 * @since 3.2
035 */
036public interface DatePrinter {
037
038    /**
039     * Formats a millisecond {@code long} value.
040     *
041     * @param millis  the millisecond value to format
042     * @return the formatted string
043     * @since 2.1
044     */
045    String format(long millis);
046
047    /**
048     * Formats a {@link Date} object using a {@link GregorianCalendar}.
049     *
050     * @param date  the date to format
051     * @return the formatted string
052     */
053    String format(Date date);
054
055    /**
056     * Formats a {@link Calendar} object.
057     * The TimeZone set on the Calendar is only used to adjust the time offset.
058     * The TimeZone specified during the construction of the Parser will determine the TimeZone
059     * used in the formatted string.
060     *
061     * @param calendar  the calendar to format.
062     * @return the formatted string
063     */
064    String format(Calendar calendar);
065
066    /**
067     * Formats a millisecond {@code long} value into the
068     * supplied {@link StringBuffer}.
069     *
070     * @param millis  the millisecond value to format
071     * @param buf  the buffer to format into
072     * @return the specified string buffer
073     * @deprecated Use {{@link #format(long, Appendable)}.
074     */
075    @Deprecated
076    StringBuffer format(long millis, StringBuffer buf);
077
078    /**
079     * Formats a {@link Date} object into the
080     * supplied {@link StringBuffer} using a {@link GregorianCalendar}.
081     *
082     * @param date  the date to format
083     * @param buf  the buffer to format into
084     * @return the specified string buffer
085     * @deprecated Use {{@link #format(Date, Appendable)}.
086     */
087    @Deprecated
088    StringBuffer format(Date date, StringBuffer buf);
089
090    /**
091     * Formats a {@link Calendar} object into the supplied {@link StringBuffer}.
092     * The TimeZone set on the Calendar is only used to adjust the time offset.
093     * The TimeZone specified during the construction of the Parser will determine the TimeZone
094     * used in the formatted string.
095     *
096     * @param calendar  the calendar to format
097     * @param buf  the buffer to format into
098     * @return the specified string buffer
099     * @deprecated Use {{@link #format(Calendar, Appendable)}.
100     */
101    @Deprecated
102    StringBuffer format(Calendar calendar, StringBuffer buf);
103
104    /**
105     * Formats a millisecond {@code long} value into the
106     * supplied {@link Appendable}.
107     *
108     * @param millis  the millisecond value to format
109     * @param buf  the buffer to format into
110     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
111     * @return the specified string buffer
112     * @since 3.5
113     */
114    <B extends Appendable> B format(long millis, B buf);
115
116    /**
117     * Formats a {@link Date} object into the
118     * supplied {@link Appendable} using a {@link GregorianCalendar}.
119     *
120     * @param date  the date to format
121     * @param buf  the buffer to format into
122     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
123     * @return the specified string buffer
124     * @since 3.5
125     */
126    <B extends Appendable> B format(Date date, B buf);
127
128    /**
129     * Formats a {@link Calendar} object into the supplied {@link Appendable}.
130     * The TimeZone set on the Calendar is only used to adjust the time offset.
131     * The TimeZone specified during the construction of the Parser will determine the TimeZone
132     * used in the formatted string.
133     *
134     * @param calendar  the calendar to format
135     * @param buf  the buffer to format into
136     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
137     * @return the specified string buffer
138     * @since 3.5
139     */
140    <B extends Appendable> B format(Calendar calendar, B buf);
141
142
143    // Accessors
144    /**
145     * Gets the pattern used by this printer.
146     *
147     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
148     */
149    String getPattern();
150
151    /**
152     * Gets the time zone used by this printer.
153     *
154     * <p>This zone is always used for {@link Date} printing.</p>
155     *
156     * @return the time zone
157     */
158    TimeZone getTimeZone();
159
160    /**
161     * Gets the locale used by this printer.
162     *
163     * @return the locale
164     */
165    Locale getLocale();
166
167    /**
168     * Formats a {@link Date}, {@link Calendar} or
169     * {@link Long} (milliseconds) object.
170     *
171     * @param obj  the object to format
172     * @param toAppendTo  the buffer to append to
173     * @param pos  the position - ignored
174     * @return the buffer passed in
175     * @see java.text.DateFormat#format(Object, StringBuffer, FieldPosition)
176     */
177    StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos);
178}