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 {@link Calendar} object.
040     * The TimeZone set on the Calendar is only used to adjust the time offset.
041     * The TimeZone specified during the construction of the Parser will determine the TimeZone
042     * used in the formatted string.
043     *
044     * @param calendar  the calendar to format.
045     * @return the formatted string
046     */
047    String format(Calendar calendar);
048
049    /**
050     * Formats a {@link Calendar} object into the supplied {@link Appendable}.
051     * The TimeZone set on the Calendar is only used to adjust the time offset.
052     * The TimeZone specified during the construction of the Parser will determine the TimeZone
053     * used in the formatted string.
054     *
055     * @param calendar  the calendar to format
056     * @param buf  the buffer to format into
057     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
058     * @return the specified string buffer
059     * @since 3.5
060     */
061    <B extends Appendable> B format(Calendar calendar, B buf);
062
063    /**
064     * Formats a {@link Calendar} object into the supplied {@link StringBuffer}.
065     * The TimeZone set on the Calendar is only used to adjust the time offset.
066     * The TimeZone specified during the construction of the Parser will determine the TimeZone
067     * used in the formatted string.
068     *
069     * @param calendar  the calendar to format
070     * @param buf  the buffer to format into
071     * @return the specified string buffer
072     * @deprecated Use {{@link #format(Calendar, Appendable)}.
073     */
074    @Deprecated
075    StringBuffer format(Calendar calendar, StringBuffer buf);
076
077    /**
078     * Formats a {@link Date} object using a {@link GregorianCalendar}.
079     *
080     * @param date  the date to format
081     * @return the formatted string
082     */
083    String format(Date date);
084
085    /**
086     * Formats a {@link Date} object into the
087     * supplied {@link Appendable} using a {@link GregorianCalendar}.
088     *
089     * @param date  the date to format
090     * @param buf  the buffer to format into
091     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
092     * @return the specified string buffer
093     * @since 3.5
094     */
095    <B extends Appendable> B format(Date date, B buf);
096
097    /**
098     * Formats a {@link Date} object into the
099     * supplied {@link StringBuffer} using a {@link GregorianCalendar}.
100     *
101     * @param date  the date to format
102     * @param buf  the buffer to format into
103     * @return the specified string buffer
104     * @deprecated Use {{@link #format(Date, Appendable)}.
105     */
106    @Deprecated
107    StringBuffer format(Date date, StringBuffer buf);
108
109    /**
110     * Formats a millisecond {@code long} value.
111     *
112     * @param millis  the millisecond value to format
113     * @return the formatted string
114     * @since 2.1
115     */
116    String format(long millis);
117
118    /**
119     * Formats a millisecond {@code long} value into the
120     * supplied {@link Appendable}.
121     *
122     * @param millis  the millisecond value to format
123     * @param buf  the buffer to format into
124     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
125     * @return the specified string buffer
126     * @since 3.5
127     */
128    <B extends Appendable> B format(long millis, B buf);
129
130    /**
131     * Formats a millisecond {@code long} value into the
132     * supplied {@link StringBuffer}.
133     *
134     * @param millis  the millisecond value to format
135     * @param buf  the buffer to format into
136     * @return the specified string buffer
137     * @deprecated Use {{@link #format(long, Appendable)}.
138     */
139    @Deprecated
140    StringBuffer format(long millis, StringBuffer buf);
141
142    /**
143     * Formats a {@link Date}, {@link Calendar} or
144     * {@link Long} (milliseconds) object.
145     *
146     * @param obj  the object to format
147     * @param toAppendTo  the buffer to append to
148     * @param pos  the position - ignored
149     * @return the buffer passed in
150     * @see java.text.DateFormat#format(Object, StringBuffer, FieldPosition)
151     */
152    StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos);
153
154    /**
155     * Gets the locale used by this printer.
156     *
157     * @return the locale
158     */
159    Locale getLocale();
160
161    // Accessors
162    /**
163     * Gets the pattern used by this printer.
164     *
165     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
166     */
167    String getPattern();
168
169    /**
170     * Gets the time zone used by this printer.
171     *
172     * <p>This zone is always used for {@link Date} printing.</p>
173     *
174     * @return the time zone
175     */
176    TimeZone getTimeZone();
177}