View Javadoc
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   */
35  public class DateFormatUtils {
36  
37      /**
38       * The UTC time zone (often referred to as GMT).
39       * This is private as it is mutable.
40       */
41      private static final TimeZone UTC_TIME_ZONE = TimeZone.getTimeZone("GMT");
42  
43      /**
44       * ISO 8601 formatter for date-time without time zone.
45       * The format used is {@code yyyy-MM-dd'T'HH:mm:ss}.
46       * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
47       * @since 3.5
48       */
49      public static final FastDateFormat ISO_8601_EXTENDED_DATETIME_FORMAT
50              = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
51  
52      /**
53       * @deprecated - as of 4.0, ISO_DATETIME_FORMAT will be replaced by ISO_8601_EXTENDED_DATETIME_FORMAT.
54       */
55      @Deprecated
56      public static final FastDateFormat ISO_DATETIME_FORMAT = ISO_8601_EXTENDED_DATETIME_FORMAT;
57  
58      /**
59       * ISO 8601 formatter for date-time with time zone.
60       * The format used is {@code yyyy-MM-dd'T'HH:mm:ssZZ}.
61       * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
62       * @since 3.5
63       */
64      public static final FastDateFormat ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT
65              = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ssZZ");
66  
67      /**
68       * @deprecated - as of 4.0, ISO_DATETIME_TIME_ZONE_FORMAT will be replaced by ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT.
69       */
70      @Deprecated
71      public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT = ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT;
72  
73      /**
74       * ISO 8601 formatter for date without time zone.
75       * The format used is {@code yyyy-MM-dd}.
76       * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
77       * @since 3.5
78       */
79      public static final FastDateFormat ISO_8601_EXTENDED_DATE_FORMAT
80              = FastDateFormat.getInstance("yyyy-MM-dd");
81  
82      /**
83       * @deprecated - as of 4.0, ISO_DATE_FORMAT will be replaced by ISO_8601_EXTENDED_DATE_FORMAT.
84       */
85      @Deprecated
86      public static final FastDateFormat ISO_DATE_FORMAT = ISO_8601_EXTENDED_DATE_FORMAT;
87  
88      /**
89       * ISO 8601-like formatter for date with time zone.
90       * The format used is {@code yyyy-MM-ddZZ}.
91       * This pattern does not comply with the formal ISO 8601 specification
92       * as the standard does not allow a time zone  without a time.
93       * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
94       * 
95       * @deprecated - as of 4.0, ISO_DATE_TIME_ZONE_FORMAT will be removed.
96       */
97      @Deprecated
98      public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
99              = FastDateFormat.getInstance("yyyy-MM-ddZZ");
100 
101     /**
102      * Non-compliant formatter for time without time zone. (ISO 8601 does not prefix 'T' for standalone time value)
103      * The format used is {@code 'T'HH:mm:ss}.
104      * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
105      * 
106      * @deprecated - as of 4.0, ISO_TIME_FORMAT will be removed.
107      */
108     @Deprecated
109     public static final FastDateFormat ISO_TIME_FORMAT
110             = FastDateFormat.getInstance("'T'HH:mm:ss");
111 
112     /**
113      * Non-compliant formatter for time with time zone. (ISO 8601 does not prefix 'T' for standalone time value)
114      * The format used is {@code 'T'HH:mm:ssZZ}.
115      * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
116      * 
117      * @deprecated - as of 4.0, ISO_TIME_TIME_ZONE_FORMAT will be removed.
118      */
119     @Deprecated
120     public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
121             = FastDateFormat.getInstance("'T'HH:mm:ssZZ");
122 
123     /**
124      * ISO 8601 formatter for time without time zone.
125      * The format used is {@code HH:mm:ss}.
126      * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
127      * @since 3.5
128      */
129     public static final FastDateFormat ISO_8601_EXTENDED_TIME_FORMAT
130             = FastDateFormat.getInstance("HH:mm:ss");
131 
132     /**
133      * @deprecated - as of 4.0, ISO_TIME_NO_T_FORMAT will be replaced by ISO_8601_EXTENDED_TIME_FORMAT.
134      */
135     @Deprecated
136     public static final FastDateFormat ISO_TIME_NO_T_FORMAT = ISO_8601_EXTENDED_TIME_FORMAT;
137 
138     /**
139      * ISO 8601 formatter for time with time zone.
140      * The format used is {@code HH:mm:ssZZ}.
141      * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
142      * @since 3.5
143      */
144     public static final FastDateFormat ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT
145             = FastDateFormat.getInstance("HH:mm:ssZZ");
146 
147     /**
148      * @deprecated - as of 4.0, ISO_TIME_NO_T_TIME_ZONE_FORMAT will be replaced by ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT.
149      */
150     @Deprecated
151     public static final FastDateFormat ISO_TIME_NO_T_TIME_ZONE_FORMAT = ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT;
152 
153     /**
154      * SMTP (and probably other) date headers.
155      * The format used is {@code EEE, dd MMM yyyy HH:mm:ss Z} in US locale.
156      * This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.
157      */
158     public static final FastDateFormat SMTP_DATETIME_FORMAT
159             = FastDateFormat.getInstance("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
160 
161     //-----------------------------------------------------------------------
162     /**
163      * <p>DateFormatUtils instances should NOT be constructed in standard programming.</p>
164      *
165      * <p>This constructor is public to permit tools that require a JavaBean instance
166      * to operate.</p>
167      */
168     public DateFormatUtils() {
169         super();
170     }
171 
172     /**
173      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
174      * 
175      * @param millis  the date to format expressed in milliseconds
176      * @param pattern  the pattern to use to format the date, not null
177      * @return the formatted date
178      */
179     public static String formatUTC(final long millis, final String pattern) {
180         return format(new Date(millis), pattern, UTC_TIME_ZONE, null);
181     }
182 
183     /**
184      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
185      * 
186      * @param date  the date to format, not null
187      * @param pattern  the pattern to use to format the date, not null
188      * @return the formatted date
189      */
190     public static String formatUTC(final Date date, final String pattern) {
191         return format(date, pattern, UTC_TIME_ZONE, null);
192     }
193     
194     /**
195      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
196      * 
197      * @param millis  the date to format expressed in milliseconds
198      * @param pattern  the pattern to use to format the date, not null
199      * @param locale  the locale to use, may be <code>null</code>
200      * @return the formatted date
201      */
202     public static String formatUTC(final long millis, final String pattern, final Locale locale) {
203         return format(new Date(millis), pattern, UTC_TIME_ZONE, locale);
204     }
205 
206     /**
207      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
208      * 
209      * @param date  the date to format, not null
210      * @param pattern  the pattern to use to format the date, not null
211      * @param locale  the locale to use, may be <code>null</code>
212      * @return the formatted date
213      */
214     public static String formatUTC(final Date date, final String pattern, final Locale locale) {
215         return format(date, pattern, UTC_TIME_ZONE, locale);
216     }
217     
218     /**
219      * <p>Formats a date/time into a specific pattern.</p>
220      * 
221      * @param millis  the date to format expressed in milliseconds
222      * @param pattern  the pattern to use to format the date, not null
223      * @return the formatted date
224      */
225     public static String format(final long millis, final String pattern) {
226         return format(new Date(millis), pattern, null, null);
227     }
228 
229     /**
230      * <p>Formats a date/time into a specific pattern.</p>
231      * 
232      * @param date  the date to format, not null
233      * @param pattern  the pattern to use to format the date, not null
234      * @return the formatted date
235      */
236     public static String format(final Date date, final String pattern) {
237         return format(date, pattern, null, null);
238     }
239 
240     /**
241      * <p>Formats a calendar into a specific pattern.</p>
242      * 
243      * @param calendar  the calendar to format, not null
244      * @param pattern  the pattern to use to format the calendar, not null
245      * @return the formatted calendar
246      * @see FastDateFormat#format(Calendar)
247      * @since 2.4
248      */
249     public static String format(final Calendar calendar, final String pattern) {
250         return format(calendar, pattern, null, null);
251     }
252     
253     /**
254      * <p>Formats a date/time into a specific pattern in a time zone.</p>
255      * 
256      * @param millis  the time expressed in milliseconds
257      * @param pattern  the pattern to use to format the date, not null
258      * @param timeZone  the time zone  to use, may be <code>null</code>
259      * @return the formatted date
260      */
261     public static String format(final long millis, final String pattern, final TimeZone timeZone) {
262         return format(new Date(millis), pattern, timeZone, null);
263     }
264 
265     /**
266      * <p>Formats a date/time into a specific pattern in a time zone.</p>
267      * 
268      * @param date  the date to format, not null
269      * @param pattern  the pattern to use to format the date, not null
270      * @param timeZone  the time zone  to use, may be <code>null</code>
271      * @return the formatted date
272      */
273     public static String format(final Date date, final String pattern, final TimeZone timeZone) {
274         return format(date, pattern, timeZone, null);
275     }
276 
277     /**
278      * <p>Formats a calendar into a specific pattern in a time zone.</p>
279      * 
280      * @param calendar  the calendar to format, not null
281      * @param pattern  the pattern to use to format the calendar, not null
282      * @param timeZone  the time zone  to use, may be <code>null</code>
283      * @return the formatted calendar
284      * @see FastDateFormat#format(Calendar)
285      * @since 2.4
286      */
287     public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone) {
288         return format(calendar, pattern, timeZone, null);
289     }
290 
291     /**
292      * <p>Formats a date/time into a specific pattern in a locale.</p>
293      * 
294      * @param millis  the date to format expressed in milliseconds
295      * @param pattern  the pattern to use to format the date, not null
296      * @param locale  the locale to use, may be <code>null</code>
297      * @return the formatted date
298      */
299     public static String format(final long millis, final String pattern, final Locale locale) {
300         return format(new Date(millis), pattern, null, locale);
301     }
302 
303     /**
304      * <p>Formats a date/time into a specific pattern in a locale.</p>
305      * 
306      * @param date  the date to format, not null
307      * @param pattern  the pattern to use to format the date, not null
308      * @param locale  the locale to use, may be <code>null</code>
309      * @return the formatted date
310      */
311     public static String format(final Date date, final String pattern, final Locale locale) {
312         return format(date, pattern, null, locale);
313     }
314 
315     /**
316      * <p>Formats a calendar into a specific pattern in a locale.</p>
317      * 
318      * @param calendar  the calendar to format, not null
319      * @param pattern  the pattern to use to format the calendar, not null
320      * @param locale  the locale to use, may be <code>null</code>
321      * @return the formatted calendar
322      * @see FastDateFormat#format(Calendar)
323      * @since 2.4
324      */
325     public static String format(final Calendar calendar, final String pattern, final Locale locale) {
326         return format(calendar, pattern, null, locale);
327     }
328 
329     /**
330      * <p>Formats a date/time into a specific pattern in a time zone  and locale.</p>
331      * 
332      * @param millis  the date to format expressed in milliseconds
333      * @param pattern  the pattern to use to format the date, not null
334      * @param timeZone  the time zone  to use, may be <code>null</code>
335      * @param locale  the locale to use, may be <code>null</code>
336      * @return the formatted date
337      */
338     public static String format(final long millis, final String pattern, final TimeZone timeZone, final Locale locale) {
339         return format(new Date(millis), pattern, timeZone, locale);
340     }
341 
342     /**
343      * <p>Formats a date/time into a specific pattern in a time zone  and locale.</p>
344      * 
345      * @param date  the date to format, not null
346      * @param pattern  the pattern to use to format the date, not null, not null
347      * @param timeZone  the time zone  to use, may be <code>null</code>
348      * @param locale  the locale to use, may be <code>null</code>
349      * @return the formatted date
350      */
351     public static String format(final Date date, final String pattern, final TimeZone timeZone, final Locale locale) {
352         final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
353         return df.format(date);
354     }
355 
356     /**
357      * <p>Formats a calendar into a specific pattern in a time zone  and locale.</p>
358      * 
359      * @param calendar  the calendar to format, not null
360      * @param pattern  the pattern to use to format the calendar, not null
361      * @param timeZone  the time zone  to use, may be <code>null</code>
362      * @param locale  the locale to use, may be <code>null</code>
363      * @return the formatted calendar
364      * @see FastDateFormat#format(Calendar)
365      * @since 2.4
366      */
367     public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone, final Locale locale) {
368         final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
369         return df.format(calendar);
370     }
371 
372 }