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.logging.log4j.core.util.datetime;
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 * </p>
033 *
034 * <p>
035 * Copied and modified from <a href="https://commons.apache.org/proper/commons-lang/">Apache Commons Lang</a>.
036 * </p>
037 *
038 * @since Apache Commons Lang 3.2
039 */
040public interface DatePrinter {
041
042    /**
043     * <p>Formats a millisecond {@code long} value.</p>
044     *
045     * @param millis  the millisecond value to format
046     * @return the formatted string
047     * @since 2.1
048     */
049    String format(long millis);
050
051    /**
052     * <p>Formats a {@code Date} object using a {@code GregorianCalendar}.</p>
053     *
054     * @param date  the date to format
055     * @return the formatted string
056     */
057    String format(Date date);
058
059    /**
060     * <p>Formats a {@code Calendar} object.</p>
061     * The TimeZone set on the Calendar is only used to adjust the time offset.
062     * The TimeZone specified during the construction of the Parser will determine the TimeZone
063     * used in the formatted string.
064     *
065     * @param calendar  the calendar to format.
066     * @return the formatted string
067     */
068    String format(Calendar calendar);
069
070    /**
071     * <p>Formats a millisecond {@code long} value into the
072     * supplied {@code Appendable}.</p>
073     *
074     * @param millis  the millisecond value to format
075     * @param buf  the buffer to format into
076     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
077     * @return the specified string buffer
078     * @since 3.5
079     */
080    <B extends Appendable> B format(long millis, B buf);
081
082    /**
083     * <p>Formats a {@code Date} object into the
084     * supplied {@code Appendable} using a {@code GregorianCalendar}.</p>
085     *
086     * @param date  the date to format
087     * @param buf  the buffer to format into
088     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
089     * @return the specified string buffer
090     * @since 3.5
091     */
092    <B extends Appendable> B format(Date date, B buf);
093
094    /**
095     * <p>Formats a {@code Calendar} object into the supplied {@code Appendable}.</p>
096     * The TimeZone set on the Calendar is only used to adjust the time offset.
097     * The TimeZone specified during the construction of the Parser will determine the TimeZone
098     * used in the formatted string.
099     *
100     * @param calendar  the calendar to format
101     * @param buf  the buffer to format into
102     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
103     * @return the specified string buffer
104     * @since 3.5
105     */
106    <B extends Appendable> B format(Calendar calendar, B buf);
107
108
109    // Accessors
110    //-----------------------------------------------------------------------
111    /**
112     * <p>Gets the pattern used by this printer.</p>
113     *
114     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
115     */
116    String getPattern();
117
118    /**
119     * <p>Gets the time zone used by this printer.</p>
120     *
121     * <p>This zone is always used for {@code Date} printing. </p>
122     *
123     * @return the time zone
124     */
125    TimeZone getTimeZone();
126
127    /**
128     * <p>Gets the locale used by this printer.</p>
129     *
130     * @return the locale
131     */
132    Locale getLocale();
133
134    /**
135     * <p>Formats a {@code Date}, {@code Calendar} or
136     * {@code Long} (milliseconds) object.</p>
137     *
138     * @param obj  the object to format
139     * @param toAppendTo  the buffer to append to
140     * @param pos  the position - ignored
141     * @return the buffer passed in
142     * @see java.text.DateFormat#format(Object, StringBuffer, FieldPosition)
143     */
144    StringBuilder format(Object obj, StringBuilder toAppendTo, FieldPosition pos);
145}