    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    }