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 */
017 package org.apache.commons.lang3.time;
018
019 import java.util.Calendar;
020 import java.util.Date;
021 import java.util.Locale;
022 import java.util.TimeZone;
023
024 /**
025 * <p>Date and time formatting utilities and constants.</p>
026 *
027 * <p>Formatting is performed using the thread-safe
028 * {@link org.apache.commons.lang3.time.FastDateFormat} class.</p>
029 *
030 * @since 2.0
031 * @version $Id: DateFormatUtils.java 1088899 2011-04-05 05:31:27Z bayard $
032 */
033 public class DateFormatUtils {
034
035 /**
036 * The UTC time zone (often referred to as GMT).
037 * This is private as it is mutable.
038 */
039 private static final TimeZone UTC_TIME_ZONE = TimeZone.getTimeZone("GMT");
040 /**
041 * ISO8601 formatter for date-time without time zone.
042 * The format used is <tt>yyyy-MM-dd'T'HH:mm:ss</tt>.
043 */
044 public static final FastDateFormat ISO_DATETIME_FORMAT
045 = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
046
047 /**
048 * ISO8601 formatter for date-time with time zone.
049 * The format used is <tt>yyyy-MM-dd'T'HH:mm:ssZZ</tt>.
050 */
051 public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT
052 = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ssZZ");
053
054 /**
055 * ISO8601 formatter for date without time zone.
056 * The format used is <tt>yyyy-MM-dd</tt>.
057 */
058 public static final FastDateFormat ISO_DATE_FORMAT
059 = FastDateFormat.getInstance("yyyy-MM-dd");
060
061 /**
062 * ISO8601-like formatter for date with time zone.
063 * The format used is <tt>yyyy-MM-ddZZ</tt>.
064 * This pattern does not comply with the formal ISO8601 specification
065 * as the standard does not allow a time zone without a time.
066 */
067 public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
068 = FastDateFormat.getInstance("yyyy-MM-ddZZ");
069
070 /**
071 * ISO8601 formatter for time without time zone.
072 * The format used is <tt>'T'HH:mm:ss</tt>.
073 */
074 public static final FastDateFormat ISO_TIME_FORMAT
075 = FastDateFormat.getInstance("'T'HH:mm:ss");
076
077 /**
078 * ISO8601 formatter for time with time zone.
079 * The format used is <tt>'T'HH:mm:ssZZ</tt>.
080 */
081 public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
082 = FastDateFormat.getInstance("'T'HH:mm:ssZZ");
083
084 /**
085 * ISO8601-like formatter for time without time zone.
086 * The format used is <tt>HH:mm:ss</tt>.
087 * This pattern does not comply with the formal ISO8601 specification
088 * as the standard requires the 'T' prefix for times.
089 */
090 public static final FastDateFormat ISO_TIME_NO_T_FORMAT
091 = FastDateFormat.getInstance("HH:mm:ss");
092
093 /**
094 * ISO8601-like formatter for time with time zone.
095 * The format used is <tt>HH:mm:ssZZ</tt>.
096 * This pattern does not comply with the formal ISO8601 specification
097 * as the standard requires the 'T' prefix for times.
098 */
099 public static final FastDateFormat ISO_TIME_NO_T_TIME_ZONE_FORMAT
100 = FastDateFormat.getInstance("HH:mm:ssZZ");
101
102 /**
103 * SMTP (and probably other) date headers.
104 * The format used is <tt>EEE, dd MMM yyyy HH:mm:ss Z</tt> in US locale.
105 */
106 public static final FastDateFormat SMTP_DATETIME_FORMAT
107 = FastDateFormat.getInstance("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
108
109 //-----------------------------------------------------------------------
110 /**
111 * <p>DateFormatUtils instances should NOT be constructed in standard programming.</p>
112 *
113 * <p>This constructor is public to permit tools that require a JavaBean instance
114 * to operate.</p>
115 */
116 public DateFormatUtils() {
117 super();
118 }
119
120 /**
121 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
122 *
123 * @param millis the date to format expressed in milliseconds
124 * @param pattern the pattern to use to format the date, not null
125 * @return the formatted date
126 */
127 public static String formatUTC(long millis, String pattern) {
128 return format(new Date(millis), pattern, UTC_TIME_ZONE, null);
129 }
130
131 /**
132 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
133 *
134 * @param date the date to format, not null
135 * @param pattern the pattern to use to format the date, not null
136 * @return the formatted date
137 */
138 public static String formatUTC(Date date, String pattern) {
139 return format(date, pattern, UTC_TIME_ZONE, null);
140 }
141
142 /**
143 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
144 *
145 * @param millis the date to format expressed in milliseconds
146 * @param pattern the pattern to use to format the date, not null
147 * @param locale the locale to use, may be <code>null</code>
148 * @return the formatted date
149 */
150 public static String formatUTC(long millis, String pattern, Locale locale) {
151 return format(new Date(millis), pattern, UTC_TIME_ZONE, locale);
152 }
153
154 /**
155 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
156 *
157 * @param date the date to format, not null
158 * @param pattern the pattern to use to format the date, not null
159 * @param locale the locale to use, may be <code>null</code>
160 * @return the formatted date
161 */
162 public static String formatUTC(Date date, String pattern, Locale locale) {
163 return format(date, pattern, UTC_TIME_ZONE, locale);
164 }
165
166 /**
167 * <p>Formats a date/time into a specific pattern.</p>
168 *
169 * @param millis the date to format expressed in milliseconds
170 * @param pattern the pattern to use to format the date, not null
171 * @return the formatted date
172 */
173 public static String format(long millis, String pattern) {
174 return format(new Date(millis), pattern, null, null);
175 }
176
177 /**
178 * <p>Formats a date/time into a specific pattern.</p>
179 *
180 * @param date the date to format, not null
181 * @param pattern the pattern to use to format the date, not null
182 * @return the formatted date
183 */
184 public static String format(Date date, String pattern) {
185 return format(date, pattern, null, null);
186 }
187
188 /**
189 * <p>Formats a calendar into a specific pattern.</p>
190 *
191 * @param calendar the calendar to format, not null
192 * @param pattern the pattern to use to format the calendar, not null
193 * @return the formatted calendar
194 * @see FastDateFormat#format(Calendar)
195 * @since 2.4
196 */
197 public static String format(Calendar calendar, String pattern) {
198 return format(calendar, pattern, null, null);
199 }
200
201 /**
202 * <p>Formats a date/time into a specific pattern in a time zone.</p>
203 *
204 * @param millis the time expressed in milliseconds
205 * @param pattern the pattern to use to format the date, not null
206 * @param timeZone the time zone to use, may be <code>null</code>
207 * @return the formatted date
208 */
209 public static String format(long millis, String pattern, TimeZone timeZone) {
210 return format(new Date(millis), pattern, timeZone, null);
211 }
212
213 /**
214 * <p>Formats a date/time into a specific pattern in a time zone.</p>
215 *
216 * @param date the date to format, not null
217 * @param pattern the pattern to use to format the date, not null
218 * @param timeZone the time zone to use, may be <code>null</code>
219 * @return the formatted date
220 */
221 public static String format(Date date, String pattern, TimeZone timeZone) {
222 return format(date, pattern, timeZone, null);
223 }
224
225 /**
226 * <p>Formats a calendar into a specific pattern in a time zone.</p>
227 *
228 * @param calendar the calendar to format, not null
229 * @param pattern the pattern to use to format the calendar, not null
230 * @param timeZone the time zone to use, may be <code>null</code>
231 * @return the formatted calendar
232 * @see FastDateFormat#format(Calendar)
233 * @since 2.4
234 */
235 public static String format(Calendar calendar, String pattern, TimeZone timeZone) {
236 return format(calendar, pattern, timeZone, null);
237 }
238
239 /**
240 * <p>Formats a date/time into a specific pattern in a locale.</p>
241 *
242 * @param millis the date to format expressed in milliseconds
243 * @param pattern the pattern to use to format the date, not null
244 * @param locale the locale to use, may be <code>null</code>
245 * @return the formatted date
246 */
247 public static String format(long millis, String pattern, Locale locale) {
248 return format(new Date(millis), pattern, null, locale);
249 }
250
251 /**
252 * <p>Formats a date/time into a specific pattern in a locale.</p>
253 *
254 * @param date the date to format, not null
255 * @param pattern the pattern to use to format the date, not null
256 * @param locale the locale to use, may be <code>null</code>
257 * @return the formatted date
258 */
259 public static String format(Date date, String pattern, Locale locale) {
260 return format(date, pattern, null, locale);
261 }
262
263 /**
264 * <p>Formats a calendar into a specific pattern in a locale.</p>
265 *
266 * @param calendar the calendar to format, not null
267 * @param pattern the pattern to use to format the calendar, not null
268 * @param locale the locale to use, may be <code>null</code>
269 * @return the formatted calendar
270 * @see FastDateFormat#format(Calendar)
271 * @since 2.4
272 */
273 public static String format(Calendar calendar, String pattern, Locale locale) {
274 return format(calendar, pattern, null, locale);
275 }
276
277 /**
278 * <p>Formats a date/time into a specific pattern in a time zone and locale.</p>
279 *
280 * @param millis the date to format expressed in milliseconds
281 * @param pattern the pattern to use to format the date, not null
282 * @param timeZone the time zone to use, may be <code>null</code>
283 * @param locale the locale to use, may be <code>null</code>
284 * @return the formatted date
285 */
286 public static String format(long millis, String pattern, TimeZone timeZone, Locale locale) {
287 return format(new Date(millis), pattern, timeZone, locale);
288 }
289
290 /**
291 * <p>Formats a date/time into a specific pattern in a time zone and locale.</p>
292 *
293 * @param date the date to format, not null
294 * @param pattern the pattern to use to format the date, not null, not null
295 * @param timeZone the time zone to use, may be <code>null</code>
296 * @param locale the locale to use, may be <code>null</code>
297 * @return the formatted date
298 */
299 public static String format(Date date, String pattern, TimeZone timeZone, Locale locale) {
300 FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
301 return df.format(date);
302 }
303
304 /**
305 * <p>Formats a calendar into a specific pattern in a time zone and locale.</p>
306 *
307 * @param calendar the calendar to format, not null
308 * @param pattern the pattern to use to format the calendar, not null
309 * @param timeZone the time zone to use, may be <code>null</code>
310 * @param locale the locale to use, may be <code>null</code>
311 * @return the formatted calendar
312 * @see FastDateFormat#format(Calendar)
313 * @since 2.4
314 */
315 public static String format(Calendar calendar, String pattern, TimeZone timeZone, Locale locale) {
316 FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
317 return df.format(calendar);
318 }
319
320 }