org.apache.commons.lang.time

Class FastDateFormat

public class FastDateFormat extends Format

FastDateFormat is a fast and thread-safe version of {@link java.text.SimpleDateFormat}.

This class can be used as a direct replacement to SimpleDateFormat in most formatting situations. This class is especially useful in multi-threaded server environments. SimpleDateFormat is not thread-safe in any JDK version, nor will it be as Sun have closed the bug/RFE.

Only formatting is supported, but all patterns are compatible with SimpleDateFormat (except time zones - see below).

Java 1.4 introduced a new pattern letter, 'Z', to represent time zones in RFC822 format (eg. +0800 or -1100). This pattern letter can be used here (on all JDK versions).

In addition, the pattern 'ZZ' has been made to represent ISO8601 full format time zones (eg. +08:00 or -11:00). This introduces a minor incompatibility with Java 1.4, but at a gain of useful functionality.

Since: 2.0

Version: $Id: FastDateFormat.java 165657 2005-05-02 18:31:49Z ggregory $

Author: TeaTrove project Brian S O'Neill Sean Schofield Gary Gregory Stephen Colebourne Nikolay Metchev

Field Summary
static intFULL
FULL locale dependent date or time style.
static intLONG
LONG locale dependent date or time style.
static intMEDIUM
MEDIUM locale dependent date or time style.
static intSHORT
SHORT locale dependent date or time style.
Constructor Summary
protected FastDateFormat(String pattern, TimeZone timeZone, Locale locale)

Constructs a new FastDateFormat.

Method Summary
protected StringBufferapplyRules(Calendar calendar, StringBuffer buf)

Performs the formatting by applying the rules to the specified calendar.

booleanequals(Object obj)

Compare two objects for equality.

StringBufferformat(Object obj, StringBuffer toAppendTo, FieldPosition pos)

Formats a Date, Calendar or Long (milliseconds) object.

Stringformat(long millis)

Formats a millisecond long value.

Stringformat(Date date)

Formats a Date object.

Stringformat(Calendar calendar)

Formats a Calendar object.

StringBufferformat(long millis, StringBuffer buf)

Formats a milliseond long value into the supplied StringBuffer.

StringBufferformat(Date date, StringBuffer buf)

Formats a Date object into the supplied StringBuffer.

StringBufferformat(Calendar calendar, StringBuffer buf)

Formats a Calendar object into the supplied StringBuffer.

static FastDateFormatgetDateInstance(int style)

Gets a date formatter instance using the specified style in the default time zone and locale.

static FastDateFormatgetDateInstance(int style, Locale locale)

Gets a date formatter instance using the specified style and locale in the default time zone.

static FastDateFormatgetDateInstance(int style, TimeZone timeZone)

Gets a date formatter instance using the specified style and time zone in the default locale.

static FastDateFormatgetDateInstance(int style, TimeZone timeZone, Locale locale)

Gets a date formatter instance using the specified style, time zone and locale.

static FastDateFormatgetDateTimeInstance(int dateStyle, int timeStyle)

Gets a date/time formatter instance using the specified style in the default time zone and locale.

static FastDateFormatgetDateTimeInstance(int dateStyle, int timeStyle, Locale locale)

Gets a date/time formatter instance using the specified style and locale in the default time zone.

static FastDateFormatgetDateTimeInstance(int dateStyle, int timeStyle, TimeZone timeZone)

Gets a date/time formatter instance using the specified style and time zone in the default locale.

static FastDateFormatgetDateTimeInstance(int dateStyle, int timeStyle, TimeZone timeZone, Locale locale)

Gets a date/time formatter instance using the specified style, time zone and locale.

static FastDateFormatgetInstance()

Gets a formatter instance using the default pattern in the default locale.

static FastDateFormatgetInstance(String pattern)

Gets a formatter instance using the specified pattern in the default locale.

static FastDateFormatgetInstance(String pattern, TimeZone timeZone)

Gets a formatter instance using the specified pattern and time zone.

static FastDateFormatgetInstance(String pattern, Locale locale)

Gets a formatter instance using the specified pattern and locale.

static FastDateFormatgetInstance(String pattern, TimeZone timeZone, Locale locale)

