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