Java > Open Source Codes > org > apache > commons > lang > time > FastDateFormat


1 /*
2  * Copyright 2002-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.lang.time;
17
18 import java.text.DateFormat ;
19 import java.text.DateFormatSymbols ;
20 import java.text.FieldPosition ;
21 import java.text.Format ;
22 import java.text.ParsePosition ;
23 import java.text.SimpleDateFormat ;
24 import java.util.ArrayList ;
25 import java.util.Calendar ;
26 import java.util.Date ;
27 import java.util.GregorianCalendar ;
28 import java.util.HashMap ;
29 import java.util.List ;
30 import java.util.Locale ;
31 import java.util.Map ;
32 import java.util.TimeZone ;
33
34 /**
35  * <p>FastDateFormat is a fast and thread-safe version of
36  * {@link java.text.SimpleDateFormat}.</p>
37  *
38  * <p>This class can be used as a direct replacement to
39  * <code>SimpleDateFormat</code> in most formatting situations.
40  * This class is especially useful in multi-threaded server environments.
41  * <code>SimpleDateFormat</code> is not thread-safe in any JDK version,
42  * nor will it be as Sun have closed the bug/RFE.
43  * </p>
44  *
45  * <p>Only formatting is supported, but all patterns are compatible with
46  * SimpleDateFormat (except time zones - see below).</p>
47  *
48  * <p>Java 1.4 introduced a new pattern letter, <code>'Z'</code>, to represent
49  * time zones in RFC822 format (eg. <code>+0800</code> or <code>-1100</code>).
50  * This pattern letter can be used here (on all JDK versions).</p>
51  *
52  * <p>In addition, the pattern <code>'ZZ'</code> has been made to represent
53  * ISO8601 full format time zones (eg. <code>+08:00</code> or <code>-11:00</code>).
54  * This introduces a minor incompatibility with Java 1.4, but at a gain of
55  * useful functionality.</p>
56  *
57  * @author TeaTrove project
58  * @author Brian S O'Neill
59  * @author Sean Schofield
60  * @author Gary Gregory
61  * @author Stephen Colebourne
62  * @author Nikolay Metchev
63  * @since 2.0
64  * @version $Id: FastDateFormat.java 165657 2005-05-02 18:31:49Z ggregory $
65  */
66 public class FastDateFormat extends Format {
67     // A lot of the speed in this class comes from caching, but some comes
68 // from the special int to StringBuffer conversion.
69 //
70 // The following produces a padded 2 digit number:
71 // buffer.append((char)(value / 10 + '0'));
72 // buffer.append((char)(value % 10 + '0'));
73 //
74 // Note that the fastest append to StringBuffer is a single char (used here).
75 // Note that Integer.toString() is not called, the conversion is simply
76 // taking the value and adding (mathematically) the ASCII value for '0'.
77 // So, don't change this code! It works and is very fast.
78
79     /**
80      * FULL locale dependent date or time style.
81      */
82     public static final int FULL = DateFormat.FULL;
83     /**
84      * LONG locale dependent date or time style.
85      */
86     public static final int LONG = DateFormat.LONG;
87     /**
88      * MEDIUM locale dependent date or time style.
89      */
90     public static final int MEDIUM = DateFormat.MEDIUM;
91     /**
92      * SHORT locale dependent date or time style.
93      */
94     public static final int SHORT = DateFormat.SHORT;
95     
96     // package scoped as used by inner class
97 static final double LOG_10 = Math.log(10);
98
99     private static String cDefaultPattern;
100
101     private static Map cInstanceCache = new HashMap (7);
102     private static Map cDateInstanceCache = new HashMap (7);
103     private static Map cTimeInstanceCache = new HashMap (7);
104     private static Map cDateTimeInstanceCache = new HashMap (7);
105     private static Map cTimeZoneDisplayCache = new HashMap (7);
106
107     /**
108      * The pattern.
109      */
110     private final String mPattern;
111     /**
112      * The time zone.
113      */
114     private final TimeZone mTimeZone;
115     /**
116      * Whether the time zone overrides any on Calendars.
117      */
118     private final boolean mTimeZoneForced;
119     /**
120      * The locale.
121      */
122     private final Locale mLocale;
123     /**
124      * Whether the locale overrides the default.
125      */
126     private final boolean mLocaleForced;
127     /**
128      * The parsed rules.
129      */
130     private Rule[] mRules;
131     /**
132      * The estimated maximum length.
133      */
134     private int mMaxLengthEstimate;
135
136     //-----------------------------------------------------------------------
137 /**
138      * <p>Gets a formatter instance using the default pattern in the
139      * default locale.</p>
140      *
141      * @return a date/time formatter
142      */
143     public static FastDateFormat getInstance() {
144         return getInstance(getDefaultPattern(), null, null);
145     }
146
147     /**
148      * <p>Gets a formatter instance using the specified pattern in the
149      * default locale.</p>
150      *
151      * @param pattern {@link java.text.SimpleDateFormat} compatible
152      * pattern
153      * @return a pattern based date/time formatter
154      * @throws IllegalArgumentException if pattern is invalid
155      */
156     public static FastDateFormat getInstance(String pattern) {
157         return getInstance(pattern, null, null);
158     }
159
160     /**
161      * <p>Gets a formatter instance using the specified pattern and
162      * time zone.</p>
163      *
164      * @param pattern {@link java.text.SimpleDateFormat} compatible
165      * pattern
166      * @param timeZone optional time zone, overrides time zone of
167      * formatted date
168      * @return a pattern based date/time formatter
169      * @throws IllegalArgumentException if pattern is invalid
170      */
171     public static FastDateFormat getInstance(String pattern, TimeZone timeZone) {
172         return getInstance(pattern, timeZone, null);
173     }
174
175     /**
176      * <p>Gets a formatter instance using the specified pattern and
177      * locale.</p>
178      *
179      * @param pattern {@link java.text.SimpleDateFormat} compatible
180      * pattern
181      * @param locale optional locale, overrides system locale
182      * @return a pattern based date/time formatter
183      * @throws IllegalArgumentException if pattern is invalid
184      */
185     public static FastDateFormat getInstance(String pattern, Locale locale) {
186         return getInstance(pattern, null, locale);
187     }
188
189     /**
190      * <p>Gets a formatter instance using the specified pattern, time zone
191      * and locale.</p>
192      *
193      * @param pattern {@link java.text.SimpleDateFormat} compatible
194      * pattern
195      * @param timeZone optional time zone, overrides time zone of
196      * formatted date
197      * @param locale optional locale, overrides system locale
198      * @return a pattern based date/time formatter
199      * @throws IllegalArgumentException if pattern is invalid
200      * or <code>null</code>
201      */
202     public static synchronized FastDateFormat getInstance(String pattern, TimeZone timeZone, Locale locale) {
203         FastDateFormat emptyFormat = new FastDateFormat(pattern, timeZone, locale);
204         FastDateFormat format = (FastDateFormat) cInstanceCache.get(emptyFormat);
205         if (format == null) {
206             format = emptyFormat;
207             format.init(); // convert shell format into usable one
208 cInstanceCache.put(format, format); // this is OK!
209 }
210         return format;
211     }
212
213     //-----------------------------------------------------------------------
214 /**
215      * <p>Gets a date formatter instance using the specified style in the
216      * default time zone and locale.</p>
217      *
218      * @param style date style: FULL, LONG, MEDIUM, or SHORT
219      * @return a localized standard date formatter
220      * @throws IllegalArgumentException if the Locale has no date
221      * pattern defined
222      * @since 2.1
223      */
224     public static FastDateFormat getDateInstance(int style) {
225         return getDateInstance(style, null, null);
226     }
227
228     /**
229      * <p>Gets a date formatter instance using the specified style and
230      * locale in the default time zone.</p>
231      *
232      * @param style date style: FULL, LONG, MEDIUM, or SHORT
233      * @param locale optional locale, overrides system locale
234      * @return a localized standard date formatter
235      * @throws IllegalArgumentException if the Locale has no date
236      * pattern defined
237      * @since 2.1
238      */
239     public static FastDateFormat getDateInstance(int style, Locale locale) {
240         return getDateInstance(style, null, locale);
241     }
242
243     /**
244      * <p>Gets a date formatter instance using the specified style and
245      * time zone in the default locale.</p>
246      *
247      * @param style date style: FULL, LONG, MEDIUM, or SHORT
248      * @param timeZone optional time zone, overrides time zone of
249      * formatted date
250      * @return a localized standard date formatter
251      * @throws IllegalArgumentException if the Locale has no date
252      * pattern defined
253      * @since 2.1
254      */
255     public static FastDateFormat getDateInstance(int style, TimeZone timeZone) {
256         return getDateInstance(style, timeZone, null);
257     }
258     /**
259      * <p>Gets a date formatter instance using the specified style, time
260      * zone and locale.</p>
261      *
262      * @param style date style: FULL, LONG, MEDIUM, or SHORT
263      * @param timeZone optional time zone, overrides time zone of
264      * formatted date
265      * @param locale optional locale, overrides system locale
266      * @return a localized standard date formatter
267      * @throws IllegalArgumentException if the Locale has no date
268      * pattern defined
269      */
270     public static synchronized FastDateFormat getDateInstance(int style, TimeZone timeZone, Locale locale) {
271         Object key = new Integer (style);
272         if (timeZone != null) {
273             key = new Pair(key, timeZone);
274         }
275         if (locale != null) {
276             key = new Pair(key, locale);
277         }
278
279         FastDateFormat format = (FastDateFormat) cDateInstanceCache.get(key);
280         if (format == null) {
281             if (locale == null) {
282                 locale = Locale.getDefault();
283             }
284
285             try {
286                 SimpleDateFormat formatter = (SimpleDateFormat ) DateFormat.getDateInstance(style, locale);
287                 String pattern = formatter.toPattern();
288                 format = getInstance(pattern, timeZone, locale);
289                 cDateInstanceCache.put(key, format);
290                 
291             } catch (ClassCastException ex) {
292                 throw new IllegalArgumentException ("No date pattern for locale: " + locale);
293             }
294         }
295         return format;
296     }
297
298     //-----------------------------------------------------------------------
299 /**
300      * <p>Gets a time formatter instance using the specified style in the
301      * default time zone and locale.</p>
302      *
303      * @param style time style: FULL, LONG, MEDIUM, or SHORT
304      * @return a localized standard time formatter
305      * @throws IllegalArgumentException if the Locale has no time
306      * pattern defined
307      * @since 2.1
308      */
309     public static FastDateFormat getTimeInstance(int style) {
310         return getTimeInstance(style, null, null);
311     }
312
313     /**
314      * <p>Gets a time formatter instance using the specified style and
315      * locale in the default time zone.</p>
316      *
317      * @param style time style: FULL, LONG, MEDIUM, or SHORT
318      * @param locale optional locale, overrides system locale
319      * @return a localized standard time formatter
320      * @throws IllegalArgumentException if the Locale has no time
321      * pattern defined
322      * @since 2.1
323      */
324     public static FastDateFormat getTimeInstance(int style, Locale locale) {
325         return getTimeInstance(style, null, locale);
326     }
327     
328     /**
329      * <p>Gets a time formatter instance using the specified style and
330      * time zone in the default locale.</p>
331      *
332      * @param style time style: FULL, LONG, MEDIUM, or SHORT
333      * @param timeZone optional time zone, overrides time zone of
334      * formatted time
335      * @return a localized standard time formatter
336      * @throws IllegalArgumentException if the Locale has no time
337      * pattern defined
338      * @since 2.1
339      */
340     public static FastDateFormat getTimeInstance(int style, TimeZone timeZone) {
341         return getTimeInstance(style, timeZone, null);
342     }
343     
344     /**
345      * <p>Gets a time formatter instance using the specified style, time
346      * zone and locale.</p>
347      *
348      * @param style time style: FULL, LONG, MEDIUM, or SHORT
349      * @param timeZone optional time zone, overrides time zone of
350      * formatted time
351      * @param locale optional locale, overrides system locale
352      * @return a localized standard time formatter
353      * @throws IllegalArgumentException if the Locale has no time
354      * pattern defined
355      */
356     public static synchronized FastDateFormat getTimeInstance(int style, TimeZone timeZone, Locale locale) {
357         Object key = new Integer (style);
358         if (timeZone != null) {
359             key = new Pair(key, timeZone);
360         }
361         if (locale != null) {
362             key = new Pair(key, locale);
363         }
364
365         FastDateFormat format = (FastDateFormat) cTimeInstanceCache.get(key);
366         if (format == null) {
367             if (locale == null) {
368                 locale = Locale.getDefault();
369             }
370
371             try {
372                 SimpleDateFormat formatter = (SimpleDateFormat ) DateFormat.getTimeInstance(style, locale);
373                 String pattern = formatter.toPattern();
374                 format = getInstance(pattern, timeZone, locale);
375                 cTimeInstanceCache.put(key, format);
376             
377             } catch (ClassCastException ex) {
378                 throw new IllegalArgumentException ("No date pattern for locale: " + locale);
379             }
380         }
381         return format;
382     }
383
384     //-----------------------------------------------------------------------
385 /**
386      * <p>Gets a date/time formatter instance using the specified style
387      * in the default time zone and locale.</p>
388      *
389      * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
390      * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
391      * @return a localized standard date/time formatter
392      * @throws IllegalArgumentException if the Locale has no date/time
393      * pattern defined
394      * @since 2.1
395      */
396     public static FastDateFormat getDateTimeInstance(
397             int dateStyle, int timeStyle) {
398         return getDateTimeInstance(dateStyle, timeStyle, null, null);
399     }
400     
401     /**
402      * <p>Gets a date/time formatter instance using the specified style and
403      * locale in the default time zone.</p>
404      *
405      * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
406      * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
407      * @param locale optional locale, overrides system locale
408      * @return a localized standard date/time formatter
409      * @throws IllegalArgumentException if the Locale has no date/time
410      * pattern defined
411      * @since 2.1
412      */
413     public static FastDateFormat getDateTimeInstance(
414             int dateStyle, int timeStyle, Locale locale) {
415         return getDateTimeInstance(dateStyle, timeStyle, null, locale);
416     }
417     
418     /**
419      * <p>Gets a date/time formatter instance using the specified style and
420      * time zone in the default locale.</p>
421      *
422      * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
423      * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
424      * @param timeZone optional time zone, overrides time zone of
425      * formatted date
426      * @return a localized standard date/time formatter
427      * @throws IllegalArgumentException if the Locale has no date/time
428      * pattern defined
429      * @since 2.1
430      */
431     public static FastDateFormat getDateTimeInstance(
432             int dateStyle, int timeStyle, TimeZone timeZone) {
433         return getDateTimeInstance(dateStyle, timeStyle, timeZone, null);
434     }
435     /**
436      * <p>Gets a date/time formatter instance using the specified style,
437      * time zone and locale.</p>
438      *
439      * @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
440      * @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
441      * @param timeZone optional time zone, overrides time zone of
442      * formatted date
443      * @param locale optional locale, overrides system locale
444      * @return a localized standard date/time formatter
445      * @throws IllegalArgumentException if the Locale has no date/time
446      * pattern defined
447      */
448     public static synchronized FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle, TimeZone timeZone,
449             Locale locale) {
450
451         Object key = new Pair(new Integer (dateStyle), new Integer (timeStyle));
452         if (timeZone != null) {
453             key = new Pair(key, timeZone);
454         }
455         if (locale != null) {
456             key = new Pair(key, locale);
457         }
458
459         FastDateFormat format = (FastDateFormat) cDateTimeInstanceCache.get(key);
460         if (format == null) {
461             if (locale == null) {
462                 locale = Locale.getDefault();
463             }
464
465             try {
466                 SimpleDateFormat formatter = (SimpleDateFormat ) DateFormat.getDateTimeInstance(dateStyle, timeStyle,
467                         locale);
468                 String pattern = formatter.toPattern();
469                 format = getInstance(pattern, timeZone, locale);
470                 cDateTimeInstanceCache.put(key, format);
471
472             } catch (ClassCastException ex) {
473                 throw new IllegalArgumentException ("No date time pattern for locale: " + locale);
474             }
475         }
476         return format;
477     }
478
479     //-----------------------------------------------------------------------
480 /**
481      * <p>Gets the time zone display name, using a cache for performance.</p>
482      *
483      * @param tz the zone to query
484      * @param daylight true if daylight savings
485      * @param style the style to use <code>TimeZone.LONG</code>
486      * or <code>TimeZone.SHORT</code>
487      * @param locale the locale to use
488      * @return the textual name of the time zone
489      */
490     static synchronized String getTimeZoneDisplay(TimeZone tz, boolean daylight, int style, Locale locale) {
491         Object key = new TimeZoneDisplayKey(tz, daylight, style, locale);
492         String value = (String ) cTimeZoneDisplayCache.get(key);
493         if (value == null) {
494             // This is a very slow call, so cache the results.
495 value = tz.getDisplayName(daylight, style, locale);
496             cTimeZoneDisplayCache.put(key, value);
497         }
498         return value;
499     }
500
501     /**
502      * <p>Gets the default pattern.</p>
503      *
504      * @return the default pattern
505      */
506     private static synchronized String getDefaultPattern() {
507         if (cDefaultPattern == null) {
508             cDefaultPattern = new SimpleDateFormat ().toPattern();
509         }
510         return cDefaultPattern;
511     }
512
513     // Constructor
514 //-----------------------------------------------------------------------
515 /**
516      * <p>Constructs a new FastDateFormat.</p>
517      *
518      * @param pattern {@link java.text.SimpleDateFormat} compatible
519      * pattern
520      * @param timeZone time zone to use, <code>null</code> means use
521      * default for <code>Date</code> and value within for
522      * <code>Calendar</code>
523      * @param locale locale, <code>null</code> means use system
524      * default
525      * @throws IllegalArgumentException if pattern is invalid or
526      * <code>null</code>
527      */
528     protected FastDateFormat(String pattern, TimeZone timeZone, Locale locale) {
529         super();
530         if (pattern == null) {
531             throw new IllegalArgumentException ("The pattern must not be null");
532         }
533         mPattern = pattern;
534         
535         mTimeZoneForced = (timeZone != null);
536         if (timeZone == null) {
537             timeZone = TimeZone.getDefault();
538         }
539         mTimeZone = timeZone;
540         
541         mLocaleForced = (locale != null);
542         if (locale == null) {
543             locale = Locale.getDefault();
544         }
545         mLocale = locale;
546     }
547
548     /**
549      * <p>Initialise the instance for first use.</p>
550      */
551     protected void init() {
552         List rulesList = parsePattern();
553         mRules = (Rule[]) rulesList.toArray(new Rule[rulesList.size()]);
554
555         int len = 0;
556         for (int i=mRules.length; --i >= 0; ) {
557             len += mRules[i].estimateLength();
558         }
559
560         mMaxLengthEstimate = len;
561     }
562
563     // Parse the pattern
564 //-----------------------------------------------------------------------
565 /**
566      * <p>Returns a list of Rules given a pattern.</p>
567      *
568      * @return a <code>List</code> of Rule objects
569      * @throws IllegalArgumentException if pattern is invalid
570      */
571     protected List parsePattern() {
572         DateFormatSymbols symbols = new DateFormatSymbols (mLocale);
573         List rules = new ArrayList ();
574
575         String [] ERAs = symbols.getEras();
576         String [] months = symbols.getMonths();
577         String [] shortMonths = symbols.getShortMonths();
578         String [] weekdays = symbols.getWeekdays();
579         String [] shortWeekdays = symbols.getShortWeekdays();
580         String [] AmPmStrings = symbols.getAmPmStrings();
581
582         int length = mPattern.length();
583         int[] indexRef = new int[1];
584
585         for (int i = 0; i < length; i++) {
586             indexRef[0] = i;
587             String token = parseToken(mPattern, indexRef);
588             i = indexRef[0];
589
590             int tokenLen = token.length();
591             if (tokenLen == 0) {
592                 break;
593             }
594
595             Rule rule;
596             char c = token.charAt(0);
597
598             switch (c) {
599             case 'G': // era designator (text)
600 rule = new TextField(Calendar.ERA, ERAs);
601                 break;
602             case 'y': // year (number)
603 if (tokenLen >= 4) {
604                     rule = selectNumberRule(Calendar.YEAR, tokenLen);
605                 } else {
606                     rule = TwoDigitYearField.INSTANCE;
607                 }
608                 break;
609             case 'M': // month in year (text and number)
610 if (tokenLen >= 4) {
611                     rule = new TextField(Calendar.MONTH, months);
612                 } else if (tokenLen == 3) {
613                     rule = new TextField(Calendar.MONTH, shortMonths);
614                 } else if (tokenLen == 2) {
615                     rule = TwoDigitMonthField.INSTANCE;
616                 } else {
617                     rule = UnpaddedMonthField.INSTANCE;
618                 }
619                 break;
620             case 'd': // day in month (number)
621 rule = selectNumberRule(Calendar.DAY_OF_MONTH, tokenLen);
622                 break;
623             case 'h': // hour in am/pm (number, 1..12)
624 rule = new TwelveHourField(selectNumberRule(Calendar.HOUR, tokenLen));
625                 break;
626             case 'H': // hour in day (number, 0..23)
627 rule = selectNumberRule(Calendar.HOUR_OF_DAY, tokenLen);
628                 break;
629             case 'm': // minute in hour (number)
630 rule = selectNumberRule(Calendar.MINUTE, tokenLen);
631                 break;
632             case 's': // second in minute (number)
633 rule = selectNumberRule(Calendar.SECOND, tokenLen);
634                 break;
635             case 'S': // millisecond (number)
636 rule = selectNumberRule(Calendar.MILLISECOND, tokenLen);
637                 break;
638             case 'E': // day in week (text)
639 rule = new TextField(Calendar.DAY_OF_WEEK, tokenLen < 4 ? shortWeekdays : weekdays);
640                 break;
641             case 'D': // day in year (number)
642 rule = selectNumberRule(Calendar.DAY_OF_YEAR, tokenLen);
643                 break;
644             case 'F': // day of week in month (number)
645 rule = selectNumberRule(Calendar.DAY_OF_WEEK_IN_MONTH, tokenLen);
646                 break;
647             case 'w': // week in year (number)
648 rule = selectNumberRule(Calendar.WEEK_OF_YEAR, tokenLen);
649                 break;
650             case 'W': // week in month (number)
651 rule = selectNumberRule(Calendar.WEEK_OF_MONTH, tokenLen);
652                 break;
653             case 'a': // am/pm marker (text)
654 rule = new TextField(Calendar.AM_PM, AmPmStrings);
655                 break;
656             case 'k': // hour in day (1..24)
657 rule = new TwentyFourHourField(selectNumberRule(Calendar.HOUR_OF_DAY, tokenLen));
658                 break;
659             case 'K': // hour in am/pm (0..11)
660 rule = selectNumberRule(Calendar.HOUR, tokenLen);
661                 break;
662             case 'z': // time zone (text)
663 if (tokenLen >= 4) {
664                     rule = new TimeZoneNameRule(mTimeZone, mTimeZoneForced, mLocale, TimeZone.LONG);
665                 } else {
666                     rule = new TimeZoneNameRule(mTimeZone, mTimeZoneForced, mLocale, TimeZone.SHORT);
667                 }
668                 break;
669             case 'Z': // time zone (value)
670 if (tokenLen == 1) {
671                     rule = TimeZoneNumberRule.INSTANCE_NO_COLON;
672                 } else {
673                     rule = TimeZoneNumberRule.INSTANCE_COLON;
674                 }
675                 break;
676             case '\'': // literal text
677 String sub = token.substring(1);
678                 if (sub.length() == 1) {
679                     rule = new CharacterLiteral(sub.charAt(0));
680                 } else {
681                     rule = new StringLiteral(sub);
682                 }
683                 break;
684             default:
685                 throw new IllegalArgumentException ("Illegal pattern component: " + token);
686             }
687
688             rules.add(rule);
689         }
690
691         return rules;
692     }
693
694     /**
695      * <p>Performs the parsing of tokens.</p>
696      *
697      * @param pattern the pattern
698      * @param indexRef index references
699      * @return parsed token
700      */
701     protected String parseToken(String pattern, int[] indexRef) {
702         StringBuffer buf = new StringBuffer ();
703
704         int i = indexRef[0];
705         int length = pattern.length();
706
707         char c = pattern.charAt(i);
708         if (c >= 'A' && c <= 'Z' || c >= 'a' && c <= 'z') {
709             // Scan a run of the same character, which indicates a time
710 // pattern.
711 buf.append(c);
712
713             while (i + 1 < length) {
714                 char peek = pattern.charAt(i + 1);
715                 if (peek == c) {
716                     buf.append(c);
717                     i++;
718                 } else {
719                     break;
720                 }
721             }
722         } else {
723             // This will identify token as text.
724 buf.append('\'');
725
726             boolean inLiteral = false;
727
728             for (; i < length; i++) {
729                 c = pattern.charAt(i);
730
731                 if (c == '\'') {
732                     if (i + 1 < length && pattern.charAt(i + 1) == '\'') {
733                         // '' is treated as escaped '
734 i++;
735                         buf.append(c);
736                     } else {
737                         inLiteral = !inLiteral;
738                     }
739                 } else if (!inLiteral &&
740                          (c >= 'A' && c <= 'Z' || c >= 'a' && c <= 'z')) {
741                     i--;
742                     break;
743                 } else {
744                     buf.append(c);
745                 }
746             }
747         }
748
749         indexRef[0] = i;
750         return buf.toString();
751     }
752
753     /**
754      * <p>Gets an appropriate rule for the padding required.</p>
755      *
756      * @param field the field to get a rule for
757      * @param padding the padding required
758      * @return a new rule with the correct padding
759      */
760     protected NumberRule selectNumberRule(int field, int padding) {
761         switch (padding) {
762         case 1:
763             return new UnpaddedNumberField(field);
764         case 2:
765             return new TwoDigitNumberField(field);
766         default:
767             return new PaddedNumberField(field, padding);
768         }
769     }
770
771     // Format methods
772 //-----------------------------------------------------------------------
773 /**
774      * <p>Formats a <code>Date</code>, <code>Calendar</code> or
775      * <code>Long</code> (milliseconds) object.</p>
776      *
777      * @param obj the object to format
778      * @param toAppendTo the buffer to append to
779      * @param pos the position - ignored
780      * @return the buffer passed in
781      */
782     public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {
783         if (obj instanceof Date ) {
784             return format((Date ) obj, toAppendTo);
785         } else if (obj instanceof Calendar ) {
786             return format((Calendar ) obj, toAppendTo);
787         } else if (obj instanceof Long ) {
788             return format(((Long ) obj).longValue(), toAppendTo);
789         } else {
790             throw new IllegalArgumentException ("Unknown class: " +
791                 (obj == null ? "<null>" : obj.getClass().getName()));
792         }
793     }
794
795     /**
796      * <p>Formats a millisecond <code>long</code> value.</p>
797      *
798      * @param millis the millisecond value to format
799      * @return the formatted string
800