Gets a formatter instance using the specified pattern, time zone and locale.

LocalegetLocale()

Gets the locale used by this formatter.

intgetMaxLengthEstimate()

Gets an estimate for the maximum string length that the formatter will produce.

The actual formatted length will almost always be less than or equal to this amount.

StringgetPattern()

Gets the pattern used by this formatter.

static FastDateFormatgetTimeInstance(int style)

Gets a time formatter instance using the specified style in the default time zone and locale.

static FastDateFormatgetTimeInstance(int style, Locale locale)

Gets a time formatter instance using the specified style and locale in the default time zone.

static FastDateFormatgetTimeInstance(int style, TimeZone timeZone)

Gets a time formatter instance using the specified style and time zone in the default locale.

static FastDateFormatgetTimeInstance(int style, TimeZone timeZone, Locale locale)

Gets a time formatter instance using the specified style, time zone and locale.

TimeZonegetTimeZone()

Gets the time zone used by this formatter.

This zone is always used for Date formatting.

booleangetTimeZoneOverridesCalendar()

Returns true if the time zone of the calendar overrides the time zone of the formatter.

inthashCode()

A suitable hashcode.

protected voidinit()

Initialise the instance for first use.

ObjectparseObject(String source, ParsePosition pos)

Parsing not supported.

protected ListparsePattern()

Returns a list of Rules given a pattern.

protected StringparseToken(String pattern, int[] indexRef)

Performs the parsing of tokens.

protected FastDateFormat.NumberRuleselectNumberRule(int field, int padding)

Gets an appropriate rule for the padding required.

StringtoString()

Gets a debugging string version of this formatter.

Field Detail

FULL

public static final int FULL
FULL locale dependent date or time style.

LONG

public static final int LONG
LONG locale dependent date or time style.

MEDIUM

public static final int MEDIUM
MEDIUM locale dependent date or time style.

SHORT

public static final int SHORT
SHORT locale dependent date or time style.

Constructor Detail

FastDateFormat

protected FastDateFormat(String pattern, TimeZone timeZone, Locale locale)

Constructs a new FastDateFormat.

Parameters: pattern {@link java.text.SimpleDateFormat} compatible pattern timeZone time zone to use, null means use default for Date and value within for Calendar locale locale, null means use system default

Throws: IllegalArgumentException if pattern is invalid or null

Method Detail

applyRules

protected StringBuffer applyRules(Calendar calendar, StringBuffer buf)

Performs the formatting by applying the rules to the specified calendar.

Parameters: calendar the calendar to format buf the buffer to format into

Returns: the specified string buffer

equals

public boolean equals(Object obj)

Compare two objects for equality.

Parameters: obj the object to compare to

Returns: true if equal

format

public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)

Formats a Date, Calendar or Long (milliseconds) object.

Parameters: obj the object to format toAppendTo the buffer to append to pos the position - ignored

Returns: the buffer passed in

format

public String format(long millis)

Formats a millisecond long value.

Parameters: millis the millisecond value to format

Returns: the formatted string

Since: 2.1

format

public String format(Date date)

Formats a Date object.

Parameters: date the date to format

Returns: the formatted string

format

public String format(Calendar calendar)

Formats a Calendar object.

Parameters: calendar the calendar to format

Returns: the formatted string

format

public StringBuffer format(long millis, StringBuffer buf)

Formats a milliseond long value into the supplied StringBuffer.

Parameters: millis the millisecond value to format buf the buffer to format into

Returns: the specified string buffer

Since: 2.1

format

public StringBuffer format(Date date, StringBuffer buf)

Formats a Date object into the supplied StringBuffer.

Parameters: date the date to format buf the buffer to format into

Returns: the specified string buffer

format

public StringBuffer format(Calendar calendar, StringBuffer buf)

Formats a Calendar object into the supplied StringBuffer.

Parameters: calendar the calendar to format buf the buffer to format into

Returns: the specified string buffer

getDateInstance

public static FastDateFormat getDateInstance(int style)

Gets a date formatter instance using the specified style in the default time zone and locale.

Parameters: style date style: FULL, LONG, MEDIUM, or SHORT

Returns: a localized standard date formatter

