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.lang.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
28 * {@link org.apache.commons.lang.time.FastDateFormat} class.</p>
29 *
30 * @author Apache Ant - DateUtils
31 * @author <a href="mailto:sbailliez@apache.org">Stephane Bailliez</a>
32 * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
33 * @author Stephen Colebourne
34 * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
35 * @since 2.0
36 * @version $Id: DateFormatUtils.java 615243 2008-01-25 15:20:32Z niallp $
37 */
38 public class DateFormatUtils {
39
40 /**
41 * ISO8601 formatter for date-time without time zone.
42 * The format used is <tt>yyyy-MM-dd'T'HH:mm:ss</tt>.
43 */
44 public static final FastDateFormat ISO_DATETIME_FORMAT
45 = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
46
47 /**
48 * ISO8601 formatter for date-time with time zone.
49 * The format used is <tt>yyyy-MM-dd'T'HH:mm:ssZZ</tt>.
50 */
51 public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT
52 = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ssZZ");
53
54 /**
55 * ISO8601 formatter for date without time zone.
56 * The format used is <tt>yyyy-MM-dd</tt>.
57 */
58 public static final FastDateFormat ISO_DATE_FORMAT
59 = FastDateFormat.getInstance("yyyy-MM-dd");
60
61 /**
62 * ISO8601-like formatter for date with time zone.
63 * The format used is <tt>yyyy-MM-ddZZ</tt>.
64 * This pattern does not comply with the formal ISO8601 specification
65 * as the standard does not allow a time zone without a time.
66 */
67 public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
68 = FastDateFormat.getInstance("yyyy-MM-ddZZ");
69
70 /**
71 * ISO8601 formatter for time without time zone.
72 * The format used is <tt>'T'HH:mm:ss</tt>.
73 */
74 public static final FastDateFormat ISO_TIME_FORMAT
75 = FastDateFormat.getInstance("'T'HH:mm:ss");
76
77 /**
78 * ISO8601 formatter for time with time zone.
79 * The format used is <tt>'T'HH:mm:ssZZ</tt>.
80 */
81 public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
82 = FastDateFormat.getInstance("'T'HH:mm:ssZZ");
83
84 /**
85 * ISO8601-like formatter for time without time zone.
86 * The format used is <tt>HH:mm:ss</tt>.
87 * This pattern does not comply with the formal ISO8601 specification
88 * as the standard requires the 'T' prefix for times.
89 */
90 public static final FastDateFormat ISO_TIME_NO_T_FORMAT
91 = FastDateFormat.getInstance("HH:mm:ss");
92
93 /**
94 * ISO8601-like formatter for time with time zone.
95 * The format used is <tt>HH:mm:ssZZ</tt>.
96 * This pattern does not comply with the formal ISO8601 specification
97 * as the standard requires the 'T' prefix for times.
98 */
99 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
125 * @return the formatted date
126 */
127 public static String formatUTC(long millis, String pattern) {
128 return format(new Date(millis), pattern, DateUtils.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
135 * @param pattern the pattern to use to format the date
136 * @return the formatted date
137 */
138 public static String formatUTC(Date date, String pattern) {
139 return format(date, pattern, DateUtils.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
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, DateUtils.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
158 * @param pattern the pattern to use to format the date
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, DateUtils.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
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
181 * @param pattern the pattern to use to format the date
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
192 * @param pattern the pattern to use to format the calendar
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
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
217 * @param pattern the pattern to use to format the date
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
229 * @param pattern the pattern to use to format the calendar
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
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
255 * @param pattern the pattern to use to format the date
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
267 * @param pattern the pattern to use to format the calendar
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
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
294 * @param pattern the pattern to use to format the date
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
308 * @param pattern the pattern to use to format the calendar
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 }