Class FastDateParser
- java.lang.Object
-
- org.apache.commons.lang3.time.FastDateParser
-
- All Implemented Interfaces:
java.io.Serializable
,DateParser
public class FastDateParser extends java.lang.Object implements DateParser, java.io.Serializable
FastDateParser is a fast and thread-safe version of
SimpleDateFormat
.To obtain a proxy to a FastDateParser, use
FastDateFormat.getInstance(String, TimeZone, Locale)
or another variation of the factory methods ofFastDateFormat
.Since FastDateParser is thread safe, you can use a static member instance:
private static final DateParser DATE_PARSER = FastDateFormat.getInstance("yyyy-MM-dd");
This class can be used as a direct replacement for
SimpleDateFormat
in most parsing 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 has closed the bug/RFE.Only parsing is supported by this class, but all patterns are compatible with SimpleDateFormat.
The class operates in lenient mode, so for example a time of 90 minutes is treated as 1 hour 30 minutes.
Timing tests indicate this class is as about as fast as SimpleDateFormat in single thread applications and about 25% faster in multi-thread applications.
- Since:
- 3.2
- See Also:
FastDatePrinter
, Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
FastDateParser.CaseInsensitiveTextStrategy
A strategy that handles a text field in the parsing patternprivate static class
FastDateParser.CopyQuotedStrategy
A strategy that copies the static or quoted field in the parsing patternprivate static class
FastDateParser.ISO8601TimeZoneStrategy
private static class
FastDateParser.NumberStrategy
A strategy that handles a number field in the parsing patternprivate static class
FastDateParser.PatternStrategy
A strategy to parse a single field from the parsing patternprivate static class
FastDateParser.Strategy
A strategy to parse a single field from the parsing patternprivate static class
FastDateParser.StrategyAndWidth
Holds strategy and field widthprivate class
FastDateParser.StrategyParser
Parse format into Strategies(package private) static class
FastDateParser.TimeZoneStrategy
A strategy that handles a time zone field in the parsing pattern
-
Field Summary
-
Constructor Summary
Constructors Modifier Constructor Description protected
FastDateParser(java.lang.String pattern, java.util.TimeZone timeZone, java.util.Locale locale)
Constructs a new FastDateParser.protected
FastDateParser(java.lang.String pattern, java.util.TimeZone timeZone, java.util.Locale locale, java.util.Date centuryStart)
Constructs a new FastDateParser.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private int
adjustYear(int twoDigitYear)
Adjusts dates to be within appropriate centuryprivate static java.util.Map<java.lang.String,java.lang.Integer>
appendDisplayNames(java.util.Calendar calendar, java.util.Locale locale, int field, java.lang.StringBuilder regex)
Gets the short and long values displayed for a fieldboolean
equals(java.lang.Object obj)
Compares another object for equality with this object.private static java.util.concurrent.ConcurrentMap<java.util.Locale,FastDateParser.Strategy>
getCache(int field)
Gets a cache of Strategies for a particular fieldjava.util.Locale
getLocale()
Gets the locale used by this parser.private FastDateParser.Strategy
getLocaleSpecificStrategy(int field, java.util.Calendar definingCalendar)
Constructs a Strategy that parses a Text fieldjava.lang.String
getPattern()
Gets the pattern used by this parser.private FastDateParser.Strategy
getStrategy(char f, int width, java.util.Calendar definingCalendar)
Gets a Strategy given a field from a SimpleDateFormat patternjava.util.TimeZone
getTimeZone()
Gets the time zone used by this parser.int
hashCode()
Returns a hash code compatible with equals.private void
init(java.util.Calendar definingCalendar)
Initializes derived fields from defining fields.private static boolean
isFormatLetter(char c)
java.util.Date
parse(java.lang.String source)
Equivalent to DateFormat.parse(String).java.util.Date
parse(java.lang.String source, java.text.ParsePosition pos)
This implementation updates the ParsePosition if the parse succeeds.boolean
parse(java.lang.String source, java.text.ParsePosition pos, java.util.Calendar calendar)
Parses a formatted date string according to the format.java.lang.Object
parseObject(java.lang.String source)
Parses text from a string to produce a Date.java.lang.Object
parseObject(java.lang.String source, java.text.ParsePosition pos)
Parses a date/time string according to the given parse position.private void
readObject(java.io.ObjectInputStream in)
Creates the object after serialization.private static java.lang.StringBuilder
simpleQuote(java.lang.StringBuilder sb, java.lang.String value)
java.lang.String
toString()
Gets a string version of this formatter.java.lang.String
toStringAll()
Converts all state of this instance to a String handy for debugging.
-
-
-
Field Detail
-
serialVersionUID
private static final long serialVersionUID
Required for serialization support.- See Also:
Serializable
, Constant Field Values
-
JAPANESE_IMPERIAL
static final java.util.Locale JAPANESE_IMPERIAL
-
pattern
private final java.lang.String pattern
-
timeZone
private final java.util.TimeZone timeZone
-
locale
private final java.util.Locale locale
-
century
private final int century
-
startYear
private final int startYear
-
patterns
private transient java.util.List<FastDateParser.StrategyAndWidth> patterns
-
LONGER_FIRST_LOWERCASE
private static final java.util.Comparator<java.lang.String> LONGER_FIRST_LOWERCASE
-
caches
private static final java.util.concurrent.ConcurrentMap<java.util.Locale,FastDateParser.Strategy>[] caches
-
ABBREVIATED_YEAR_STRATEGY
private static final FastDateParser.Strategy ABBREVIATED_YEAR_STRATEGY
-
NUMBER_MONTH_STRATEGY
private static final FastDateParser.Strategy NUMBER_MONTH_STRATEGY
-
LITERAL_YEAR_STRATEGY
private static final FastDateParser.Strategy LITERAL_YEAR_STRATEGY
-
WEEK_OF_YEAR_STRATEGY
private static final FastDateParser.Strategy WEEK_OF_YEAR_STRATEGY
-
WEEK_OF_MONTH_STRATEGY
private static final FastDateParser.Strategy WEEK_OF_MONTH_STRATEGY
-
DAY_OF_YEAR_STRATEGY
private static final FastDateParser.Strategy DAY_OF_YEAR_STRATEGY
-
DAY_OF_MONTH_STRATEGY
private static final FastDateParser.Strategy DAY_OF_MONTH_STRATEGY
-
DAY_OF_WEEK_STRATEGY
private static final FastDateParser.Strategy DAY_OF_WEEK_STRATEGY
-
DAY_OF_WEEK_IN_MONTH_STRATEGY
private static final FastDateParser.Strategy DAY_OF_WEEK_IN_MONTH_STRATEGY
-
HOUR_OF_DAY_STRATEGY
private static final FastDateParser.Strategy HOUR_OF_DAY_STRATEGY
-
HOUR24_OF_DAY_STRATEGY
private static final FastDateParser.Strategy HOUR24_OF_DAY_STRATEGY
-
HOUR12_STRATEGY
private static final FastDateParser.Strategy HOUR12_STRATEGY
-
HOUR_STRATEGY
private static final FastDateParser.Strategy HOUR_STRATEGY
-
MINUTE_STRATEGY
private static final FastDateParser.Strategy MINUTE_STRATEGY
-
SECOND_STRATEGY
private static final FastDateParser.Strategy SECOND_STRATEGY
-
MILLISECOND_STRATEGY
private static final FastDateParser.Strategy MILLISECOND_STRATEGY
-
-
Constructor Detail
-
FastDateParser
protected FastDateParser(java.lang.String pattern, java.util.TimeZone timeZone, java.util.Locale locale)
Constructs a new FastDateParser.
UseFastDateFormat.getInstance(String, TimeZone, Locale)
or another variation of the factory methods ofFastDateFormat
to get a cached FastDateParser instance.- Parameters:
pattern
- non-nullSimpleDateFormat
compatible patterntimeZone
- non-null time zone to uselocale
- non-null locale
-
FastDateParser
protected FastDateParser(java.lang.String pattern, java.util.TimeZone timeZone, java.util.Locale locale, java.util.Date centuryStart)
Constructs a new FastDateParser.
- Parameters:
pattern
- non-nullSimpleDateFormat
compatible patterntimeZone
- non-null time zone to uselocale
- non-null localecenturyStart
- The start of the century for 2 digit year parsing- Since:
- 3.5
-
-
Method Detail
-
init
private void init(java.util.Calendar definingCalendar)
Initializes derived fields from defining fields. This is called from constructor and from readObject (de-serialization)- Parameters:
definingCalendar
- theCalendar
instance used to initialize this FastDateParser
-
isFormatLetter
private static boolean isFormatLetter(char c)
-
getPattern
public java.lang.String getPattern()
Description copied from interface:DateParser
Gets the pattern used by this parser.
- Specified by:
getPattern
in interfaceDateParser
- Returns:
- the pattern,
SimpleDateFormat
compatible
-
getTimeZone
public java.util.TimeZone getTimeZone()
Description copied from interface:DateParser
Gets the time zone used by this parser.
The default
TimeZone
used to create aDate
when theTimeZone
is not specified by the format pattern.- Specified by:
getTimeZone
in interfaceDateParser
- Returns:
- the time zone
-
getLocale
public java.util.Locale getLocale()
Description copied from interface:DateParser
Gets the locale used by this parser.
- Specified by:
getLocale
in interfaceDateParser
- Returns:
- the locale
-
equals
public boolean equals(java.lang.Object obj)
Compares another object for equality with this object.
- Overrides:
equals
in classjava.lang.Object
- Parameters:
obj
- the object to compare to- Returns:
true
if equal to this instance
-
hashCode
public int hashCode()
Returns a hash code compatible with equals.
- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- a hash code compatible with equals
-
toString
public java.lang.String toString()
Gets a string version of this formatter.
- Overrides:
toString
in classjava.lang.Object
- Returns:
- a debugging string
-
toStringAll
public java.lang.String toStringAll()
Converts all state of this instance to a String handy for debugging.- Returns:
- a string.
- Since:
- 3.12.0
-
readObject
private void readObject(java.io.ObjectInputStream in) throws java.io.IOException, java.lang.ClassNotFoundException
Creates the object after serialization. This implementation reinitializes the transient properties.- Parameters:
in
- ObjectInputStream from which the object is being deserialized.- Throws:
java.io.IOException
- if there is an IO issue.java.lang.ClassNotFoundException
- if a class cannot be found.
-
parseObject
public java.lang.Object parseObject(java.lang.String source) throws java.text.ParseException
Description copied from interface:DateParser
Parses text from a string to produce a Date.- Specified by:
parseObject
in interfaceDateParser
- Parameters:
source
- AString
whose beginning should be parsed.- Returns:
- a
java.util.Date
object - Throws:
java.text.ParseException
- if the beginning of the specified string cannot be parsed.- See Also:
Format.parseObject(String)
-
parse
public java.util.Date parse(java.lang.String source) throws java.text.ParseException
Description copied from interface:DateParser
Equivalent to DateFormat.parse(String). SeeDateFormat.parse(String)
for more information.- Specified by:
parse
in interfaceDateParser
- Parameters:
source
- AString
whose beginning should be parsed.- Returns:
- A
Date
parsed from the string - Throws:
java.text.ParseException
- if the beginning of the specified string cannot be parsed.
-
parseObject
public java.lang.Object parseObject(java.lang.String source, java.text.ParsePosition pos)
Description copied from interface:DateParser
Parses a date/time string according to the given parse position.- Specified by:
parseObject
in interfaceDateParser
- Parameters:
source
- AString
whose beginning should be parsed.pos
- the parse position- Returns:
- a
java.util.Date
object - See Also:
DateFormat.parseObject(String, ParsePosition)
-
parse
public java.util.Date parse(java.lang.String source, java.text.ParsePosition pos)
This implementation updates the ParsePosition if the parse succeeds. However, it sets the error index to the position before the failed field unlike the methodSimpleDateFormat.parse(String, ParsePosition)
which sets the error index to after the failed field.To determine if the parse has succeeded, the caller must check if the current parse position given by
ParsePosition.getIndex()
has been updated. If the input buffer has been fully parsed, then the index will point to just after the end of the input buffer.- Specified by:
parse
in interfaceDateParser
- Parameters:
source
- AString
, part of which should be parsed.pos
- AParsePosition
object with index and error index information as described above.- Returns:
- A
Date
parsed from the string. In case of error, returns null. - See Also:
DateParser.parse(java.lang.String, java.text.ParsePosition)
-
parse
public boolean parse(java.lang.String source, java.text.ParsePosition pos, java.util.Calendar calendar)
Parses a formatted date string according to the format. Updates the Calendar with parsed fields. Upon success, the ParsePosition index is updated to indicate how much of the source text was consumed. Not all source text needs to be consumed. Upon parse failure, ParsePosition error index is updated to the offset of the source text which does not match the supplied format.- Specified by:
parse
in interfaceDateParser
- Parameters:
source
- The text to parse.pos
- On input, the position in the source to start parsing, on output, updated position.calendar
- The calendar into which to set parsed fields.- Returns:
- true, if source has been parsed (pos parsePosition is updated); otherwise false (and pos errorIndex is updated)
- Throws:
java.lang.IllegalArgumentException
- when Calendar has been set to be not lenient, and a parsed field is out of range.
-
simpleQuote
private static java.lang.StringBuilder simpleQuote(java.lang.StringBuilder sb, java.lang.String value)
-
appendDisplayNames
private static java.util.Map<java.lang.String,java.lang.Integer> appendDisplayNames(java.util.Calendar calendar, java.util.Locale locale, int field, java.lang.StringBuilder regex)
Gets the short and long values displayed for a field- Parameters:
calendar
- The calendar to obtain the short and long valueslocale
- The locale of display namesfield
- The field of interestregex
- The regular expression to build- Returns:
- The map of string display names to field values
-
adjustYear
private int adjustYear(int twoDigitYear)
Adjusts dates to be within appropriate century- Parameters:
twoDigitYear
- The year to adjust- Returns:
- A value between centuryStart(inclusive) to centuryStart+100(exclusive)
-
getStrategy
private FastDateParser.Strategy getStrategy(char f, int width, java.util.Calendar definingCalendar)
Gets a Strategy given a field from a SimpleDateFormat pattern- Parameters:
f
- A sub-sequence of the SimpleDateFormat patterndefiningCalendar
- The calendar to obtain the short and long values- Returns:
- The Strategy that will handle parsing for the field
-
getCache
private static java.util.concurrent.ConcurrentMap<java.util.Locale,FastDateParser.Strategy> getCache(int field)
Gets a cache of Strategies for a particular field- Parameters:
field
- The Calendar field- Returns:
- a cache of Locale to Strategy
-
getLocaleSpecificStrategy
private FastDateParser.Strategy getLocaleSpecificStrategy(int field, java.util.Calendar definingCalendar)
Constructs a Strategy that parses a Text field- Parameters:
field
- The Calendar fielddefiningCalendar
- The calendar to obtain the short and long values- Returns:
- a TextStrategy for the field and Locale
-
-