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 * <p>DatePrinter is the "missing" interface for the format methods of 
027 * {@link java.text.DateFormat}.</p>
028 * 
029 * @since 3.2
030 */
031public interface DatePrinter {
032
033    /**
034     * <p>Formats a millisecond {@code long} value.</p>
035     *
036     * @param millis  the millisecond value to format
037     * @return the formatted string
038     * @since 2.1
039     */
040    String format(long millis);
041
042    /**
043     * <p>Formats a {@code Date} object using a {@code GregorianCalendar}.</p>
044     *
045     * @param date  the date to format
046     * @return the formatted string
047     */
048    String format(Date date);
049
050    /**
051     * <p>Formats a {@code Calendar} object.</p>
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 StringBuffer}.</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    StringBuffer format(long millis, StringBuffer buf);
067
068    /**
069     * <p>Formats a {@code Date} object into the
070     * supplied {@code StringBuffer} 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    StringBuffer format(Date date, StringBuffer buf);
077
078    /**
079     * <p>Formats a {@code Calendar} object into the
080     * supplied {@code StringBuffer}.</p>
081     *
082     * @param calendar  the calendar to format
083     * @param buf  the buffer to format into
084     * @return the specified string buffer
085     */
086    StringBuffer format(Calendar calendar, StringBuffer buf);
087
088    // Accessors
089    //-----------------------------------------------------------------------
090    /**
091     * <p>Gets the pattern used by this printer.</p>
092     *
093     * @return the pattern, {@link java.text.SimpleDateFormat} compatible
094     */
095    String getPattern();
096
097    /**
098     * <p>Gets the time zone used by this printer.</p>
099     *
100     * <p>This zone is always used for {@code Date} printing. </p>
101     *
102     * @return the time zone
103     */
104    TimeZone getTimeZone();
105
106    /**
107     * <p>Gets the locale used by this printer.</p>
108     *
109     * @return the locale
110     */
111    Locale getLocale();
112
113    /**
114     * <p>Formats a {@code Date}, {@code Calendar} or
115     * {@code Long} (milliseconds) object.</p>
116     * 
117     * See {@link java.text.DateFormat#format(Object, StringBuffer, FieldPosition)}
118     * 
119     * @param obj  the object to format
120     * @param toAppendTo  the buffer to append to
121     * @param pos  the position - ignored
122     * @return the buffer passed in
123     */
124    StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos);
125}