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   * @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 }