    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 *      https://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}