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 * Copied from Commons Lang 3.
027 */
028public interface DatePrinter {
029
030    /**
031     * <p>Formats a millisecond {@code long} value.</p>
032     *
033     * @param millis  the millisecond value to format
034     * @return the formatted string
035     * @since 2.1
036     */
037    String format(long millis);
038
039    /**
040     * <p>Formats a {@code Date} object using a {@code GregorianCalendar}.</p>
041     *
042     * @param date  the date to format
043     * @return the formatted string
044     */
045    String format(Date date);
046
047    /**
048     * <p>Formats a {@code Calendar} object.</p>
049     * The TimeZone set on the Calendar is only used to adjust the time offset.
050     * The TimeZone specified during the construction of the Parser will determine the TimeZone
051     * used in the formatted string.
052     *
053     * @param calendar  the calendar to format.
054     * @return the formatted string
055     */
056    String format(Calendar calendar);
057
058    /**
059     * <p>Formats a milliseond {@code long} value into the
060     * supplied {@code StringBuilder}.</p>
061     *
062     * @param millis  the millisecond value to format
063     * @param buf  the buffer to format into
064     * @return the specified string buffer
065     */
066    StringBuilder format(long millis, StringBuilder buf);
067
068    /**
069     * <p>Formats a {@code Date} object into the
070     * supplied {@code StringBuilder} using a {@code GregorianCalendar}.</p>
071     *
072     * @param date  the date to format
073     * @param buf  the buffer to format into
074     * @return the specified string buffer
075     */
076    StringBuilder format(Date date, StringBuilder buf);
077
078    /**
079     * <p>Formats a {@code Calendar} object into the supplied {@code StringBuilder}.</p>
080     * The TimeZone set on the Calendar is only used to adjust the time offset.
081     * The TimeZone specified during the construction of the Parser will determine the TimeZone
082     * used in the formatted string.
083     *
084     * @param calendar  the calendar to format
085     * @param buf  the buffer to format into
086     * @return the specified string buffer
087     */
088    StringBuilder format(Calendar calendar, StringBuilder buf);
089
090    // Accessors
091    //-----------------------------------------------------------------------
092    /**
093     * <p>Gets the pattern used by this printer.</p>
094     *
095     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
096     */
097    String getPattern();
098
099    /**
100     * <p>Gets the time zone used by this printer.</p>
101     *
102     * <p>This zone is always used for {@code Date} printing. </p>
103     *
104     * @return the time zone
105     */
106    TimeZone getTimeZone();
107
108    /**
109     * <p>Gets the locale used by this printer.</p>
110     *
111     * @return the locale
112     */
113    Locale getLocale();
114
115    /**
116     * <p>Formats a {@code Date}, {@code Calendar} or
117     * {@code Long} (milliseconds) object.</p>
118     * 
119     * See {@link java.text.DateFormat#format(Object, StringBuffer, FieldPosition)}
120     * 
121     * @param obj  the object to format
122     * @param toAppendTo  the buffer to append to
123     * @param pos  the position - ignored
124     * @return the buffer passed in
125     */
126    StringBuilder format(Object obj, StringBuilder toAppendTo, FieldPosition pos);
127}