Throws: IllegalArgumentException if the Locale has no date pattern defined

Since: 2.1

getDateInstance

public static FastDateFormat getDateInstance(int style, Locale locale)

Gets a date formatter instance using the specified style and locale in the default time zone.

Parameters: style date style: FULL, LONG, MEDIUM, or SHORT locale optional locale, overrides system locale

Returns: a localized standard date formatter

Throws: IllegalArgumentException if the Locale has no date pattern defined

Since: 2.1

getDateInstance

public static FastDateFormat getDateInstance(int style, TimeZone timeZone)

Gets a date formatter instance using the specified style and time zone in the default locale.

Parameters: style date style: FULL, LONG, MEDIUM, or SHORT timeZone optional time zone, overrides time zone of formatted date

Returns: a localized standard date formatter

Throws: IllegalArgumentException if the Locale has no date pattern defined

Since: 2.1

getDateInstance

public static FastDateFormat getDateInstance(int style, TimeZone timeZone, Locale locale)

Gets a date formatter instance using the specified style, time zone and locale.

Parameters: style date style: FULL, LONG, MEDIUM, or SHORT timeZone optional time zone, overrides time zone of formatted date locale optional locale, overrides system locale

Returns: a localized standard date formatter

Throws: IllegalArgumentException if the Locale has no date pattern defined

getDateTimeInstance

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle)

Gets a date/time formatter instance using the specified style in the default time zone and locale.

Parameters: dateStyle date style: FULL, LONG, MEDIUM, or SHORT timeStyle time style: FULL, LONG, MEDIUM, or SHORT

Returns: a localized standard date/time formatter

Throws: IllegalArgumentException if the Locale has no date/time pattern defined

Since: 2.1

getDateTimeInstance

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle, Locale locale)

Gets a date/time formatter instance using the specified style and locale in the default time zone.

Parameters: dateStyle date style: FULL, LONG, MEDIUM, or SHORT timeStyle time style: FULL, LONG, MEDIUM, or SHORT locale optional locale, overrides system locale

Returns: a localized standard date/time formatter

Throws: IllegalArgumentException if the Locale has no date/time pattern defined

Since: 2.1

getDateTimeInstance

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle, TimeZone timeZone)

Gets a date/time formatter instance using the specified style and time zone in the default locale.

Parameters: dateStyle date style: FULL, LONG, MEDIUM, or SHORT timeStyle time style: FULL, LONG, MEDIUM, or SHORT timeZone optional time zone, overrides time zone of formatted date

Returns: a localized standard date/time formatter

Throws: IllegalArgumentException if the Locale has no date/time pattern defined

Since: 2.1

getDateTimeInstance

public static FastDateFormat getDateTimeInstance(int dateStyle, int timeStyle, TimeZone timeZone, Locale locale)

Gets a date/time formatter instance using the specified style, time zone and locale.

Parameters: dateStyle date style: FULL, LONG, MEDIUM, or SHORT timeStyle time style: FULL, LONG, MEDIUM, or SHORT timeZone optional time zone, overrides time zone of formatted date locale optional locale, overrides system locale

Returns: a localized standard date/time formatter

Throws: IllegalArgumentException if the Locale has no date/time pattern defined

getInstance

public static FastDateFormat getInstance()

Gets a formatter instance using the default pattern in the default locale.

Returns: a date/time formatter

getInstance

public static FastDateFormat getInstance(String pattern)

Gets a formatter instance using the specified pattern in the default locale.

Parameters: pattern {@link java.text.SimpleDateFormat} compatible pattern

Returns: a pattern based date/time formatter

Throws: IllegalArgumentException if pattern is invalid

getInstance

public static FastDateFormat getInstance(String pattern, TimeZone timeZone)

Gets a formatter instance using the specified pattern and time zone.

Parameters: pattern {@link java.text.SimpleDateFormat} compatible pattern timeZone optional time zone, overrides time zone of formatted date

Returns: a pattern based date/time formatter

Throws: IllegalArgumentException if pattern is invalid

getInstance

public static FastDateFormat getInstance(String pattern, Locale locale)

Gets a formatter instance using the specified pattern and locale.

