panda.lang.time.FastDateFormat Maven / Gradle / Ivy
Show all versions of panda-core Show documentation
package panda.lang.time;
import java.text.DateFormat;
import java.text.FieldPosition;
import java.text.Format;
import java.text.ParseException;
import java.text.ParsePosition;
import java.util.Calendar;
import java.util.Date;
import java.util.Locale;
import java.util.TimeZone;
/**
*
* FastDateFormat is a fast and thread-safe version of {@link java.text.SimpleDateFormat}.
*
*
* This class can be used as a direct replacement to {@code SimpleDateFormat} in most formatting and
* parsing situations. This class is especially useful in multi-threaded server environments.
* {@code SimpleDateFormat} is not thread-safe in any JDK version, nor will it be as Sun have closed
* the bug/RFE.
*
*
* All patterns are compatible with SimpleDateFormat (except time zones and some year patterns - see
* below).
*
*
* FastDateFormat supports parsing as well as printing.
*
*
* Java 1.4 introduced a new pattern letter, {@code 'Z'}, to represent time zones in RFC822 format
* (eg. {@code +0800} or {@code -1100}). This pattern letter can be used here (on all JDK versions).
*
*
* In addition, the pattern {@code 'ZZ'} has been made to represent ISO8601 full format time zones
* (eg. {@code +08:00} or {@code -11:00}). This introduces a minor incompatibility with Java 1.4,
* but at a gain of useful functionality.
*
*
* Javadoc cites for the year pattern: For formatting, if the number of pattern letters is 2, the
* year is truncated to 2 digits; otherwise it is interpreted as a number. Starting with Java
* 1.7 a pattern of 'Y' or 'YYY' will be formatted as '2003', while it was '03' in former Java
* versions. FastDateFormat implements the behavior of Java 7.
*
*/
public class FastDateFormat extends Format implements DateParser, DatePrinter {
/**
* Required for serialization support.
*
* @see java.io.Serializable
*/
private static final long serialVersionUID = 2L;
/**
* FULL locale dependent date or time style.
*/
public static final int FULL = DateFormat.FULL;
/**
* LONG locale dependent date or time style.
*/
public static final int LONG = DateFormat.LONG;
/**
* MEDIUM locale dependent date or time style.
*/
public static final int MEDIUM = DateFormat.MEDIUM;
/**
* SHORT locale dependent date or time style.
*/
public static final int SHORT = DateFormat.SHORT;
private static final FormatCache cache = new FormatCache() {
@Override
protected FastDateFormat createInstance(final String pattern, final TimeZone timeZone, final Locale locale) {
return new FastDateFormat(pattern, timeZone, locale);
}
};
private final FastDatePrinter printer;
private final FastDateParser parser;
// -----------------------------------------------------------------------
/**
*
* Gets a formatter instance using the default pattern in the default locale.
*
*
* @return a date/time formatter
*/
public static FastDateFormat getInstance() {
return cache.getInstance();
}
/**
*
* Gets a formatter instance using the specified pattern in the default locale.
*
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid
*/
public static FastDateFormat getInstance(final String pattern) {
return cache.getInstance(pattern, null, null);
}
/**
*
* Gets a formatter instance using the specified pattern and time zone.
*
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param timeZone optional time zone, overrides time zone of formatted date
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid
*/
public static FastDateFormat getInstance(final String pattern, final TimeZone timeZone) {
return cache.getInstance(pattern, timeZone, null);
}
/**
*
* Gets a formatter instance using the specified pattern and locale.
*
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param locale optional locale, overrides system locale
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid
*/
public static FastDateFormat getInstance(final String pattern, final Locale locale) {
return cache.getInstance(pattern, null, locale);
}
/**
*
* Gets a formatter instance using the specified pattern, time zone and locale.
*
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param timeZone optional time zone, overrides time zone of formatted date
* @param locale optional locale, overrides system locale
* @return a pattern based date/time formatter
* @throws IllegalArgumentException if pattern is invalid or {@code null}
*/
public static FastDateFormat getInstance(final String pattern, final TimeZone timeZone, final Locale locale) {
return cache.getInstance(pattern, timeZone, locale);
}
// -----------------------------------------------------------------------
/**
*
* Gets a date formatter instance using the specified style in the default time zone and locale.
*
*
* @param style date style: FULL, LONG, MEDIUM, or SHORT
* @return a localized standard date formatter
* @throws IllegalArgumentException if the Locale has no date pattern defined
*/
public static FastDateFormat getDateInstance(final int style) {
return cache.getDateInstance(style, null, null);
}
/**
*
* Gets a date formatter instance using the specified style and locale in the default time zone.
*
*
* @param style date style: FULL, LONG, MEDIUM, or SHORT
* @param locale optional locale, overrides system locale
* @return a localized standard date formatter
* @throws IllegalArgumentException if the Locale has no date pattern defined
*/
public static FastDateFormat getDateInstance(final int style, final Locale locale) {
return cache.getDateInstance(style, null, locale);
}
/**
*
* Gets a date formatter instance using the specified style and time zone in the default locale.
*
*
* @param style date style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted date
* @return a localized standard date formatter
* @throws IllegalArgumentException if the Locale has no date pattern defined
*/
public static FastDateFormat getDateInstance(final int style, final TimeZone timeZone) {
return cache.getDateInstance(style, timeZone, null);
}
/**
*
* Gets a date formatter instance using the specified style, time zone and locale.
*
*
* @param style date style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted date
* @param locale optional locale, overrides system locale
* @return a localized standard date formatter
* @throws IllegalArgumentException if the Locale has no date pattern defined
*/
public static FastDateFormat getDateInstance(final int style, final TimeZone timeZone, final Locale locale) {
return cache.getDateInstance(style, timeZone, locale);
}
// -----------------------------------------------------------------------
/**
*
* Gets a time formatter instance using the specified style in the default time zone and locale.
*
*
* @param style time style: FULL, LONG, MEDIUM, or SHORT
* @return a localized standard time formatter
* @throws IllegalArgumentException if the Locale has no time pattern defined
*/
public static FastDateFormat getTimeInstance(final int style) {
return cache.getTimeInstance(style, null, null);
}
/**
*
* Gets a time formatter instance using the specified style and locale in the default time zone.
*
*
* @param style time style: FULL, LONG, MEDIUM, or SHORT
* @param locale optional locale, overrides system locale
* @return a localized standard time formatter
* @throws IllegalArgumentException if the Locale has no time pattern defined
*/
public static FastDateFormat getTimeInstance(final int style, final Locale locale) {
return cache.getTimeInstance(style, null, locale);
}
/**
*
* Gets a time formatter instance using the specified style and time zone in the default locale.
*
*
* @param style time style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted time
* @return a localized standard time formatter
* @throws IllegalArgumentException if the Locale has no time pattern defined
*/
public static FastDateFormat getTimeInstance(final int style, final TimeZone timeZone) {
return cache.getTimeInstance(style, timeZone, null);
}
/**
*
* Gets a time formatter instance using the specified style, time zone and locale.
*
*
* @param style time style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted time
* @param locale optional locale, overrides system locale
* @return a localized standard time formatter
* @throws IllegalArgumentException if the Locale has no time pattern defined
*/
public static FastDateFormat getTimeInstance(final int style, final TimeZone timeZone, final Locale locale) {
return cache.getTimeInstance(style, timeZone, locale);
}
// -----------------------------------------------------------------------
/**
*
* Gets a date/time formatter instance using the specified style in the default time zone and
* locale.
*
*
* @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
* @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
* @return a localized standard date/time formatter
* @throws IllegalArgumentException if the Locale has no date/time pattern defined
*/
public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle) {
return cache.getDateTimeInstance(dateStyle, timeStyle, null, null);
}
/**
*
* Gets a date/time formatter instance using the specified style and locale in the default time
* zone.
*
*
* @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
* @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
* @param locale optional locale, overrides system locale
* @return a localized standard date/time formatter
* @throws IllegalArgumentException if the Locale has no date/time pattern defined
*/
public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle, final Locale locale) {
return cache.getDateTimeInstance(dateStyle, timeStyle, null, locale);
}
/**
*
* Gets a date/time formatter instance using the specified style and time zone in the default
* locale.
*
*
* @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
* @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted date
* @return a localized standard date/time formatter
* @throws IllegalArgumentException if the Locale has no date/time pattern defined
*/
public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle, final TimeZone timeZone) {
return getDateTimeInstance(dateStyle, timeStyle, timeZone, null);
}
/**
*
* Gets a date/time formatter instance using the specified style, time zone and locale.
*
*
* @param dateStyle date style: FULL, LONG, MEDIUM, or SHORT
* @param timeStyle time style: FULL, LONG, MEDIUM, or SHORT
* @param timeZone optional time zone, overrides time zone of formatted date
* @param locale optional locale, overrides system locale
* @return a localized standard date/time formatter
* @throws IllegalArgumentException if the Locale has no date/time pattern defined
*/
public static FastDateFormat getDateTimeInstance(final int dateStyle, final int timeStyle, final TimeZone timeZone,
final Locale locale) {
return cache.getDateTimeInstance(dateStyle, timeStyle, timeZone, locale);
}
// Constructor
// -----------------------------------------------------------------------
/**
*
* Constructs a new FastDateFormat.
*
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param timeZone non-null time zone to use
* @param locale non-null locale to use
* @throws NullPointerException if pattern, timeZone, or locale is null.
*/
protected FastDateFormat(final String pattern, final TimeZone timeZone, final Locale locale) {
this(pattern, timeZone, locale, null);
}
// Constructor
// -----------------------------------------------------------------------
/**
*
* Constructs a new FastDateFormat.
*
*
* @param pattern {@link java.text.SimpleDateFormat} compatible pattern
* @param timeZone non-null time zone to use
* @param locale non-null locale to use
* @param centuryStart The start of the 100 year period to use as the "default century" for 2
* digit year parsing. If centuryStart is null, defaults to now - 80 years
* @throws NullPointerException if pattern, timeZone, or locale is null.
*/
protected FastDateFormat(final String pattern, final TimeZone timeZone, final Locale locale, final Date centuryStart) {
printer = new FastDatePrinter(pattern, timeZone, locale);
parser = new FastDateParser(pattern, timeZone, locale, centuryStart);
}
// Format methods
// -----------------------------------------------------------------------
/**
*
* Formats a {@code Date}, {@code Calendar} or {@code Long} (milliseconds) object.
*
*
* @param obj the object to format
* @param toAppendTo the buffer to append to
* @param pos the position - ignored
* @return the buffer passed in
*/
@Override
public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {
return toAppendTo.append(printer.format(obj));
}
/**
*
* Formats a millisecond {@code long} value.
*
*
* @param millis the millisecond value to format
* @return the formatted string
*/
@Override
public String format(final long millis) {
return printer.format(millis);
}
/**
*
* Formats a {@code Date} object using a {@code GregorianCalendar}.
*
*
* @param date the date to format
* @return the formatted string
*/
@Override
public String format(final Date date) {
return printer.format(date);
}
/**
*
* Formats a {@code Calendar} object.
*
*
* @param calendar the calendar to format
* @return the formatted string
*/
@Override
public String format(final Calendar calendar) {
return printer.format(calendar);
}
/**
*
* Formats a millisecond {@code long} value into the supplied {@code StringBuffer}.
*
*
* @param millis the millisecond value to format
* @param buf the buffer to format into
* @return the specified string buffer
*/
@Override
public B format(final long millis, final B buf) {
return printer.format(millis, buf);
}
/**
*
* Formats a {@code Date} object into the supplied {@code StringBuffer} using a
* {@code GregorianCalendar}.
*
*
* @param date the date to format
* @param buf the buffer to format into
* @return the specified string buffer
*/
@Override
public B format(final Date date, final B buf) {
return printer.format(date, buf);
}
/**
*
* Formats a {@code Calendar} object into the supplied {@code StringBuffer}.
*
*
* @param calendar the calendar to format
* @param buf the buffer to format into
* @return the specified string buffer
*/
@Override
public B format(final Calendar calendar, final B buf) {
return printer.format(calendar, buf);
}
// Parsing
// -----------------------------------------------------------------------
/*
* (non-Javadoc)
* @see DateParser#parse(java.lang.String)
*/
@Override
public Date parse(final CharSequence source) throws ParseException {
return parser.parse(source);
}
/*
* (non-Javadoc)
* @see DateParser#parse(java.lang.String, java.text.ParsePosition)
*/
@Override
public Date parse(final CharSequence source, final ParsePosition pos) {
return parser.parse(source, pos);
}
@Override
public Object parseObject(CharSequence source) throws ParseException {
ParsePosition pos = new ParsePosition(0);
Object result = parseObject(source, pos);
if (pos.getIndex() == 0) {
throw new ParseException("Format.parseObject(String) failed", pos.getErrorIndex());
}
return result;
}
@Override
public boolean parse(final CharSequence source, final ParsePosition pos, final Calendar calendar) {
return parser.parse(source, pos, calendar);
}
/*
* (non-Javadoc)
* @see java.text.Format#parseObject(java.lang.String, java.text.ParsePosition)
*/
@Override
public Object parseObject(final String source, final ParsePosition pos) {
return parser.parseObject(source, pos);
}
@Override
public Object parseObject(final CharSequence source, final ParsePosition pos) {
return parser.parseObject(source, pos);
}
// Accessors
// -----------------------------------------------------------------------
/**
*
* Gets the pattern used by this formatter.
*
*
* @return the pattern, {@link java.text.SimpleDateFormat} compatible
*/
@Override
public String getPattern() {
return printer.getPattern();
}
/**
*
* Gets the time zone used by this formatter.
*
*
* This zone is always used for {@code Date} formatting.
*
*
* @return the time zone
*/
@Override
public TimeZone getTimeZone() {
return printer.getTimeZone();
}
/**
*
* Gets the locale used by this formatter.
*
*
* @return the locale
*/
@Override
public Locale getLocale() {
return printer.getLocale();
}
/**
*
* 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.
*
*
* @return the maximum formatted length
*/
public int getMaxLengthEstimate() {
return printer.getMaxLengthEstimate();
}
// Basics
// -----------------------------------------------------------------------
/**
*
* Compares two objects for equality.
*
*
* @param obj the object to compare to
* @return {@code true} if equal
*/
@Override
public boolean equals(final Object obj) {
if (obj instanceof FastDateFormat == false) {
return false;
}
final FastDateFormat other = (FastDateFormat)obj;
// no need to check parser, as it has same invariants as printer
return printer.equals(other.printer);
}
/**
*
* Returns a hashcode compatible with equals.
*
*
* @return a hashcode compatible with equals
*/
@Override
public int hashCode() {
return printer.hashCode();
}
/**
*
* Gets a debugging string version of this formatter.
*
*
* @return a debugging string
*/
@Override
public String toString() {
return "FastDateFormat[" + printer.getPattern() + "," + printer.getLocale() + ","
+ printer.getTimeZone().getID() + "]";
}
}