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