001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     * 
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.lang3.time;
018    
019    import java.util.Calendar;
020    import java.util.Date;
021    import java.util.Locale;
022    import java.util.TimeZone;
023    
024    /**
025     * <p>Date and time formatting utilities and constants.</p>
026     *
027     * <p>Formatting is performed using the thread-safe
028     * {@link org.apache.commons.lang3.time.FastDateFormat} class.</p>
029     *
030     * @since 2.0
031     * @version $Id: DateFormatUtils.java 1088899 2011-04-05 05:31:27Z bayard $
032     */
033    public class DateFormatUtils {
034    
035        /**
036         * The UTC time zone (often referred to as GMT).
037         * This is private as it is mutable.
038         */
039        private static final TimeZone UTC_TIME_ZONE = TimeZone.getTimeZone("GMT");
040        /**
041         * ISO8601 formatter for date-time without time zone.
042         * The format used is <tt>yyyy-MM-dd'T'HH:mm:ss</tt>.
043         */
044        public static final FastDateFormat ISO_DATETIME_FORMAT
045                = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
046    
047        /**
048         * ISO8601 formatter for date-time with time zone.
049         * The format used is <tt>yyyy-MM-dd'T'HH:mm:ssZZ</tt>.
050         */
051        public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT
052                = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ssZZ");
053    
054        /**
055         * ISO8601 formatter for date without time zone.
056         * The format used is <tt>yyyy-MM-dd</tt>.
057         */
058        public static final FastDateFormat ISO_DATE_FORMAT
059                = FastDateFormat.getInstance("yyyy-MM-dd");
060    
061        /**
062         * ISO8601-like formatter for date with time zone.
063         * The format used is <tt>yyyy-MM-ddZZ</tt>.
064         * This pattern does not comply with the formal ISO8601 specification
065         * as the standard does not allow a time zone  without a time.
066         */
067        public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
068                = FastDateFormat.getInstance("yyyy-MM-ddZZ");
069    
070        /**
071         * ISO8601 formatter for time without time zone.
072         * The format used is <tt>'T'HH:mm:ss</tt>.
073         */
074        public static final FastDateFormat ISO_TIME_FORMAT
075                = FastDateFormat.getInstance("'T'HH:mm:ss");
076    
077        /**
078         * ISO8601 formatter for time with time zone.
079         * The format used is <tt>'T'HH:mm:ssZZ</tt>.
080         */
081        public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
082                = FastDateFormat.getInstance("'T'HH:mm:ssZZ");
083    
084        /**
085         * ISO8601-like formatter for time without time zone.
086         * The format used is <tt>HH:mm:ss</tt>.
087         * This pattern does not comply with the formal ISO8601 specification
088         * as the standard requires the 'T' prefix for times.
089         */
090        public static final FastDateFormat ISO_TIME_NO_T_FORMAT
091                = FastDateFormat.getInstance("HH:mm:ss");
092    
093        /**
094         * ISO8601-like formatter for time with time zone.
095         * The format used is <tt>HH:mm:ssZZ</tt>.
096         * This pattern does not comply with the formal ISO8601 specification
097         * as the standard requires the 'T' prefix for times.
098         */
099        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, not null
125         * @return the formatted date
126         */
127        public static String formatUTC(long millis, String pattern) {
128            return format(new Date(millis), pattern, 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, not null
135         * @param pattern  the pattern to use to format the date, not null
136         * @return the formatted date
137         */
138        public static String formatUTC(Date date, String pattern) {
139            return format(date, 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 millis  the date to format expressed in milliseconds
146         * @param pattern  the pattern to use to format the date, not null
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, 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, not null
158         * @param pattern  the pattern to use to format the date, not null
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, 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, not null
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, not null
181         * @param pattern  the pattern to use to format the date, not null
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, not null
192         * @param pattern  the pattern to use to format the calendar, not null
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, not null
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, not null
217         * @param pattern  the pattern to use to format the date, not null
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, not null
229         * @param pattern  the pattern to use to format the calendar, not null
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, not null
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, not null
255         * @param pattern  the pattern to use to format the date, not null
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, not null
267         * @param pattern  the pattern to use to format the calendar, not null
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, not null
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, not null
294         * @param pattern  the pattern to use to format the date, not null, not null
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, not null
308         * @param pattern  the pattern to use to format the calendar, not null
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    }