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.Locale;
023import java.util.TimeZone;
024
025/**
026 * DatePrinter is the "missing" interface for the format methods of 
027 * {@link java.text.DateFormat}. You can obtain an object implementing this
028 * interface by using one of the FastDateFormat factory methods.
029 * <p>
030 * Warning: Since binary compatible methods may be added to this interface in any
031 * release, developers are not expected to implement this interface.
032 * 
033 * @since 3.2
034 */
035public interface DatePrinter {
036
037    /**
038     * <p>Formats a millisecond {@code long} value.</p>
039     *
040     * @param millis  the millisecond value to format
041     * @return the formatted string
042     * @since 2.1
043     */
044    String format(long millis);
045
046    /**
047     * <p>Formats a {@code Date} object using a {@code GregorianCalendar}.</p>
048     *
049     * @param date  the date to format
050     * @return the formatted string
051     */
052    String format(Date date);
053
054    /**
055     * <p>Formats a {@code Calendar} object.</p>
056     * The TimeZone set on the Calendar is only used to adjust the time offset.
057     * The TimeZone specified during the construction of the Parser will determine the TimeZone
058     * used in the formatted string.
059     *
060     * @param calendar  the calendar to format.
061     * @return the formatted string
062     */
063    String format(Calendar calendar);
064
065    /**
066     * <p>Formats a millisecond {@code long} value into the
067     * supplied {@code StringBuffer}.</p>
068     *
069     * @param millis  the millisecond value to format
070     * @param buf  the buffer to format into
071     * @return the specified string buffer
072     * @deprecated Use {{@link #format(long, Appendable)}.
073     */
074    @Deprecated
075    StringBuffer format(long millis, StringBuffer buf);
076
077    /**
078     * <p>Formats a {@code Date} object into the
079     * supplied {@code StringBuffer} using a {@code GregorianCalendar}.</p>
080     *
081     * @param date  the date to format
082     * @param buf  the buffer to format into
083     * @return the specified string buffer
084     * @deprecated Use {{@link #format(Date, Appendable)}.
085     */
086    @Deprecated
087    StringBuffer format(Date date, StringBuffer buf);
088
089    /**
090     * <p>Formats a {@code Calendar} object into the supplied {@code StringBuffer}.</p>
091     * The TimeZone set on the Calendar is only used to adjust the time offset.
092     * The TimeZone specified during the construction of the Parser will determine the TimeZone
093     * used in the formatted string.
094     *
095     * @param calendar  the calendar to format
096     * @param buf  the buffer to format into
097     * @return the specified string buffer
098     * @deprecated Use {{@link #format(Calendar, Appendable)}.
099     */
100    @Deprecated
101    StringBuffer format(Calendar calendar, StringBuffer buf);
102
103    /**
104     * <p>Formats a millisecond {@code long} value into the
105     * supplied {@code Appendable}.</p>
106     *
107     * @param millis  the millisecond value to format
108     * @param buf  the buffer to format into
109     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
110     * @return the specified string buffer
111     * @since 3.5
112     */
113    <B extends Appendable> B format(long millis, B buf);
114
115    /**
116     * <p>Formats a {@code Date} object into the
117     * supplied {@code Appendable} using a {@code GregorianCalendar}.</p>
118     *
119     * @param date  the date to format
120     * @param buf  the buffer to format into
121     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
122     * @return the specified string buffer
123     * @since 3.5
124     */
125    <B extends Appendable> B format(Date date, B buf);
126
127    /**
128     * <p>Formats a {@code Calendar} object into the supplied {@code Appendable}.</p>
129     * The TimeZone set on the Calendar is only used to adjust the time offset.
130     * The TimeZone specified during the construction of the Parser will determine the TimeZone
131     * used in the formatted string.
132     *
133     * @param calendar  the calendar to format
134     * @param buf  the buffer to format into
135     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
136     * @return the specified string buffer
137     * @since 3.5
138     */
139    <B extends Appendable> B format(Calendar calendar, B buf);
140
141
142    // Accessors
143    //-----------------------------------------------------------------------
144    /**
145     * <p>Gets the pattern used by this printer.</p>
146     *
147     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
148     */
149    String getPattern();
150
151    /**
152     * <p>Gets the time zone used by this printer.</p>
153     *
154     * <p>This zone is always used for {@code Date} printing. </p>
155     *
156     * @return the time zone
157     */
158    TimeZone getTimeZone();
159
160    /**
161     * <p>Gets the locale used by this printer.</p>
162     *
163     * @return the locale
164     */
165    Locale getLocale();
166
167    /**
168     * <p>Formats a {@code Date}, {@code Calendar} or
169     * {@code Long} (milliseconds) object.</p>
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}