Package freemarker.template.utility
Class DateUtil
- java.lang.Object
-
- freemarker.template.utility.DateUtil
-
public class DateUtil extends java.lang.Object
Date and time related utilities.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
DateUtil.CalendarFieldsToDateConverter
Used internally byDateUtil
; don't use its implementations for anything else.static class
DateUtil.DateParseException
static interface
DateUtil.DateToISO8601CalendarFactory
Used internally byDateUtil
; don't use its implementations for anything else.static class
DateUtil.TrivialCalendarFieldsToDateConverter
Non-thread-safe implementation that hard-references a calendar internally.static class
DateUtil.TrivialDateToISO8601CalendarFactory
Non-thread-safe factory that hard-references a calendar internally.
-
Field Summary
Fields Modifier and Type Field Description static int
ACCURACY_HOURS
Show hours (24h); always 2 digits, like00
,05
, etc.static int
ACCURACY_MILLISECONDS
Show hours, minutes and seconds and up to 3 fraction second digits, without trailing 0-s in the fraction part.static int
ACCURACY_MILLISECONDS_FORCED
Show hours, minutes and seconds and exactly 3 fraction second digits (even if it's 000)static int
ACCURACY_MINUTES
Show hours and minutes (even if minutes is 00).static int
ACCURACY_SECONDS
Show hours, minutes and seconds (even if seconds is 00).static java.util.TimeZone
UTC
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.lang.String
dateToISO8601String(java.util.Date date, boolean datePart, boolean timePart, boolean offsetPart, int accuracy, java.util.TimeZone timeZone, DateUtil.DateToISO8601CalendarFactory calendarFactory)
Format a date, time or dateTime with one of the ISO 8601 extended formats that is also compatible with the XML Schema format (as far as you don't have dates in the BC era).static java.lang.String
dateToXSString(java.util.Date date, boolean datePart, boolean timePart, boolean offsetPart, int accuracy, java.util.TimeZone timeZone, DateUtil.DateToISO8601CalendarFactory calendarFactory)
Same asdateToISO8601String(java.util.Date, boolean, boolean, boolean, int, java.util.TimeZone, freemarker.template.utility.DateUtil.DateToISO8601CalendarFactory)
, but gives XML Schema compliant format.static java.util.TimeZone
getTimeZone(java.lang.String name)
Returns the time zone object for the name (or ID).static java.util.Date
parseISO8601Date(java.lang.String dateStr, java.util.TimeZone defaultTimeZone, DateUtil.CalendarFieldsToDateConverter calToDateConverter)
Same asparseXSDate(String, TimeZone, CalendarFieldsToDateConverter)
, but for ISO 8601 dates.static java.util.Date
parseISO8601DateTime(java.lang.String dateTimeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter)
Same asparseXSDateTime(String, TimeZone, CalendarFieldsToDateConverter)
but for ISO 8601 format.static java.util.Date
parseISO8601Time(java.lang.String timeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter)
Same asparseXSTime(String, TimeZone, CalendarFieldsToDateConverter)
but for ISO 8601 times.static java.util.Date
parseXSDate(java.lang.String dateStr, java.util.TimeZone defaultTimeZone, DateUtil.CalendarFieldsToDateConverter calToDateConverter)
Parses an W3C XML Schema date string (not time or date-time).static java.util.Date
parseXSDateTime(java.lang.String dateTimeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter)
Parses an W3C XML Schema date-time string (not date or time).static java.util.Date
parseXSTime(java.lang.String timeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter)
Parses an W3C XML Schema time string (not date or date-time).static java.util.TimeZone
parseXSTimeZone(java.lang.String timeZoneStr)
Parses the time zone part from a W3C XML Schema date/time/dateTime.
-
-
-
Field Detail
-
ACCURACY_HOURS
public static final int ACCURACY_HOURS
Show hours (24h); always 2 digits, like00
,05
, etc.- See Also:
- Constant Field Values
-
ACCURACY_MINUTES
public static final int ACCURACY_MINUTES
Show hours and minutes (even if minutes is 00).- See Also:
- Constant Field Values
-
ACCURACY_SECONDS
public static final int ACCURACY_SECONDS
Show hours, minutes and seconds (even if seconds is 00).- See Also:
- Constant Field Values
-
ACCURACY_MILLISECONDS
public static final int ACCURACY_MILLISECONDS
Show hours, minutes and seconds and up to 3 fraction second digits, without trailing 0-s in the fraction part.- See Also:
- Constant Field Values
-
ACCURACY_MILLISECONDS_FORCED
public static final int ACCURACY_MILLISECONDS_FORCED
Show hours, minutes and seconds and exactly 3 fraction second digits (even if it's 000)- See Also:
- Constant Field Values
-
UTC
public static final java.util.TimeZone UTC
-
-
Method Detail
-
getTimeZone
public static java.util.TimeZone getTimeZone(java.lang.String name) throws UnrecognizedTimeZoneException
Returns the time zone object for the name (or ID). This differs fromTimeZone.getTimeZone(String)
in that the latest returns GMT if it doesn't recognize the name, while this throws anUnrecognizedTimeZoneException
.- Throws:
UnrecognizedTimeZoneException
- If the time zone name wasn't understood
-
dateToISO8601String
public static java.lang.String dateToISO8601String(java.util.Date date, boolean datePart, boolean timePart, boolean offsetPart, int accuracy, java.util.TimeZone timeZone, DateUtil.DateToISO8601CalendarFactory calendarFactory)
Format a date, time or dateTime with one of the ISO 8601 extended formats that is also compatible with the XML Schema format (as far as you don't have dates in the BC era). Examples of possible outputs:"2005-11-27T15:30:00+02:00"
,"2005-11-27"
,"15:30:00Z"
. Note the":00"
in the time zone offset; this is not required by ISO 8601, but included for compatibility with the XML Schema format. Regarding the B.C. issue, those dates will be one year off when read back according the XML Schema format, because of a mismatch between that format and ISO 8601:2000 Second Edition.This method is thread-safe.
- Parameters:
date
- the date to convert to ISO 8601 stringdatePart
- whether the date part (year, month, day) will be included or nottimePart
- whether the time part (hours, minutes, seconds, milliseconds) will be included or notoffsetPart
- whether the time zone offset part will be included or not. This will be shown as an offset to UTC (examples:"+01"
,"-02"
,"+04:30"
) or as"Z"
for UTC (and for UT1 and for GMT+00, since the Java platform doesn't really care about the difference). Note that this can't betrue
whentimePart
isfalse
, because ISO 8601 (2004) doesn't mention such patterns.accuracy
- tells which parts of the date/time to drop. ThedatePart
andtimePart
parameters are stronger than this. Note that whenACCURACY_MILLISECONDS
is specified, the milliseconds part will be displayed as fraction seconds (like"15:30.00.25"
) with the minimum number of digits needed to show the milliseconds without precision lose. Thus, if the milliseconds happen to be exactly 0, no fraction seconds will be shown at all.timeZone
- the time zone in which the date/time will be shown. (You may findUTC
handy here.) Note that although date-only formats has no time zone offset part, the result still depends on the time zone, as days start and end at different points on the time line in different zones.calendarFactory
- the factory that will create the calendar used internally for calculations. The point of this parameter is that creating a new calendar is relatively expensive, so it's desirable to reuse calendars and only set their time and zone. (This was tested on Sun JDK 1.6 x86 Win, where it gave 2x-3x speedup.)
-
dateToXSString
public static java.lang.String dateToXSString(java.util.Date date, boolean datePart, boolean timePart, boolean offsetPart, int accuracy, java.util.TimeZone timeZone, DateUtil.DateToISO8601CalendarFactory calendarFactory)
Same asdateToISO8601String(java.util.Date, boolean, boolean, boolean, int, java.util.TimeZone, freemarker.template.utility.DateUtil.DateToISO8601CalendarFactory)
, but gives XML Schema compliant format.
-
parseXSDate
public static java.util.Date parseXSDate(java.lang.String dateStr, java.util.TimeZone defaultTimeZone, DateUtil.CalendarFieldsToDateConverter calToDateConverter) throws DateUtil.DateParseException
Parses an W3C XML Schema date string (not time or date-time). Unlike in ISO 8601:2000 Second Edition, year -1 means B.C 1, and year 0 is invalid.- Parameters:
dateStr
- the string to parse.defaultTimeZone
- used if the date doesn't specify the time zone offset explicitly. Can't benull
.calToDateConverter
- Used internally to calculate the result from the calendar field values. If you don't have a such object around, you can just usenew
DateUtil.TrivialCalendarFieldsToDateConverter
()
.- Throws:
DateUtil.DateParseException
- if the date is malformed, or if the time zone offset is unspecified and thedefaultTimeZone
isnull
.
-
parseISO8601Date
public static java.util.Date parseISO8601Date(java.lang.String dateStr, java.util.TimeZone defaultTimeZone, DateUtil.CalendarFieldsToDateConverter calToDateConverter) throws DateUtil.DateParseException
Same asparseXSDate(String, TimeZone, CalendarFieldsToDateConverter)
, but for ISO 8601 dates.- Throws:
DateUtil.DateParseException
-
parseXSTime
public static java.util.Date parseXSTime(java.lang.String timeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) throws DateUtil.DateParseException
Parses an W3C XML Schema time string (not date or date-time). If the time string doesn't specify the time zone offset explicitly, the value of thedefaultTZ
paramter will be used.- Throws:
DateUtil.DateParseException
-
parseISO8601Time
public static java.util.Date parseISO8601Time(java.lang.String timeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) throws DateUtil.DateParseException
Same asparseXSTime(String, TimeZone, CalendarFieldsToDateConverter)
but for ISO 8601 times.- Throws:
DateUtil.DateParseException
-
parseXSDateTime
public static java.util.Date parseXSDateTime(java.lang.String dateTimeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) throws DateUtil.DateParseException
Parses an W3C XML Schema date-time string (not date or time). Unlike in ISO 8601:2000 Second Edition, year -1 means B.C 1, and year 0 is invalid.- Parameters:
dateTimeStr
- the string to parse.defaultTZ
- used if the dateTime doesn't specify the time zone offset explicitly. Can't benull
.- Throws:
DateUtil.DateParseException
- if the dateTime is malformed.
-
parseISO8601DateTime
public static java.util.Date parseISO8601DateTime(java.lang.String dateTimeStr, java.util.TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) throws DateUtil.DateParseException
Same asparseXSDateTime(String, TimeZone, CalendarFieldsToDateConverter)
but for ISO 8601 format.- Throws:
DateUtil.DateParseException
-
parseXSTimeZone
public static java.util.TimeZone parseXSTimeZone(java.lang.String timeZoneStr) throws DateUtil.DateParseException
Parses the time zone part from a W3C XML Schema date/time/dateTime.- Throws:
DateUtil.DateParseException
- if the zone is malformed.
-
-