1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.lang3.time; 18 19 import java.text.FieldPosition; 20 import java.util.Calendar; 21 import java.util.Date; 22 import java.util.GregorianCalendar; 23 import java.util.Locale; 24 import java.util.TimeZone; 25 26 /** 27 * DatePrinter is the "missing" interface for the format methods of 28 * {@link java.text.DateFormat}. You can obtain an object implementing this 29 * interface by using one of the FastDateFormat factory methods. 30 * <p> 31 * Warning: Since binary compatible methods may be added to this interface in any 32 * release, developers are not expected to implement this interface. 33 * 34 * @since 3.2 35 */ 36 public interface DatePrinter { 37 38 /** 39 * Formats a millisecond {@code long} value. 40 * 41 * @param millis the millisecond value to format 42 * @return the formatted string 43 * @since 2.1 44 */ format(long millis)45 String format(long millis); 46 47 /** 48 * Formats a {@link Date} object using a {@link GregorianCalendar}. 49 * 50 * @param date the date to format 51 * @return the formatted string 52 */ format(Date date)53 String format(Date date); 54 55 /** 56 * Formats a {@link Calendar} object. 57 * The TimeZone set on the Calendar is only used to adjust the time offset. 58 * The TimeZone specified during the construction of the Parser will determine the TimeZone 59 * used in the formatted string. 60 * 61 * @param calendar the calendar to format. 62 * @return the formatted string 63 */ format(Calendar calendar)64 String format(Calendar calendar); 65 66 /** 67 * Formats a millisecond {@code long} value into the 68 * supplied {@link StringBuffer}. 69 * 70 * @param millis the millisecond value to format 71 * @param buf the buffer to format into 72 * @return the specified string buffer 73 * @deprecated Use {{@link #format(long, Appendable)}. 74 */ 75 @Deprecated format(long millis, StringBuffer buf)76 StringBuffer format(long millis, StringBuffer buf); 77 78 /** 79 * Formats a {@link Date} object into the 80 * supplied {@link StringBuffer} using a {@link GregorianCalendar}. 81 * 82 * @param date the date to format 83 * @param buf the buffer to format into 84 * @return the specified string buffer 85 * @deprecated Use {{@link #format(Date, Appendable)}. 86 */ 87 @Deprecated format(Date date, StringBuffer buf)88 StringBuffer format(Date date, StringBuffer buf); 89 90 /** 91 * Formats a {@link Calendar} object into the supplied {@link StringBuffer}. 92 * The TimeZone set on the Calendar is only used to adjust the time offset. 93 * The TimeZone specified during the construction of the Parser will determine the TimeZone 94 * used in the formatted string. 95 * 96 * @param calendar the calendar to format 97 * @param buf the buffer to format into 98 * @return the specified string buffer 99 * @deprecated Use {{@link #format(Calendar, Appendable)}. 100 */ 101 @Deprecated format(Calendar calendar, StringBuffer buf)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 */ format(long millis, B buf)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 */ format(Date date, B buf)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 */ format(Calendar calendar, B buf)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 */ getPattern()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 */ getTimeZone()158 TimeZone getTimeZone(); 159 160 /** 161 * Gets the locale used by this printer. 162 * 163 * @return the locale 164 */ getLocale()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 */ format(Object obj, StringBuffer toAppendTo, FieldPosition pos)177 StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos); 178 } 179