freemarker.template.utility

Class DateUtil

java.lang.Object

freemarker.template.utility.DateUtil

public class DateUtil
extends Object

Date and time related utilities.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	DateUtil.CalendarFieldsToDateConverter Used internally by DateUtil; don't use its implementations for anything else.
static class	DateUtil.DateParseException
static interface	DateUtil.DateToISO8601CalendarFactory Used internally by DateUtil; 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 and Description
static int	ACCURACY_HOURS Show hours (24h); always 2 digits, like 00, 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 TimeZone	UTC

Method Summary

Modifier and Type	Method and Description
static String	dateToISO8601String(Date date, boolean datePart, boolean timePart, boolean offsetPart, int accuracy, 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 String	dateToXSString(Date date, boolean datePart, boolean timePart, boolean offsetPart, int accuracy, TimeZone timeZone, DateUtil.DateToISO8601CalendarFactory calendarFactory) Same as dateToISO8601String(java.util.Date, boolean, boolean, boolean, int, java.util.TimeZone, freemarker.template.utility.DateUtil.DateToISO8601CalendarFactory), but gives XML Schema compliant format.
static TimeZone	getTimeZone(String name) Returns the time zone object for the name (or ID).
static Date	parseISO8601Date(String dateStr, TimeZone defaultTimeZone, DateUtil.CalendarFieldsToDateConverter calToDateConverter) Same as parseXSDate(String, TimeZone, CalendarFieldsToDateConverter), but for ISO 8601 dates.
static Date	parseISO8601DateTime(String dateTimeStr, TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) Same as parseXSDateTime(String, TimeZone, CalendarFieldsToDateConverter) but for ISO 8601 format.
static Date	parseISO8601Time(String timeStr, TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) Same as parseXSTime(String, TimeZone, CalendarFieldsToDateConverter) but for ISO 8601 times.
static Date	parseXSDate(String dateStr, TimeZone defaultTimeZone, DateUtil.CalendarFieldsToDateConverter calToDateConverter) Parses an W3C XML Schema date string (not time or date-time).
static Date	parseXSDateTime(String dateTimeStr, TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) Parses an W3C XML Schema date-time string (not date or time).
static Date	parseXSTime(String timeStr, TimeZone defaultTZ, DateUtil.CalendarFieldsToDateConverter calToDateConverter) Parses an W3C XML Schema time string (not date or date-time).
static TimeZone	parseXSTimeZone(String timeZoneStr) Parses the time zone part from a W3C XML Schema date/time/dateTime.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ACCURACY_HOURS

public static final int ACCURACY_HOURS

Show hours (24h); always 2 digits, like 00, 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 TimeZone UTC

Method Detail

getTimeZone

public static TimeZone getTimeZone(String name)
                            throws UnrecognizedTimeZoneException

Returns the time zone object for the name (or ID). This differs from TimeZone.getTimeZone(String) in that the latest returns GMT if it doesn't recognize the name, while this throws an UnrecognizedTimeZoneException.

Throws:

UnrecognizedTimeZoneException - If the time zone name wasn't understood

dateToISO8601String

public static String dateToISO8601String(Date date,
                                         boolean datePart,
                                         boolean timePart,
                                         boolean offsetPart,
                                         int accuracy,
                                         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 string

datePart - whether the date part (year, month, day) will be included or not

timePart - whether the time part (hours, minutes, seconds, milliseconds) will be included or not

offsetPart - 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 be true when timePart is false, because ISO 8601 (2004) doesn't mention such patterns.

accuracy - tells which parts of the date/time to drop. The datePart and timePart parameters are stronger than this. Note that when ACCURACY_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 find UTC 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 String dateToXSString(Date date,
                                    boolean datePart,
                                    boolean timePart,
                                    boolean offsetPart,
                                    int accuracy,
                                    TimeZone timeZone,
                                    DateUtil.DateToISO8601CalendarFactory calendarFactory)

Same as dateToISO8601String(java.util.Date, boolean, boolean, boolean, int, java.util.TimeZone, freemarker.template.utility.DateUtil.DateToISO8601CalendarFactory), but gives XML Schema compliant format.

parseXSDate

public static Date parseXSDate(String dateStr,
                               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 be null.

calToDateConverter - Used internally to calculate the result from the calendar field values. If you don't have a such object around, you can just use new DateUtil.TrivialCalendarFieldsToDateConverter().

Throws:

DateUtil.DateParseException - if the date is malformed, or if the time zone offset is unspecified and the defaultTimeZone is null.

parseISO8601Date

public static Date parseISO8601Date(String dateStr,
                                    TimeZone defaultTimeZone,
                                    DateUtil.CalendarFieldsToDateConverter calToDateConverter)
                             throws DateUtil.DateParseException

Same as parseXSDate(String, TimeZone, CalendarFieldsToDateConverter), but for ISO 8601 dates.

Throws:

DateUtil.DateParseException

parseXSTime

public static Date parseXSTime(String timeStr,
                               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 the defaultTZ paramter will be used.

Throws:

DateUtil.DateParseException

parseISO8601Time

public static Date parseISO8601Time(String timeStr,
                                    TimeZone defaultTZ,
                                    DateUtil.CalendarFieldsToDateConverter calToDateConverter)
                             throws DateUtil.DateParseException

Same as parseXSTime(String, TimeZone, CalendarFieldsToDateConverter) but for ISO 8601 times.

Throws:

DateUtil.DateParseException

parseXSDateTime

public static Date parseXSDateTime(String dateTimeStr,
                                   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 be null.

Throws:

DateUtil.DateParseException - if the dateTime is malformed.

parseISO8601DateTime

public static Date parseISO8601DateTime(String dateTimeStr,
                                        TimeZone defaultTZ,
                                        DateUtil.CalendarFieldsToDateConverter calToDateConverter)
                                 throws DateUtil.DateParseException

Same as parseXSDateTime(String, TimeZone, CalendarFieldsToDateConverter) but for ISO 8601 format.

Throws:

DateUtil.DateParseException

parseXSTimeZone

public static TimeZone parseXSTimeZone(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.