Parameters: pattern {@link java.text.SimpleDateFormat} compatible pattern locale optional locale, overrides system locale

Returns: a pattern based date/time formatter

Throws: IllegalArgumentException if pattern is invalid

getInstance

public static FastDateFormat getInstance(String pattern, TimeZone timeZone, Locale locale)

Gets a formatter instance using the specified pattern, time zone and locale.

Parameters: pattern {@link java.text.SimpleDateFormat} compatible pattern timeZone optional time zone, overrides time zone of formatted date locale optional locale, overrides system locale

Returns: a pattern based date/time formatter

Throws: IllegalArgumentException if pattern is invalid or null

getLocale

public Locale getLocale()

Gets the locale used by this formatter.

Returns: the locale

getMaxLengthEstimate

public int getMaxLengthEstimate()

Gets an estimate for the maximum string length that the formatter will produce.

The actual formatted length will almost always be less than or equal to this amount.

Returns: the maximum formatted length

getPattern

public String getPattern()

Gets the pattern used by this formatter.

Returns: the pattern, {@link java.text.SimpleDateFormat} compatible

getTimeInstance

public static FastDateFormat getTimeInstance(int style)

Gets a time formatter instance using the specified style in the default time zone and locale.

Parameters: style time style: FULL, LONG, MEDIUM, or SHORT

Returns: a localized standard time formatter

Throws: IllegalArgumentException if the Locale has no time pattern defined

Since: 2.1

getTimeInstance

public static FastDateFormat getTimeInstance(int style, Locale locale)

Gets a time formatter instance using the specified style and locale in the default time zone.

Parameters: style time style: FULL, LONG, MEDIUM, or SHORT locale optional locale, overrides system locale

Returns: a localized standard time formatter

Throws: IllegalArgumentException if the Locale has no time pattern defined

Since: 2.1

getTimeInstance

public static FastDateFormat getTimeInstance(int style, TimeZone timeZone)

Gets a time formatter instance using the specified style and time zone in the default locale.

Parameters: style time style: FULL, LONG, MEDIUM, or SHORT timeZone optional time zone, overrides time zone of formatted time

Returns: a localized standard time formatter

Throws: IllegalArgumentException if the Locale has no time pattern defined

Since: 2.1

getTimeInstance

public static FastDateFormat getTimeInstance(int style, TimeZone timeZone, Locale locale)

Gets a time formatter instance using the specified style, time zone and locale.

Parameters: style time style: FULL, LONG, MEDIUM, or SHORT timeZone optional time zone, overrides time zone of formatted time locale optional locale, overrides system locale

Returns: a localized standard time formatter

Throws: IllegalArgumentException if the Locale has no time pattern defined

getTimeZone

public TimeZone getTimeZone()

Gets the time zone used by this formatter.

This zone is always used for Date formatting. If a Calendar is passed in to be formatted, the time zone on that may be used depending on {@link #getTimeZoneOverridesCalendar()}.

Returns: the time zone

getTimeZoneOverridesCalendar

public boolean getTimeZoneOverridesCalendar()

Returns true if the time zone of the calendar overrides the time zone of the formatter.

Returns: true if time zone of formatter overridden for calendars

hashCode

public int hashCode()

A suitable hashcode.

Returns: a hashcode compatible with equals

init

protected void init()

Initialise the instance for first use.

parseObject

public Object parseObject(String source, ParsePosition pos)

Parsing not supported.

Parameters: source the string to parse pos the parsing position

Returns: null as not supported

parsePattern

protected List parsePattern()

Returns a list of Rules given a pattern.

Returns: a List of Rule objects

Throws: IllegalArgumentException if pattern is invalid

parseToken

protected String parseToken(String pattern, int[] indexRef)

Performs the parsing of tokens.

Parameters: pattern the pattern indexRef index references

Returns: parsed token

selectNumberRule

protected FastDateFormat.NumberRule selectNumberRule(int field, int padding)

Gets an appropriate rule for the padding required.

Parameters: field the field to get a rule for padding the padding required

Returns: a new rule with the correct padding

toString

public String toString()

Gets a debugging string version of this formatter.

Returns: a debugging string

Copyright © 2001-2005 - Apache Software Foundation