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 * 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 * 033 * @since 3.2 034 */ 035public interface DatePrinter { 036 037 /** 038 * <p>Formats a millisecond {@code long} value.</p> 039 * 040 * @param millis the millisecond value to format 041 * @return the formatted string 042 * @since 2.1 043 */ 044 String format(long millis); 045 046 /** 047 * <p>Formats a {@code Date} object using a {@code GregorianCalendar}.</p> 048 * 049 * @param date the date to format 050 * @return the formatted string 051 */ 052 String format(Date date); 053 054 /** 055 * <p>Formats a {@code Calendar} object.</p> 056 * The TimeZone set on the Calendar is only used to adjust the time offset. 057 * The TimeZone specified during the construction of the Parser will determine the TimeZone 058 * used in the formatted string. 059 * 060 * @param calendar the calendar to format. 061 * @return the formatted string 062 */ 063 String format(Calendar calendar); 064 065 /** 066 * <p>Formats a millisecond {@code long} value into the 067 * supplied {@code StringBuffer}.</p> 068 * 069 * @param millis the millisecond value to format 070 * @param buf the buffer to format into 071 * @return the specified string buffer 072 * @deprecated Use {{@link #format(long, Appendable)}. 073 */ 074 @Deprecated 075 StringBuffer format(long millis, StringBuffer buf); 076 077 /** 078 * <p>Formats a {@code Date} object into the 079 * supplied {@code StringBuffer} using a {@code GregorianCalendar}.</p> 080 * 081 * @param date the date to format 082 * @param buf the buffer to format into 083 * @return the specified string buffer 084 * @deprecated Use {{@link #format(Date, Appendable)}. 085 */ 086 @Deprecated 087 StringBuffer format(Date date, StringBuffer buf); 088 089 /** 090 * <p>Formats a {@code Calendar} object into the supplied {@code StringBuffer}.</p> 091 * The TimeZone set on the Calendar is only used to adjust the time offset. 092 * The TimeZone specified during the construction of the Parser will determine the TimeZone 093 * used in the formatted string. 094 * 095 * @param calendar the calendar to format 096 * @param buf the buffer to format into 097 * @return the specified string buffer 098 * @deprecated Use {{@link #format(Calendar, Appendable)}. 099 */ 100 @Deprecated 101 StringBuffer format(Calendar calendar, StringBuffer buf); 102 103 /** 104 * <p>Formats a millisecond {@code long} value into the 105 * supplied {@code Appendable}.</p> 106 * 107 * @param millis the millisecond value to format 108 * @param buf the buffer to format into 109 * @param <B> the Appendable class type, usually StringBuilder or StringBuffer. 110 * @return the specified string buffer 111 * @since 3.5 112 */ 113 <B extends Appendable> B format(long millis, B buf); 114 115 /** 116 * <p>Formats a {@code Date} object into the 117 * supplied {@code Appendable} using a {@code GregorianCalendar}.</p> 118 * 119 * @param date the date to format 120 * @param buf the buffer to format into 121 * @param <B> the Appendable class type, usually StringBuilder or StringBuffer. 122 * @return the specified string buffer 123 * @since 3.5 124 */ 125 <B extends Appendable> B format(Date date, B buf); 126 127 /** 128 * <p>Formats a {@code Calendar} object into the supplied {@code Appendable}.</p> 129 * The TimeZone set on the Calendar is only used to adjust the time offset. 130 * The TimeZone specified during the construction of the Parser will determine the TimeZone 131 * used in the formatted string. 132 * 133 * @param calendar the calendar to format 134 * @param buf the buffer to format into 135 * @param <B> the Appendable class type, usually StringBuilder or StringBuffer. 136 * @return the specified string buffer 137 * @since 3.5 138 */ 139 <B extends Appendable> B format(Calendar calendar, B buf); 140 141 142 // Accessors 143 //----------------------------------------------------------------------- 144 /** 145 * <p>Gets the pattern used by this printer.</p> 146 * 147 * @return the pattern, {@link java.text.SimpleDateFormat} compatible 148 */ 149 String getPattern(); 150 151 /** 152 * <p>Gets the time zone used by this printer.</p> 153 * 154 * <p>This zone is always used for {@code Date} printing. </p> 155 * 156 * @return the time zone 157 */ 158 TimeZone getTimeZone(); 159 160 /** 161 * <p>Gets the locale used by this printer.</p> 162 * 163 * @return the locale 164 */ 165 Locale getLocale(); 166 167 /** 168 * <p>Formats a {@code Date}, {@code Calendar} or 169 * {@code Long} (milliseconds) object.</p> 170 * 171 * @param obj the object to format 172 * @param toAppendTo the buffer to append to 173 * @param pos the position - ignored 174 * @return the buffer passed in 175 * @see java.text.DateFormat#format(Object, StringBuffer, FieldPosition) 176 */ 177 StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos); 178}