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.util.Calendar;
20 import java.util.Date;
21 import java.util.Locale;
22 import java.util.TimeZone;
23
24 /**
25 * <p>Date and time formatting utilities and constants.</p>
26 *
27 * <p>Formatting is performed using the thread-safe
28 * {@link org.apache.commons.lang3.time.FastDateFormat} class.</p>
29 *
30 * <p>Note that the JDK has a bug wherein calling Calendar.get(int) will
31 * override any previously called Calendar.clear() calls. See LANG-755.</p>
32 *
33 * @since 2.0
34 * @version $Id: DateFormatUtils.java 1436770 2013-01-22 07:09:45Z ggregory $
35 */
36 public class DateFormatUtils {
37
38 /**
39 * The UTC time zone (often referred to as GMT).
40 * This is private as it is mutable.
41 */
42 private static final TimeZone UTC_TIME_ZONE = TimeZone.getTimeZone("GMT");
43 /**
44 * ISO8601 formatter for date-time without time zone.
45 * The format used is <tt>yyyy-MM-dd'T'HH:mm:ss</tt>.
46 */
47 public static final FastDateFormat ISO_DATETIME_FORMAT
48 = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
49
50 /**
51 * ISO8601 formatter for date-time with time zone.
52 * The format used is <tt>yyyy-MM-dd'T'HH:mm:ssZZ</tt>.
53 */
54 public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT
55 = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ssZZ");
56
57 /**
58 * ISO8601 formatter for date without time zone.
59 * The format used is <tt>yyyy-MM-dd</tt>.
60 */
61 public static final FastDateFormat ISO_DATE_FORMAT
62 = FastDateFormat.getInstance("yyyy-MM-dd");
63
64 /**
65 * ISO8601-like formatter for date with time zone.
66 * The format used is <tt>yyyy-MM-ddZZ</tt>.
67 * This pattern does not comply with the formal ISO8601 specification
68 * as the standard does not allow a time zone without a time.
69 */
70 public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
71 = FastDateFormat.getInstance("yyyy-MM-ddZZ");
72
73 /**
74 * ISO8601 formatter for time without time zone.
75 * The format used is <tt>'T'HH:mm:ss</tt>.
76 */
77 public static final FastDateFormat ISO_TIME_FORMAT
78 = FastDateFormat.getInstance("'T'HH:mm:ss");
79
80 /**
81 * ISO8601 formatter for time with time zone.
82 * The format used is <tt>'T'HH:mm:ssZZ</tt>.
83 */
84 public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
85 = FastDateFormat.getInstance("'T'HH:mm:ssZZ");
86
87 /**
88 * ISO8601-like formatter for time without time zone.
89 * The format used is <tt>HH:mm:ss</tt>.
90 * This pattern does not comply with the formal ISO8601 specification
91 * as the standard requires the 'T' prefix for times.
92 */
93 public static final FastDateFormat ISO_TIME_NO_T_FORMAT
94 = FastDateFormat.getInstance("HH:mm:ss");
95
96 /**
97 * ISO8601-like formatter for time with time zone.
98 * The format used is <tt>HH:mm:ssZZ</tt>.
99 * This pattern does not comply with the formal ISO8601 specification
100 * as the standard requires the 'T' prefix for times.
101 */
102 public static final FastDateFormat ISO_TIME_NO_T_TIME_ZONE_FORMAT
103 = FastDateFormat.getInstance("HH:mm:ssZZ");
104
105 /**
106 * SMTP (and probably other) date headers.
107 * The format used is <tt>EEE, dd MMM yyyy HH:mm:ss Z</tt> in US locale.
108 */
109 public static final FastDateFormat SMTP_DATETIME_FORMAT
110 = FastDateFormat.getInstance("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
111
112 //-----------------------------------------------------------------------
113 /**
114 * <p>DateFormatUtils instances should NOT be constructed in standard programming.</p>
115 *
116 * <p>This constructor is public to permit tools that require a JavaBean instance
117 * to operate.</p>
118 */
119 public DateFormatUtils() {
120 super();
121 }
122
123 /**
124 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
125 *
126 * @param millis the date to format expressed in milliseconds
127 * @param pattern the pattern to use to format the date, not null
128 * @return the formatted date
129 */
130 public static String formatUTC(final long millis, final String pattern) {
131 return format(new Date(millis), pattern, UTC_TIME_ZONE, null);
132 }
133
134 /**
135 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
136 *
137 * @param date the date to format, not null
138 * @param pattern the pattern to use to format the date, not null
139 * @return the formatted date
140 */
141 public static String formatUTC(final Date date, final String pattern) {
142 return format(date, pattern, UTC_TIME_ZONE, null);
143 }
144
145 /**
146 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
147 *
148 * @param millis the date to format expressed in milliseconds
149 * @param pattern the pattern to use to format the date, not null
150 * @param locale the locale to use, may be <code>null</code>
151 * @return the formatted date
152 */
153 public static String formatUTC(final long millis, final String pattern, final Locale locale) {
154 return format(new Date(millis), pattern, UTC_TIME_ZONE, locale);
155 }
156
157 /**
158 * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
159 *
160 * @param date the date to format, not null
161 * @param pattern the pattern to use to format the date, not null
162 * @param locale the locale to use, may be <code>null</code>
163 * @return the formatted date
164 */
165 public static String formatUTC(final Date date, final String pattern, final Locale locale) {
166 return format(date, pattern, UTC_TIME_ZONE, locale);
167 }
168
169 /**
170 * <p>Formats a date/time into a specific pattern.</p>
171 *
172 * @param millis the date to format expressed in milliseconds
173 * @param pattern the pattern to use to format the date, not null
174 * @return the formatted date
175 */
176 public static String format(final long millis, final String pattern) {
177 return format(new Date(millis), pattern, null, null);
178 }
179
180 /**
181 * <p>Formats a date/time into a specific pattern.</p>
182 *
183 * @param date the date to format, not null
184 * @param pattern the pattern to use to format the date, not null
185 * @return the formatted date
186 */
187 public static String format(final Date date, final String pattern) {
188 return format(date, pattern, null, null);
189 }
190
191 /**
192 * <p>Formats a calendar into a specific pattern.</p>
193 *
194 * @param calendar the calendar to format, not null
195 * @param pattern the pattern to use to format the calendar, not null
196 * @return the formatted calendar
197 * @see FastDateFormat#format(Calendar)
198 * @since 2.4
199 */
200 public static String format(final Calendar calendar, final String pattern) {
201 return format(calendar, pattern, null, null);
202 }
203
204 /**
205 * <p>Formats a date/time into a specific pattern in a time zone.</p>
206 *
207 * @param millis the time expressed in milliseconds
208 * @param pattern the pattern to use to format the date, not null
209 * @param timeZone the time zone to use, may be <code>null</code>
210 * @return the formatted date
211 */
212 public static String format(final long millis, final String pattern, final TimeZone timeZone) {
213 return format(new Date(millis), pattern, timeZone, null);
214 }
215
216 /**
217 * <p>Formats a date/time into a specific pattern in a time zone.</p>
218 *
219 * @param date the date to format, not null
220 * @param pattern the pattern to use to format the date, not null
221 * @param timeZone the time zone to use, may be <code>null</code>
222 * @return the formatted date
223 */
224 public static String format(final Date date, final String pattern, final TimeZone timeZone) {
225 return format(date, pattern, timeZone, null);
226 }
227
228 /**
229 * <p>Formats a calendar into a specific pattern in a time zone.</p>
230 *
231 * @param calendar the calendar to format, not null
232 * @param pattern the pattern to use to format the calendar, not null
233 * @param timeZone the time zone to use, may be <code>null</code>
234 * @return the formatted calendar
235 * @see FastDateFormat#format(Calendar)
236 * @since 2.4
237 */
238 public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone) {
239 return format(calendar, pattern, timeZone, null);
240 }
241
242 /**
243 * <p>Formats a date/time into a specific pattern in a locale.</p>
244 *
245 * @param millis the date to format expressed in milliseconds
246 * @param pattern the pattern to use to format the date, not null
247 * @param locale the locale to use, may be <code>null</code>
248 * @return the formatted date
249 */
250 public static String format(final long millis, final String pattern, final Locale locale) {
251 return format(new Date(millis), pattern, null, locale);
252 }
253
254 /**
255 * <p>Formats a date/time into a specific pattern in a locale.</p>
256 *
257 * @param date the date to format, not null
258 * @param pattern the pattern to use to format the date, not null
259 * @param locale the locale to use, may be <code>null</code>
260 * @return the formatted date
261 */
262 public static String format(final Date date, final String pattern, final Locale locale) {
263 return format(date, pattern, null, locale);
264 }
265
266 /**
267 * <p>Formats a calendar into a specific pattern in a locale.</p>
268 *
269 * @param calendar the calendar to format, not null
270 * @param pattern the pattern to use to format the calendar, not null
271 * @param locale the locale to use, may be <code>null</code>
272 * @return the formatted calendar
273 * @see FastDateFormat#format(Calendar)
274 * @since 2.4
275 */
276 public static String format(final Calendar calendar, final String pattern, final Locale locale) {
277 return format(calendar, pattern, null, locale);
278 }
279
280 /**
281 * <p>Formats a date/time into a specific pattern in a time zone and locale.</p>
282 *
283 * @param millis the date to format expressed in milliseconds
284 * @param pattern the pattern to use to format the date, not null
285 * @param timeZone the time zone to use, may be <code>null</code>
286 * @param locale the locale to use, may be <code>null</code>
287 * @return the formatted date
288 */
289 public static String format(final long millis, final String pattern, final TimeZone timeZone, final Locale locale) {
290 return format(new Date(millis), pattern, timeZone, locale);
291 }
292
293 /**
294 * <p>Formats a date/time into a specific pattern in a time zone and locale.</p>
295 *
296 * @param date the date to format, not null
297 * @param pattern the pattern to use to format the date, not null, not null
298 * @param timeZone the time zone to use, may be <code>null</code>
299 * @param locale the locale to use, may be <code>null</code>
300 * @return the formatted date
301 */
302 public static String format(final Date date, final String pattern, final TimeZone timeZone, final Locale locale) {
303 final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
304 return df.format(date);
305 }
306
307 /**
308 * <p>Formats a calendar into a specific pattern in a time zone and locale.</p>
309 *
310 * @param calendar the calendar to format, not null
311 * @param pattern the pattern to use to format the calendar, not null
312 * @param timeZone the time zone to use, may be <code>null</code>
313 * @param locale the locale to use, may be <code>null</code>
314 * @return the formatted calendar
315 * @see FastDateFormat#format(Calendar)
316 * @since 2.4
317 */
318 public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone, final Locale locale) {
319 final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
320 return df.format(calendar);
321 }
322
323 }