    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    /**
    144     * Formats a {@link Date}, {@link Calendar} or
    145     * {@link Long} (milliseconds) object.
    146     *
    147     * @param obj  the object to format
    148     * @param toAppendTo  the buffer to append to
    149     * @param pos  the position - ignored
    150     * @return the buffer passed in
    151     * @see java.text.DateFormat#format(Object, StringBuffer, FieldPosition)
    152     */
    153    StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos);
    154
    155    /**
    156     * Gets the locale used by this printer.
    157     *
    158     * @return the locale
    159     */
    160    Locale getLocale();
    161
    162    // Accessors
    163    /**
    164     * Gets the pattern used by this printer.
    165     *
    166     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
    167     */
    168    String getPattern();
    169
    170    /**
    171     * Gets the time zone used by this printer.
    172     *
    173     * <p>This zone is always used for {@link Date} printing.</p>
    174     *
    175     * @return the time zone
    176     */
    177    TimeZone getTimeZone();
    178}