    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 */
    017package org.apache.commons.lang3.time;
    018
    019import java.io.IOException;
    020import java.io.ObjectInputStream;
    021import java.io.Serializable;
    022import java.text.DateFormat;
    023import java.text.DateFormatSymbols;
    024import java.text.FieldPosition;
    025import java.util.ArrayList;
    026import java.util.Calendar;
    027import java.util.Date;
    028import java.util.List;
    029import java.util.Locale;
    030import java.util.TimeZone;
    031import java.util.concurrent.ConcurrentHashMap;
    032import java.util.concurrent.ConcurrentMap;
    033
    034import org.apache.commons.lang3.exception.ExceptionUtils;
    035
    036/**
    037 * <p>FastDatePrinter is a fast and thread-safe version of
    038 * {@link java.text.SimpleDateFormat}.</p>
    039 *
    040 * <p>To obtain a FastDatePrinter, use {@link FastDateFormat#getInstance(String, TimeZone, Locale)}
    041 * or another variation of the factory methods of {@link FastDateFormat}.</p>
    042 *
    043 * <p>Since FastDatePrinter is thread safe, you can use a static member instance:</p>
    044 * <code>
    045 *     private static final DatePrinter DATE_PRINTER = FastDateFormat.getInstance("yyyy-MM-dd");
    046 * </code>
    047 *
    048 * <p>This class can be used as a direct replacement to
    049 * {@code SimpleDateFormat} in most formatting situations.
    050 * This class is especially useful in multi-threaded server environments.
    051 * {@code SimpleDateFormat} is not thread-safe in any JDK version,
    052 * nor will it be as Sun have closed the bug/RFE.
    053 * </p>
    054 *
    055 * <p>Only formatting is supported by this class, but all patterns are compatible with
    056 * SimpleDateFormat (except time zones and some year patterns - see below).</p>
    057 *
    058 * <p>Java 1.4 introduced a new pattern letter, {@code 'Z'}, to represent
    059 * time zones in RFC822 format (eg. {@code +0800} or {@code -1100}).
    060 * This pattern letter can be used here (on all JDK versions).</p>
    061 *
    062 * <p>In addition, the pattern {@code 'ZZ'} has been made to represent
    063 * ISO 8601 extended format time zones (eg. {@code +08:00} or {@code -11:00}).
    064 * This introduces a minor incompatibility with Java 1.4, but at a gain of
    065 * useful functionality.</p>
    066 *
    067 * <p>Starting with JDK7, ISO 8601 support was added using the pattern {@code 'X'}.
    068 * To maintain compatibility, {@code 'ZZ'} will continue to be supported, but using
    069 * one of the {@code 'X'} formats is recommended.
    070 *
    071 * <p>Javadoc cites for the year pattern: <i>For formatting, if the number of
    072 * pattern letters is 2, the year is truncated to 2 digits; otherwise it is
    073 * interpreted as a number.</i> Starting with Java 1.7 a pattern of 'Y' or
    074 * 'YYY' will be formatted as '2003', while it was '03' in former Java
    075 * versions. FastDatePrinter implements the behavior of Java 7.</p>
    076 *
    077 * @since 3.2
    078 * @see FastDateParser
    079 */
    080public class FastDatePrinter implements DatePrinter, Serializable {
    081    // A lot of the speed in this class comes from caching, but some comes
    082    // from the special int to StringBuffer conversion.
    083    //
    084    // The following produces a padded 2 digit number:
    085    //   buffer.append((char)(value / 10 + '0'));
    086    //   buffer.append((char)(value % 10 + '0'));
    087    //
    088    // Note that the fastest append to StringBuffer is a single char (used here).
    089    // Note that Integer.toString() is not called, the conversion is simply
    090    // taking the value and adding (mathematically) the ASCII value for '0'.
    091    // So, don't change this code! It works and is very fast.
    092
    093    /**
    094     * Required for serialization support.
    095     *
    096     * @see java.io.Serializable
    097     */
    098    private static final long serialVersionUID = 1L;
    099
    100    /**
    101     * FULL locale dependent date or time style.
    102     */
    103    public static final int FULL = DateFormat.FULL;
    104    /**
    105     * LONG locale dependent date or time style.
    106     */
    107    public static final int LONG = DateFormat.LONG;
    108    /**
    109     * MEDIUM locale dependent date or time style.
    110     */
    111    public static final int MEDIUM = DateFormat.MEDIUM;
    112    /**
    113     * SHORT locale dependent date or time style.
    114     */
    115    public static final int SHORT = DateFormat.SHORT;
    116
    117    /**
    118     * The pattern.
    119     */
    120    private final String mPattern;
    121    /**
    122     * The time zone.
    123     */
    124    private final TimeZone mTimeZone;
    125    /**
    126     * The locale.
    127     */
    128    private final Locale mLocale;
    129    /**
    130     * The parsed rules.
    131     */
    132    private transient Rule[] mRules;
    133    /**
    134     * The estimated maximum length.
    135     */
    136    private transient int mMaxLengthEstimate;
    137
    138    // Constructor
    139    //-----------------------------------------------------------------------
    140    /**
    141     * <p>Constructs a new FastDatePrinter.</p>
    142     * Use {@link FastDateFormat#getInstance(String, TimeZone, Locale)}  or another variation of the
    143     * factory methods of {@link FastDateFormat} to get a cached FastDatePrinter instance.
    144     *
    145     * @param pattern  {@link java.text.SimpleDateFormat} compatible pattern
    146     * @param timeZone  non-null time zone to use
    147     * @param locale  non-null locale to use
    148     * @throws NullPointerException if pattern, timeZone, or locale is null.
    149     */
    150    protected FastDatePrinter(final String pattern, final TimeZone timeZone, final Locale locale) {
    151        mPattern = pattern;
    152        mTimeZone = timeZone;
    153        mLocale = locale;
    154
    155        init();
    156    }
    157
    158    /**
    159     * <p>Initializes the instance for first use.</p>
    160     */
    161    private void init() {
    162        final List<Rule> rulesList = parsePattern();
    163        mRules = rulesList.toArray(new Rule[0]);
    164
    165        int len = 0;
    166        for (int i=mRules.length; --i >= 0; ) {
    167            len += mRules[i].estimateLength();
    168        }
    169
    170        mMaxLengthEstimate = len;
    171    }
    172
    173    // Parse the pattern
    174    //-----------------------------------------------------------------------
    175    /**
    176     * <p>Returns a list of Rules given a pattern.</p>
    177     *
    178     * @return a {@code List} of Rule objects
    179     * @throws IllegalArgumentException if pattern is invalid
    180     */
    181    protected List<Rule> parsePattern() {
    182        final DateFormatSymbols symbols = new DateFormatSymbols(mLocale);
    183        final List<Rule> rules = new ArrayList<>();
    184
    185        final String[] ERAs = symbols.getEras();
    186        final String[] months = symbols.getMonths();
    187        final String[] shortMonths = symbols.getShortMonths();
    188        final String[] weekdays = symbols.getWeekdays();
    189        final String[] shortWeekdays = symbols.getShortWeekdays();
    190        final String[] AmPmStrings = symbols.getAmPmStrings();
    191
    192        final int length = mPattern.length();
    193        final int[] indexRef = new int[1];
    194
    195        for (int i = 0; i < length; i++) {
    196            indexRef[0] = i;
    197            final String token = parseToken(mPattern, indexRef);
    198            i = indexRef[0];
    199
    200            final int tokenLen = token.length();
    201            if (tokenLen == 0) {
    202                break;
    203            }
    204
    205            Rule rule;
    206            final char c = token.charAt(0);
    207
    208            switch (c) {
    209            case 'G': // era designator (text)
    210                rule = new TextField(Calendar.ERA, ERAs);
    211                break;
    212            case 'y': // year (number)
    213            case 'Y': // week year
    214                if (tokenLen == 2) {
    215                    rule = TwoDigitYearField.INSTANCE;
    216                } else {
    217                    rule = selectNumberRule(Calendar.YEAR, tokenLen < 4 ? 4 : tokenLen);
    218                }
    219                if (c == 'Y') {
    220                    rule = new WeekYear((NumberRule) rule);
    221                }
    222                break;
    223            case 'M': // month in year (text and number)
    224                if (tokenLen >= 4) {
    225                    rule = new TextField(Calendar.MONTH, months);
    226                } else if (tokenLen == 3) {
    227                    rule = new TextField(Calendar.MONTH, shortMonths);
    228                } else if (tokenLen == 2) {
    229                    rule = TwoDigitMonthField.INSTANCE;
    230                } else {
    231                    rule = UnpaddedMonthField.INSTANCE;
    232                }
    233                break;
    234            case 'd': // day in month (number)
    235                rule = selectNumberRule(Calendar.DAY_OF_MONTH, tokenLen);
    236                break;
    237            case 'h': // hour in am/pm (number, 1..12)
    238                rule = new TwelveHourField(selectNumberRule(Calendar.HOUR, tokenLen));
    239                break;
    240            case 'H': // hour in day (number, 0..23)
    241                rule = selectNumberRule(Calendar.HOUR_OF_DAY, tokenLen);
    242                break;
    243            case 'm': // minute in hour (number)
    244                rule = selectNumberRule(Calendar.MINUTE, tokenLen);
    245                break;
    246            case 's': // second in minute (number)
    247                rule = selectNumberRule(Calendar.SECOND, tokenLen);
    248                break;
    249            case 'S': // millisecond (number)
    250                rule = selectNumberRule(Calendar.MILLISECOND, tokenLen);
    251                break;
    252            case 'E': // day in week (text)
    253                rule = new TextField(Calendar.DAY_OF_WEEK, tokenLen < 4 ? shortWeekdays : weekdays);
    254                break;
    255            case 'u': // day in week (number)
    256                rule = new DayInWeekField(selectNumberRule(Calendar.DAY_OF_WEEK, tokenLen));
    257                break;
    258            case 'D': // day in year (number)
    259                rule = selectNumberRule(Calendar.DAY_OF_YEAR, tokenLen);
    260                break;
    261            case 'F': // day of week in month (number)
    262                rule = selectNumberRule(Calendar.DAY_OF_WEEK_IN_MONTH, tokenLen);
    263                break;
    264            case 'w': // week in year (number)
    265                rule = selectNumberRule(Calendar.WEEK_OF_YEAR, tokenLen);
    266                break;
    267            case 'W': // week in month (number)
    268                rule = selectNumberRule(Calendar.WEEK_OF_MONTH, tokenLen);
    269                break;
    270            case 'a': // am/pm marker (text)
    271                rule = new TextField(Calendar.AM_PM, AmPmStrings);
    272                break;
    273            case 'k': // hour in day (1..24)
    274                rule = new TwentyFourHourField(selectNumberRule(Calendar.HOUR_OF_DAY, tokenLen));
    275                break;
    276            case 'K': // hour in am/pm (0..11)
    277                rule = selectNumberRule(Calendar.HOUR, tokenLen);
    278                break;
    279            case 'X': // ISO 8601
    280                rule = Iso8601_Rule.getRule(tokenLen);
    281                break;
    282            case 'z': // time zone (text)
    283                if (tokenLen >= 4) {
    284                    rule = new TimeZoneNameRule(mTimeZone, mLocale, TimeZone.LONG);
    285                } else {
    286                    rule = new TimeZoneNameRule(mTimeZone, mLocale, TimeZone.SHORT);
    287                }
    288                break;
    289            case 'Z': // time zone (value)
    290                if (tokenLen == 1) {
    291                    rule = TimeZoneNumberRule.INSTANCE_NO_COLON;
    292                } else if (tokenLen == 2) {
    293                    rule = Iso8601_Rule.ISO8601_HOURS_COLON_MINUTES;
    294                } else {
    295                    rule = TimeZoneNumberRule.INSTANCE_COLON;
    296                }
    297                break;
    298            case '\'': // literal text
    299                final String sub = token.substring(1);
    300                if (sub.length() == 1) {
    301                    rule = new CharacterLiteral(sub.charAt(0));
    302                } else {
    303                    rule = new StringLiteral(sub);
    304                }
    305                break;
    306            default:
    307                throw new IllegalArgumentException("Illegal pattern component: " + token);
    308            }
    309
    310            rules.add(rule);
    311        }
    312
    313        return rules;
    314    }
    315
    316    /**
    317     * <p>Performs the parsing of tokens.</p>
    318     *
    319     * @param pattern  the pattern
    320     * @param indexRef  index references
    321     * @return parsed token
    322     */
    323    protected String parseToken(final String pattern, final int[] indexRef) {
    324        final StringBuilder buf = new StringBuilder();
    325
    326        int i = indexRef[0];
    327        final int length = pattern.length();
    328
    329        char c = pattern.charAt(i);
    330        if (c >= 'A' && c <= 'Z' || c >= 'a' && c <= 'z') {
    331            // Scan a run of the same character, which indicates a time
    332            // pattern.
    333            buf.append(c);
    334
    335            while (i + 1 < length) {
    336                final char peek = pattern.charAt(i + 1);
    337                if (peek == c) {
    338                    buf.append(c);
    339                    i++;
    340                } else {
    341                    break;
    342                }
    343            }
    344        } else {
    345            // This will identify token as text.
    346            buf.append('\'');
    347
    348            boolean inLiteral = false;
    349
    350            for (; i < length; i++) {
    351                c = pattern.charAt(i);
    352
    353                if (c == '\'') {
    354                    if (i + 1 < length && pattern.charAt(i + 1) == '\'') {
    355                        // '' is treated as escaped '
    356                        i++;
    357                        buf.append(c);
    358                    } else {
    359                        inLiteral = !inLiteral;
    360                    }
    361                } else if (!inLiteral &&
    362                         (c >= 'A' && c <= 'Z' || c >= 'a' && c <= 'z')) {
    363                    i--;
    364                    break;
    365                } else {
    366                    buf.append(c);
    367                }
    368            }
    369        }
    370
    371        indexRef[0] = i;
    372        return buf.toString();
    373    }
    374
    375    /**
    376     * <p>Gets an appropriate rule for the padding required.</p>
    377     *
    378     * @param field  the field to get a rule for
    379     * @param padding  the padding required
    380     * @return a new rule with the correct padding
    381     */
    382    protected NumberRule selectNumberRule(final int field, final int padding) {
    383        switch (padding) {
    384        case 1:
    385            return new UnpaddedNumberField(field);
    386        case 2:
    387            return new TwoDigitNumberField(field);
    388        default:
    389            return new PaddedNumberField(field, padding);
    390        }
    391    }
    392
    393    // Format methods
    394    //-----------------------------------------------------------------------
    395    /**
    396     * <p>Formats a {@code Date}, {@code Calendar} or
    397     * {@code Long} (milliseconds) object.</p>
    398     * @deprecated Use {{@link #format(Date)}, {{@link #format(Calendar)}, {{@link #format(long)}, or {{@link #format(Object)}
    399     * @param obj  the object to format
    400     * @param toAppendTo  the buffer to append to
    401     * @param pos  the position - ignored
    402     * @return the buffer passed in
    403     */
    404    @Deprecated
    405    @Override
    406    public StringBuffer format(final Object obj, final StringBuffer toAppendTo, final FieldPosition pos) {
    407        if (obj instanceof Date) {
    408            return format((Date) obj, toAppendTo);
    409        } else if (obj instanceof Calendar) {
    410            return format((Calendar) obj, toAppendTo);
    411        } else if (obj instanceof Long) {
    412            return format(((Long) obj).longValue(), toAppendTo);
    413        } else {
    414            throw new IllegalArgumentException("Unknown class: " +
    415                (obj == null ? "<null>" : obj.getClass().getName()));
    416        }
    417    }
    418
    419    /**
    420     * <p>Formats a {@code Date}, {@code Calendar} or
    421     * {@code Long} (milliseconds) object.</p>
    422     * @since 3.5
    423     * @param obj  the object to format
    424     * @return The formatted value.
    425     */
    426    String format(final Object obj) {
    427        if (obj instanceof Date) {
    428            return format((Date) obj);
    429        } else if (obj instanceof Calendar) {
    430            return format((Calendar) obj);
    431        } else if (obj instanceof Long) {
    432            return format(((Long) obj).longValue());
    433        } else {
    434            throw new IllegalArgumentException("Unknown class: " +
    435                (obj == null ? "<null>" : obj.getClass().getName()));
    436        }
    437    }
    438
    439    /* (non-Javadoc)
    440     * @see org.apache.commons.lang3.time.DatePrinter#format(long)
    441     */
    442    @Override
    443    public String format(final long millis) {
    444        final Calendar c = newCalendar();
    445        c.setTimeInMillis(millis);
    446        return applyRulesToString(c);
    447    }
    448
    449    /**
    450     * Creates a String representation of the given Calendar by applying the rules of this printer to it.
    451     * @param c the Calender to apply the rules to.
    452     * @return a String representation of the given Calendar.
    453     */
    454    private String applyRulesToString(final Calendar c) {
    455        return applyRules(c, new StringBuilder(mMaxLengthEstimate)).toString();
    456    }
    457
    458    /**
    459     * Creation method for new calender instances.
    460     * @return a new Calendar instance.
    461     */
    462    private Calendar newCalendar() {
    463        return Calendar.getInstance(mTimeZone, mLocale);
    464    }
    465
    466    /* (non-Javadoc)
    467     * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Date)
    468     */
    469    @Override
    470    public String format(final Date date) {
    471        final Calendar c = newCalendar();
    472        c.setTime(date);
    473        return applyRulesToString(c);
    474    }
    475
    476    /* (non-Javadoc)
    477     * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Calendar)
    478     */
    479    @Override
    480    public String format(final Calendar calendar) {
    481        return format(calendar, new StringBuilder(mMaxLengthEstimate)).toString();
    482    }
    483
    484    /* (non-Javadoc)
    485     * @see org.apache.commons.lang3.time.DatePrinter#format(long, java.lang.StringBuffer)
    486     */
    487    @Override
    488    public StringBuffer format(final long millis, final StringBuffer buf) {
    489        final Calendar c = newCalendar();
    490        c.setTimeInMillis(millis);
    491        return (StringBuffer) applyRules(c, (Appendable) buf);
    492    }
    493
    494    /* (non-Javadoc)
    495     * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Date, java.lang.StringBuffer)
    496     */
    497    @Override
    498    public StringBuffer format(final Date date, final StringBuffer buf) {
    499        final Calendar c = newCalendar();
    500        c.setTime(date);
    501        return (StringBuffer) applyRules(c, (Appendable) buf);
    502    }
    503
    504    /* (non-Javadoc)
    505     * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Calendar, java.lang.StringBuffer)
    506     */
    507    @Override
    508    public StringBuffer format(final Calendar calendar, final StringBuffer buf) {
    509        // do not pass in calendar directly, this will cause TimeZone of FastDatePrinter to be ignored
    510        return format(calendar.getTime(), buf);
    511    }
    512
    513    /* (non-Javadoc)
    514     * @see org.apache.commons.lang3.time.DatePrinter#format(long, java.lang.Appendable)
    515     */
    516    @Override
    517    public <B extends Appendable> B format(final long millis, final B buf) {
    518        final Calendar c = newCalendar();
    519        c.setTimeInMillis(millis);
    520        return applyRules(c, buf);
    521    }
    522
    523    /* (non-Javadoc)
    524     * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Date, java.lang.Appendable)
    525     */
    526    @Override
    527    public <B extends Appendable> B format(final Date date, final B buf) {
    528        final Calendar c = newCalendar();
    529        c.setTime(date);
    530        return applyRules(c, buf);
    531    }
    532
    533    /* (non-Javadoc)
    534     * @see org.apache.commons.lang3.time.DatePrinter#format(java.util.Calendar, java.lang.Appendable)
    535     */
    536    @Override
    537    public <B extends Appendable> B format(Calendar calendar, final B buf) {
    538        // do not pass in calendar directly, this will cause TimeZone of FastDatePrinter to be ignored
    539        if (!calendar.getTimeZone().equals(mTimeZone)) {
    540            calendar = (Calendar) calendar.clone();
    541            calendar.setTimeZone(mTimeZone);
    542        }
    543        return applyRules(calendar, buf);
    544    }
    545
    546    /**
    547     * Performs the formatting by applying the rules to the
    548     * specified calendar.
    549     *
    550     * @param calendar the calendar to format
    551     * @param buf the buffer to format into
    552     * @return the specified string buffer
    553     *
    554     * @deprecated use {@link #format(Calendar)} or {@link #format(Calendar, Appendable)}
    555     */
    556    @Deprecated
    557    protected StringBuffer applyRules(final Calendar calendar, final StringBuffer buf) {
    558        return (StringBuffer) applyRules(calendar, (Appendable) buf);
    559    }
    560
    561    /**
    562     * <p>Performs the formatting by applying the rules to the
    563     * specified calendar.</p>
    564     *
    565     * @param calendar  the calendar to format
    566     * @param buf  the buffer to format into
    567     * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
    568     * @return the specified string buffer
    569     */
    570    private <B extends Appendable> B applyRules(final Calendar calendar, final B buf) {
    571        try {
    572            for (final Rule rule : mRules) {
    573                rule.appendTo(buf, calendar);
    574            }
    575        } catch (final IOException ioe) {
    576            ExceptionUtils.rethrow(ioe);
    577        }
    578        return buf;
    579    }
    580
    581    // Accessors
    582    //-----------------------------------------------------------------------
    583    /* (non-Javadoc)
    584     * @see org.apache.commons.lang3.time.DatePrinter#getPattern()
    585     */
    586    @Override
    587    public String getPattern() {
    588        return mPattern;
    589    }
    590
    591    /* (non-Javadoc)
    592     * @see org.apache.commons.lang3.time.DatePrinter#getTimeZone()
    593     */
    594    @Override
    595    public TimeZone getTimeZone() {
    596        return mTimeZone;
    597    }
    598
    599    /* (non-Javadoc)
    600     * @see org.apache.commons.lang3.time.DatePrinter#getLocale()
    601     */
    602    @Override
    603    public Locale getLocale() {
    604        return mLocale;
    605    }
    606
    607    /**
    608     * <p>Gets an estimate for the maximum string length that the
    609     * formatter will produce.</p>
    610     *
    611     * <p>The actual formatted length will almost always be less than or
    612     * equal to this amount.</p>
    613     *
    614     * @return the maximum formatted length
    615     */
    616    public int getMaxLengthEstimate() {
    617        return mMaxLengthEstimate;
    618    }
    619
    620    // Basics
    621    //-----------------------------------------------------------------------
    622    /**
    623     * <p>Compares two objects for equality.</p>
    624     *
    625     * @param obj  the object to compare to
    626     * @return {@code true} if equal
    627     */
    628    @Override
    629    public boolean equals(final Object obj) {
    630        if (!(obj instanceof FastDatePrinter)) {
    631            return false;
    632        }
    633        final FastDatePrinter other = (FastDatePrinter) obj;
    634        return mPattern.equals(other.mPattern)
    635            && mTimeZone.equals(other.mTimeZone)
    636            && mLocale.equals(other.mLocale);
    637    }
    638
    639    /**
    640     * <p>Returns a hash code compatible with equals.</p>
    641     *
    642     * @return a hash code compatible with equals
    643     */
    644    @Override
    645    public int hashCode() {
    646        return mPattern.hashCode() + 13 * (mTimeZone.hashCode() + 13 * mLocale.hashCode());
    647    }
    648
    649    /**
    650     * <p>Gets a debugging string version of this formatter.</p>
    651     *
    652     * @return a debugging string
    653     */
    654    @Override
    655    public String toString() {
    656        return "FastDatePrinter[" + mPattern + "," + mLocale + "," + mTimeZone.getID() + "]";
    657    }
    658
    659    // Serializing
    660    //-----------------------------------------------------------------------
    661    /**
    662     * Create the object after serialization. This implementation reinitializes the
    663     * transient properties.
    664     *
    665     * @param in ObjectInputStream from which the object is being deserialized.
    666     * @throws IOException if there is an IO issue.
    667     * @throws ClassNotFoundException if a class cannot be found.
    668     */
    669    private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
    670        in.defaultReadObject();
    671        init();
    672    }
    673
    674    /**
    675     * Appends two digits to the given buffer.
    676     *
    677     * @param buffer the buffer to append to.
    678     * @param value the value to append digits from.
    679     */
    680    private static void appendDigits(final Appendable buffer, final int value) throws IOException {
    681        buffer.append((char) (value / 10 + '0'));
    682        buffer.append((char) (value % 10 + '0'));
    683    }
    684
    685    private static final int MAX_DIGITS = 10; // log10(Integer.MAX_VALUE) ~= 9.3
    686
    687    /**
    688     * Appends all digits to the given buffer.
    689     *
    690     * @param buffer the buffer to append to.
    691     * @param value the value to append digits from.
    692     */
    693    private static void appendFullDigits(final Appendable buffer, int value, int minFieldWidth) throws IOException {
    694        // specialized paths for 1 to 4 digits -> avoid the memory allocation from the temporary work array
    695        // see LANG-1248
    696        if (value < 10000) {
    697            // less memory allocation path works for four digits or less
    698
    699            int nDigits = 4;
    700            if (value < 1000) {
    701                --nDigits;
    702                if (value < 100) {
    703                    --nDigits;
    704                    if (value < 10) {
    705                        --nDigits;
    706                    }
    707                }
    708            }
    709            // left zero pad
    710            for (int i = minFieldWidth - nDigits; i > 0; --i) {
    711                buffer.append('0');
    712            }
    713
    714            switch (nDigits) {
    715            case 4:
    716                buffer.append((char) (value / 1000 + '0'));
    717                value %= 1000;
    718            case 3:
    719                if (value >= 100) {
    720                    buffer.append((char) (value / 100 + '0'));
    721                    value %= 100;
    722                } else {
    723                    buffer.append('0');
    724                }
    725            case 2:
    726                if (value >= 10) {
    727                    buffer.append((char) (value / 10 + '0'));
    728                    value %= 10;
    729                } else {
    730                    buffer.append('0');
    731                }
    732            case 1:
    733                buffer.append((char) (value + '0'));
    734            }
    735        } else {
    736            // more memory allocation path works for any digits
    737
    738            // build up decimal representation in reverse
    739            final char[] work = new char[MAX_DIGITS];
    740            int digit = 0;
    741            while (value != 0) {
    742                work[digit++] = (char) (value % 10 + '0');
    743                value = value / 10;
    744            }
    745
    746            // pad with zeros
    747            while (digit < minFieldWidth) {
    748                buffer.append('0');
    749                --minFieldWidth;
    750            }
    751
    752            // reverse
    753            while (--digit >= 0) {
    754                buffer.append(work[digit]);
    755            }
    756        }
    757    }
    758
    759    // Rules
    760    //-----------------------------------------------------------------------
    761    /**
    762     * <p>Inner class defining a rule.</p>
    763     */
    764    private interface Rule {
    765        /**
    766         * Returns the estimated length of the result.
    767         *
    768         * @return the estimated length
    769         */
    770        int estimateLength();
    771
    772        /**
    773         * Appends the value of the specified calendar to the output buffer based on the rule implementation.
    774         *
    775         * @param buf the output buffer
    776         * @param calendar calendar to be appended
    777         * @throws IOException if an I/O error occurs
    778         */
    779        void appendTo(Appendable buf, Calendar calendar) throws IOException;
    780    }
    781
    782    /**
    783     * <p>Inner class defining a numeric rule.</p>
    784     */
    785    private interface NumberRule extends Rule {
    786        /**
    787         * Appends the specified value to the output buffer based on the rule implementation.
    788         *
    789         * @param buffer the output buffer
    790         * @param value the value to be appended
    791         * @throws IOException if an I/O error occurs
    792         */
    793        void appendTo(Appendable buffer, int value) throws IOException;
    794    }
    795
    796    /**
    797     * <p>Inner class to output a constant single character.</p>
    798     */
    799    private static class CharacterLiteral implements Rule {
    800        private final char mValue;
    801
    802        /**
    803         * Constructs a new instance of {@code CharacterLiteral}
    804         * to hold the specified value.
    805         *
    806         * @param value the character literal
    807         */
    808        CharacterLiteral(final char value) {
    809            mValue = value;
    810        }
    811
    812        /**
    813         * {@inheritDoc}
    814         */
    815        @Override
    816        public int estimateLength() {
    817            return 1;
    818        }
    819
    820        /**
    821         * {@inheritDoc}
    822         */
    823        @Override
    824        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    825            buffer.append(mValue);
    826        }
    827    }
    828
    829    /**
    830     * <p>Inner class to output a constant string.</p>
    831     */
    832    private static class StringLiteral implements Rule {
    833        private final String mValue;
    834
    835        /**
    836         * Constructs a new instance of {@code StringLiteral}
    837         * to hold the specified value.
    838         *
    839         * @param value the string literal
    840         */
    841        StringLiteral(final String value) {
    842            mValue = value;
    843        }
    844
    845        /**
    846         * {@inheritDoc}
    847         */
    848        @Override
    849        public int estimateLength() {
    850            return mValue.length();
    851        }
    852
    853        /**
    854         * {@inheritDoc}
    855         */
    856        @Override
    857        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    858            buffer.append(mValue);
    859        }
    860    }
    861
    862    /**
    863     * <p>Inner class to output one of a set of values.</p>
    864     */
    865    private static class TextField implements Rule {
    866        private final int mField;
    867        private final String[] mValues;
    868
    869        /**
    870         * Constructs an instance of {@code TextField}
    871         * with the specified field and values.
    872         *
    873         * @param field the field
    874         * @param values the field values
    875         */
    876        TextField(final int field, final String[] values) {
    877            mField = field;
    878            mValues = values;
    879        }
    880
    881        /**
    882         * {@inheritDoc}
    883         */
    884        @Override
    885        public int estimateLength() {
    886            int max = 0;
    887            for (int i=mValues.length; --i >= 0; ) {
    888                final int len = mValues[i].length();
    889                if (len > max) {
    890                    max = len;
    891                }
    892            }
    893            return max;
    894        }
    895
    896        /**
    897         * {@inheritDoc}
    898         */
    899        @Override
    900        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    901            buffer.append(mValues[calendar.get(mField)]);
    902        }
    903    }
    904
    905    /**
    906     * <p>Inner class to output an unpadded number.</p>
    907     */
    908    private static class UnpaddedNumberField implements NumberRule {
    909        private final int mField;
    910
    911        /**
    912         * Constructs an instance of {@code UnpadedNumberField} with the specified field.
    913         *
    914         * @param field the field
    915         */
    916        UnpaddedNumberField(final int field) {
    917            mField = field;
    918        }
    919
    920        /**
    921         * {@inheritDoc}
    922         */
    923        @Override
    924        public int estimateLength() {
    925            return 4;
    926        }
    927
    928        /**
    929         * {@inheritDoc}
    930         */
    931        @Override
    932        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    933            appendTo(buffer, calendar.get(mField));
    934        }
    935
    936        /**
    937         * {@inheritDoc}
    938         */
    939        @Override
    940        public final void appendTo(final Appendable buffer, final int value) throws IOException {
    941            if (value < 10) {
    942                buffer.append((char) (value + '0'));
    943            } else if (value < 100) {
    944                appendDigits(buffer, value);
    945            } else {
    946               appendFullDigits(buffer, value, 1);
    947            }
    948        }
    949    }
    950
    951    /**
    952     * <p>Inner class to output an unpadded month.</p>
    953     */
    954    private static class UnpaddedMonthField implements NumberRule {
    955        static final UnpaddedMonthField INSTANCE = new UnpaddedMonthField();
    956
    957        /**
    958         * Constructs an instance of {@code UnpaddedMonthField}.
    959         *
    960         */
    961        UnpaddedMonthField() {
    962            super();
    963        }
    964
    965        /**
    966         * {@inheritDoc}
    967         */
    968        @Override
    969        public int estimateLength() {
    970            return 2;
    971        }
    972
    973        /**
    974         * {@inheritDoc}
    975         */
    976        @Override
    977        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    978            appendTo(buffer, calendar.get(Calendar.MONTH) + 1);
    979        }
    980
    981        /**
    982         * {@inheritDoc}
    983         */
    984        @Override
    985        public final void appendTo(final Appendable buffer, final int value) throws IOException {
    986            if (value < 10) {
    987                buffer.append((char) (value + '0'));
    988            } else {
    989                appendDigits(buffer, value);
    990            }
    991        }
    992    }
    993
    994    /**
    995     * <p>Inner class to output a padded number.</p>
    996     */
    997    private static class PaddedNumberField implements NumberRule {
    998        private final int mField;
    999        private final int mSize;
    1000
    1001        /**
    1002         * Constructs an instance of {@code PaddedNumberField}.
    1003         *
    1004         * @param field the field
    1005         * @param size size of the output field
    1006         */
    1007        PaddedNumberField(final int field, final int size) {
    1008            if (size < 3) {
    1009                // Should use UnpaddedNumberField or TwoDigitNumberField.
    1010                throw new IllegalArgumentException();
    1011            }
    1012            mField = field;
    1013            mSize = size;
    1014        }
    1015
    1016        /**
    1017         * {@inheritDoc}
    1018         */
    1019        @Override
    1020        public int estimateLength() {
    1021            return mSize;
    1022        }
    1023
    1024        /**
    1025         * {@inheritDoc}
    1026         */
    1027        @Override
    1028        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1029            appendTo(buffer, calendar.get(mField));
    1030        }
    1031
    1032        /**
    1033         * {@inheritDoc}
    1034         */
    1035        @Override
    1036        public final void appendTo(final Appendable buffer, final int value) throws IOException {
    1037            appendFullDigits(buffer, value, mSize);
    1038        }
    1039    }
    1040
    1041    /**
    1042     * <p>Inner class to output a two digit number.</p>
    1043     */
    1044    private static class TwoDigitNumberField implements NumberRule {
    1045        private final int mField;
    1046
    1047        /**
    1048         * Constructs an instance of {@code TwoDigitNumberField} with the specified field.
    1049         *
    1050         * @param field the field
    1051         */
    1052        TwoDigitNumberField(final int field) {
    1053            mField = field;
    1054        }
    1055
    1056        /**
    1057         * {@inheritDoc}
    1058         */
    1059        @Override
    1060        public int estimateLength() {
    1061            return 2;
    1062        }
    1063
    1064        /**
    1065         * {@inheritDoc}
    1066         */
    1067        @Override
    1068        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1069            appendTo(buffer, calendar.get(mField));
    1070        }
    1071
    1072        /**
    1073         * {@inheritDoc}
    1074         */
    1075        @Override
    1076        public final void appendTo(final Appendable buffer, final int value) throws IOException {
    1077            if (value < 100) {
    1078                appendDigits(buffer, value);
    1079            } else {
    1080                appendFullDigits(buffer, value, 2);
    1081            }
    1082        }
    1083    }
    1084
    1085    /**
    1086     * <p>Inner class to output a two digit year.</p>
    1087     */
    1088    private static class TwoDigitYearField implements NumberRule {
    1089        static final TwoDigitYearField INSTANCE = new TwoDigitYearField();
    1090
    1091        /**
    1092         * Constructs an instance of {@code TwoDigitYearField}.
    1093         */
    1094        TwoDigitYearField() {
    1095            super();
    1096        }
    1097
    1098        /**
    1099         * {@inheritDoc}
    1100         */
    1101        @Override
    1102        public int estimateLength() {
    1103            return 2;
    1104        }
    1105
    1106        /**
    1107         * {@inheritDoc}
    1108         */
    1109        @Override
    1110        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1111            appendTo(buffer, calendar.get(Calendar.YEAR) % 100);
    1112        }
    1113
    1114        /**
    1115         * {@inheritDoc}
    1116         */
    1117        @Override
    1118        public final void appendTo(final Appendable buffer, final int value) throws IOException {
    1119            appendDigits(buffer, value);
    1120        }
    1121    }
    1122
    1123    /**
    1124     * <p>Inner class to output a two digit month.</p>
    1125     */
    1126    private static class TwoDigitMonthField implements NumberRule {
    1127        static final TwoDigitMonthField INSTANCE = new TwoDigitMonthField();
    1128
    1129        /**
    1130         * Constructs an instance of {@code TwoDigitMonthField}.
    1131         */
    1132        TwoDigitMonthField() {
    1133            super();
    1134        }
    1135
    1136        /**
    1137         * {@inheritDoc}
    1138         */
    1139        @Override
    1140        public int estimateLength() {
    1141            return 2;
    1142        }
    1143
    1144        /**
    1145         * {@inheritDoc}
    1146         */
    1147        @Override
    1148        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1149            appendTo(buffer, calendar.get(Calendar.MONTH) + 1);
    1150        }
    1151
    1152        /**
    1153         * {@inheritDoc}
    1154         */
    1155        @Override
    1156        public final void appendTo(final Appendable buffer, final int value) throws IOException {
    1157            appendDigits(buffer, value);
    1158        }
    1159    }
    1160
    1161    /**
    1162     * <p>Inner class to output the twelve hour field.</p>
    1163     */
    1164    private static class TwelveHourField implements NumberRule {
    1165        private final NumberRule mRule;
    1166
    1167        /**
    1168         * Constructs an instance of {@code TwelveHourField} with the specified
    1169         * {@code NumberRule}.
    1170         *
    1171         * @param rule the rule
    1172         */
    1173        TwelveHourField(final NumberRule rule) {
    1174            mRule = rule;
    1175        }
    1176
    1177        /**
    1178         * {@inheritDoc}
    1179         */
    1180        @Override
    1181        public int estimateLength() {
    1182            return mRule.estimateLength();
    1183        }
    1184
    1185        /**
    1186         * {@inheritDoc}
    1187         */
    1188        @Override
    1189        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1190            int value = calendar.get(Calendar.HOUR);
    1191            if (value == 0) {
    1192                value = calendar.getLeastMaximum(Calendar.HOUR) + 1;
    1193            }
    1194            mRule.appendTo(buffer, value);
    1195        }
    1196
    1197        /**
    1198         * {@inheritDoc}
    1199         */
    1200        @Override
    1201        public void appendTo(final Appendable buffer, final int value) throws IOException {
    1202            mRule.appendTo(buffer, value);
    1203        }
    1204    }
    1205
    1206    /**
    1207     * <p>Inner class to output the twenty four hour field.</p>
    1208     */
    1209    private static class TwentyFourHourField implements NumberRule {
    1210        private final NumberRule mRule;
    1211
    1212        /**
    1213         * Constructs an instance of {@code TwentyFourHourField} with the specified
    1214         * {@code NumberRule}.
    1215         *
    1216         * @param rule the rule
    1217         */
    1218        TwentyFourHourField(final NumberRule rule) {
    1219            mRule = rule;
    1220        }
    1221
    1222        /**
    1223         * {@inheritDoc}
    1224         */
    1225        @Override
    1226        public int estimateLength() {
    1227            return mRule.estimateLength();
    1228        }
    1229
    1230        /**
    1231         * {@inheritDoc}
    1232         */
    1233        @Override
    1234        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1235            int value = calendar.get(Calendar.HOUR_OF_DAY);
    1236            if (value == 0) {
    1237                value = calendar.getMaximum(Calendar.HOUR_OF_DAY) + 1;
    1238            }
    1239            mRule.appendTo(buffer, value);
    1240        }
    1241
    1242        /**
    1243         * {@inheritDoc}
    1244         */
    1245        @Override
    1246        public void appendTo(final Appendable buffer, final int value) throws IOException {
    1247            mRule.appendTo(buffer, value);
    1248        }
    1249    }
    1250
    1251    /**
    1252     * <p>Inner class to output the numeric day in week.</p>
    1253     */
    1254    private static class DayInWeekField implements NumberRule {
    1255        private final NumberRule mRule;
    1256
    1257        DayInWeekField(final NumberRule rule) {
    1258            mRule = rule;
    1259        }
    1260
    1261        @Override
    1262        public int estimateLength() {
    1263            return mRule.estimateLength();
    1264        }
    1265
    1266        @Override
    1267        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1268            final int value = calendar.get(Calendar.DAY_OF_WEEK);
    1269            mRule.appendTo(buffer, value == Calendar.SUNDAY ? 7 : value - 1);
    1270        }
    1271
    1272        @Override
    1273        public void appendTo(final Appendable buffer, final int value) throws IOException {
    1274            mRule.appendTo(buffer, value);
    1275        }
    1276    }
    1277
    1278    /**
    1279     * <p>Inner class to output the numeric day in week.</p>
    1280     */
    1281    private static class WeekYear implements NumberRule {
    1282        private final NumberRule mRule;
    1283
    1284        WeekYear(final NumberRule rule) {
    1285            mRule = rule;
    1286        }
    1287
    1288        @Override
    1289        public int estimateLength() {
    1290            return mRule.estimateLength();
    1291        }
    1292
    1293        @Override
    1294        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1295            mRule.appendTo(buffer, calendar.getWeekYear());
    1296        }
    1297
    1298        @Override
    1299        public void appendTo(final Appendable buffer, final int value) throws IOException {
    1300            mRule.appendTo(buffer, value);
    1301        }
    1302    }
    1303
    1304    //-----------------------------------------------------------------------
    1305
    1306    private static final ConcurrentMap<TimeZoneDisplayKey, String> cTimeZoneDisplayCache =
    1307        new ConcurrentHashMap<>(7);
    1308    /**
    1309     * <p>Gets the time zone display name, using a cache for performance.</p>
    1310     *
    1311     * @param tz  the zone to query
    1312     * @param daylight  true if daylight savings
    1313     * @param style  the style to use {@code TimeZone.LONG} or {@code TimeZone.SHORT}
    1314     * @param locale  the locale to use
    1315     * @return the textual name of the time zone
    1316     */
    1317    static String getTimeZoneDisplay(final TimeZone tz, final boolean daylight, final int style, final Locale locale) {
    1318        final TimeZoneDisplayKey key = new TimeZoneDisplayKey(tz, daylight, style, locale);
    1319        String value = cTimeZoneDisplayCache.get(key);
    1320        if (value == null) {
    1321            // This is a very slow call, so cache the results.
    1322            value = tz.getDisplayName(daylight, style, locale);
    1323            final String prior = cTimeZoneDisplayCache.putIfAbsent(key, value);
    1324            if (prior != null) {
    1325                value= prior;
    1326            }
    1327        }
    1328        return value;
    1329    }
    1330
    1331    /**
    1332     * <p>Inner class to output a time zone name.</p>
    1333     */
    1334    private static class TimeZoneNameRule implements Rule {
    1335        private final Locale mLocale;
    1336        private final int mStyle;
    1337        private final String mStandard;
    1338        private final String mDaylight;
    1339
    1340        /**
    1341         * Constructs an instance of {@code TimeZoneNameRule} with the specified properties.
    1342         *
    1343         * @param timeZone the time zone
    1344         * @param locale the locale
    1345         * @param style the style
    1346         */
    1347        TimeZoneNameRule(final TimeZone timeZone, final Locale locale, final int style) {
    1348            mLocale = locale;
    1349            mStyle = style;
    1350
    1351            mStandard = getTimeZoneDisplay(timeZone, false, style, locale);
    1352            mDaylight = getTimeZoneDisplay(timeZone, true, style, locale);
    1353        }
    1354
    1355        /**
    1356         * {@inheritDoc}
    1357         */
    1358        @Override
    1359        public int estimateLength() {
    1360            // We have no access to the Calendar object that will be passed to
    1361            // appendTo so base estimate on the TimeZone passed to the
    1362            // constructor
    1363            return Math.max(mStandard.length(), mDaylight.length());
    1364        }
    1365
    1366        /**
    1367         * {@inheritDoc}
    1368         */
    1369        @Override
    1370        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1371            final TimeZone zone = calendar.getTimeZone();
    1372            if (calendar.get(Calendar.DST_OFFSET) == 0) {
    1373                buffer.append(getTimeZoneDisplay(zone, false, mStyle, mLocale));
    1374            } else {
    1375                buffer.append(getTimeZoneDisplay(zone, true, mStyle, mLocale));
    1376            }
    1377        }
    1378    }
    1379
    1380    /**
    1381     * <p>Inner class to output a time zone as a number {@code +/-HHMM}
    1382     * or {@code +/-HH:MM}.</p>
    1383     */
    1384    private static class TimeZoneNumberRule implements Rule {
    1385        static final TimeZoneNumberRule INSTANCE_COLON = new TimeZoneNumberRule(true);
    1386        static final TimeZoneNumberRule INSTANCE_NO_COLON = new TimeZoneNumberRule(false);
    1387
    1388        final boolean mColon;
    1389
    1390        /**
    1391         * Constructs an instance of {@code TimeZoneNumberRule} with the specified properties.
    1392         *
    1393         * @param colon add colon between HH and MM in the output if {@code true}
    1394         */
    1395        TimeZoneNumberRule(final boolean colon) {
    1396            mColon = colon;
    1397        }
    1398
    1399        /**
    1400         * {@inheritDoc}
    1401         */
    1402        @Override
    1403        public int estimateLength() {
    1404            return 5;
    1405        }
    1406
    1407        /**
    1408         * {@inheritDoc}
    1409         */
    1410        @Override
    1411        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1412
    1413            int offset = calendar.get(Calendar.ZONE_OFFSET) + calendar.get(Calendar.DST_OFFSET);
    1414
    1415            if (offset < 0) {
    1416                buffer.append('-');
    1417                offset = -offset;
    1418            } else {
    1419                buffer.append('+');
    1420            }
    1421
    1422            final int hours = offset / (60 * 60 * 1000);
    1423            appendDigits(buffer, hours);
    1424
    1425            if (mColon) {
    1426                buffer.append(':');
    1427            }
    1428
    1429            final int minutes = offset / (60 * 1000) - 60 * hours;
    1430            appendDigits(buffer, minutes);
    1431        }
    1432    }
    1433
    1434    /**
    1435     * <p>Inner class to output a time zone as a number {@code +/-HHMM}
    1436     * or {@code +/-HH:MM}.</p>
    1437     */
    1438    private static class Iso8601_Rule implements Rule {
    1439
    1440        // Sign TwoDigitHours or Z
    1441        static final Iso8601_Rule ISO8601_HOURS = new Iso8601_Rule(3);
    1442        // Sign TwoDigitHours Minutes or Z
    1443        static final Iso8601_Rule ISO8601_HOURS_MINUTES = new Iso8601_Rule(5);
    1444        // Sign TwoDigitHours : Minutes or Z
    1445        static final Iso8601_Rule ISO8601_HOURS_COLON_MINUTES = new Iso8601_Rule(6);
    1446
    1447        /**
    1448         * Factory method for Iso8601_Rules.
    1449         *
    1450         * @param tokenLen a token indicating the length of the TimeZone String to be formatted.
    1451         * @return a Iso8601_Rule that can format TimeZone String of length {@code tokenLen}. If no such
    1452         *          rule exists, an IllegalArgumentException will be thrown.
    1453         */
    1454        static Iso8601_Rule getRule(final int tokenLen) {
    1455            switch(tokenLen) {
    1456            case 1:
    1457                return ISO8601_HOURS;
    1458            case 2:
    1459                return ISO8601_HOURS_MINUTES;
    1460            case 3:
    1461                return ISO8601_HOURS_COLON_MINUTES;
    1462            default:
    1463                throw new IllegalArgumentException("invalid number of X");
    1464            }
    1465        }
    1466
    1467        final int length;
    1468
    1469        /**
    1470         * Constructs an instance of {@code Iso8601_Rule} with the specified properties.
    1471         *
    1472         * @param length The number of characters in output (unless Z is output)
    1473         */
    1474        Iso8601_Rule(final int length) {
    1475            this.length = length;
    1476        }
    1477
    1478        /**
    1479         * {@inheritDoc}
    1480         */
    1481        @Override
    1482        public int estimateLength() {
    1483            return length;
    1484        }
    1485
    1486        /**
    1487         * {@inheritDoc}
    1488         */
    1489        @Override
    1490        public void appendTo(final Appendable buffer, final Calendar calendar) throws IOException {
    1491            int offset = calendar.get(Calendar.ZONE_OFFSET) + calendar.get(Calendar.DST_OFFSET);
    1492            if (offset == 0) {
    1493                buffer.append("Z");
    1494                return;
    1495            }
    1496
    1497            if (offset < 0) {
    1498                buffer.append('-');
    1499                offset = -offset;
    1500            } else {
    1501                buffer.append('+');
    1502            }
    1503
    1504            final int hours = offset / (60 * 60 * 1000);
    1505            appendDigits(buffer, hours);
    1506
    1507            if (length<5) {
    1508                return;
    1509            }
    1510
    1511            if (length==6) {
    1512                buffer.append(':');
    1513            }
    1514
    1515            final int minutes = offset / (60 * 1000) - 60 * hours;
    1516            appendDigits(buffer, minutes);
    1517        }
    1518    }
    1519
    1520    // ----------------------------------------------------------------------
    1521    /**
    1522     * <p>Inner class that acts as a compound key for time zone names.</p>
    1523     */
    1524    private static class TimeZoneDisplayKey {
    1525        private final TimeZone mTimeZone;
    1526        private final int mStyle;
    1527        private final Locale mLocale;
    1528
    1529        /**
    1530         * Constructs an instance of {@code TimeZoneDisplayKey} with the specified properties.
    1531         *
    1532         * @param timeZone the time zone
    1533         * @param daylight adjust the style for daylight saving time if {@code true}
    1534         * @param style the timezone style
    1535         * @param locale the timezone locale
    1536         */
    1537        TimeZoneDisplayKey(final TimeZone timeZone,
    1538                           final boolean daylight, final int style, final Locale locale) {
    1539            mTimeZone = timeZone;
    1540            if (daylight) {
    1541                mStyle = style | 0x80000000;
    1542            } else {
    1543                mStyle = style;
    1544            }
    1545            mLocale = locale;
    1546        }
    1547
    1548        /**
    1549         * {@inheritDoc}
    1550         */
    1551        @Override
    1552        public int hashCode() {
    1553            return (mStyle * 31 + mLocale.hashCode() ) * 31 + mTimeZone.hashCode();
    1554        }
    1555
    1556        /**
    1557         * {@inheritDoc}
    1558         */
    1559        @Override
    1560        public boolean equals(final Object obj) {
    1561            if (this == obj) {
    1562                return true;
    1563            }
    1564            if (obj instanceof TimeZoneDisplayKey) {
    1565                final TimeZoneDisplayKey other = (TimeZoneDisplayKey) obj;
    1566                return
    1567                    mTimeZone.equals(other.mTimeZone) &&
    1568                    mStyle == other.mStyle &&
    1569                    mLocale.equals(other.mLocale);
    1570            }
    1571            return false;
    1572        }
    1573    }
    1574}