net.sf.mmm.util.date.api
Interface Iso8601Util

All Known Implementing Classes:

Iso8601UtilImpl

@ComponentSpecification
public interface Iso8601Util

This class is a collection of utility functions for formatting and parsing dates according to ISO 8601 formats.
The ISO 8601 defines multiple formats for date and times. The following forms are handled by this implementation:

Type	Basic	Extended	Special
Date	yyyyMMdd	yyyy-MM-dd
Time	HHmmss	HH:mm:ss
Timezone	±HH[mm[ss]]	±HH[:mm[:ss]]	'Z'

Please note that the special timezone character Z means UTC.
Out of these forms the following combinations are supported:

• <Date>
• <Date>T<Time>
• <Date>T<Time><Timezone>

Examples:

• 1999-12-31
• 1999-12-31T23:59:59
• 1999-12-31T23:59:59+01:00
• 2000-01-01T00:00:00Z
• 20000101T000000Z

As you can see by the example the basic format is harder to read (for humans). Therefore you should use the extended format if possible.
The parse methods support all formats described above. For formatting various methods exist for different format combinations.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

Iso8601UtilImpl

Field Summary

static Pattern	PATTERN_ALL The regex-pattern to check the format.
static String	PATTERN_STRING_ALL The regex-pattern for the full date-format (date with optional time and optional timezone).
static String	PATTERN_STRING_DATE The regex-pattern for the date-format.
static String	PATTERN_STRING_TIME The regex-pattern for the time-format.
static String	PATTERN_STRING_TIMEZONE The regex-pattern for the timezone-format.

Method Summary

String	formatDate(Calendar calendar) This method formats the given calendar as a date in the format "yyyy-MM-dd" according to ISO 8601.
String	formatDate(Calendar calendar, boolean extended) This method formats the given calendar as a date in the format "yyyy-MM-dd" according to ISO 8601.
void	formatDate(Calendar calendar, boolean extended, Appendable buffer) This method formats the given calendar as a date according to ISO 8601.
String	formatDate(Date date) This method formats the given date in the format "yyyy-MM-dd" in GMT according to ISO 8601.
String	formatDateTime(Calendar calendar) This method formats the given calendar as a date and time in the format "yyyy-MM-ddTHH:mm:ss±hh:mm" according to ISO 8601.
String	formatDateTime(Calendar calendar, boolean extendedDate, boolean extendedTime, boolean extendedTimezone) This method formats the given calendar as a date and time in the format "yyyy-MM-ddTHH:mm:ss±hh:mm" according to ISO 8601.
void	formatDateTime(Calendar calendar, boolean extendedDate, boolean extendedTime, boolean extendedTimezone, Appendable buffer) This method formats the given calendar as a date and time in the format "yyyy-MM-ddTHH:mm:ss±hh:mm" according to ISO 8601.
String	formatDateTime(Date date) This method formats the given date as a date and time in the format "yyyy-MM-ddTHH:mm:ssZ" (UTC) according to ISO 8601.
void	formatTime(Calendar calendar, boolean extended, Appendable buffer) This method formats the given calendar as time according to ISO 8601.
void	formatTimeZone(Calendar calendar, boolean extended, Appendable buffer) This method formats the given timezone according to ISO 8601.
void	formatTimeZone(int timezoneOffset, boolean extended, Appendable buffer) This method formats the given timezone according to ISO 8601.
Calendar	parseCalendar(String date) This method parses the given string date according to ISO 8601.
void	parseCalendar(String date, Calendar calendar) This method parses the given date according to ISO 8601 using the given calendar.
Date	parseDate(String date) This method parses the given string date according to ISO 8601.

Field Detail

PATTERN_STRING_DATE

static final String PATTERN_STRING_DATE

The regex-pattern for the date-format.

See Also:

Constant Field Values

PATTERN_STRING_TIME

static final String PATTERN_STRING_TIME

The regex-pattern for the time-format.

See Also:

Constant Field Values

PATTERN_STRING_TIMEZONE

static final String PATTERN_STRING_TIMEZONE

The regex-pattern for the timezone-format.

See Also:

Constant Field Values

PATTERN_STRING_ALL

static final String PATTERN_STRING_ALL

The regex-pattern for the full date-format (date with optional time and optional timezone).

See Also:

Constant Field Values

PATTERN_ALL

static final Pattern PATTERN_ALL

The regex-pattern to check the format.

Method Detail

formatDate

String formatDate(Date date)

This method formats the given date in the format "yyyy-MM-dd" in GMT according to ISO 8601.

Parameters:

date - is the date to format.

Returns:

the given date as date string.

formatDate

String formatDate(Calendar calendar)

This method formats the given calendar as a date in the format "yyyy-MM-dd" according to ISO 8601.

Parameters:

calendar - is the date to format.

Returns:

the given calendar as date string.

formatDate

String formatDate(Calendar calendar,
                  boolean extended)

This method formats the given calendar as a date in the format "yyyy-MM-dd" according to ISO 8601.

Parameters:

calendar - is the date to format.

extended - if false the basic format ("yyyyMMdd") is used, if true the extended format ("yyyy-MM-dd") is used.

Returns:

the given calendar as date string.

formatDate

void formatDate(Calendar calendar,
                boolean extended,
                Appendable buffer)

This method formats the given calendar as a date according to ISO 8601.

Parameters:

calendar - is the date to format.

extended - if false the basic date format ("yyyyMMdd") is used, if true the extended date format ("yyyy-MM-dd") is used.

buffer - is where to append the formatted date.

formatDateTime

String formatDateTime(Date date)

This method formats the given date as a date and time in the format "yyyy-MM-ddTHH:mm:ssZ" (UTC) according to ISO 8601.

Parameters:

date - is the date to format.

Returns:

the given calendar as date string.

formatDateTime

String formatDateTime(Calendar calendar)

This method formats the given calendar as a date and time in the format "yyyy-MM-ddTHH:mm:ss±hh:mm" according to ISO 8601.

Parameters:

calendar - is the date to format.

Returns:

the given calendar as date string.

formatDateTime

String formatDateTime(Calendar calendar,
                      boolean extendedDate,
                      boolean extendedTime,
                      boolean extendedTimezone)

This method formats the given calendar as a date and time in the format "yyyy-MM-ddTHH:mm:ss±hh:mm" according to ISO 8601.

Parameters:

calendar - is the Calendar to format.

extendedDate - if false the basic date format ("yyyyMMdd") is used, if true the extended date format ("yyyy-MM-dd") is used.

extendedTime - if false the basic time format ("HHmmss") is used, if true the extended time format ("HH:mm:ss") is used.

extendedTimezone - if false the basic timezone format ("±HHmm[ss]") is used, if true the extended timezone format ("±HH:mm[:ss]") is used.

Returns:

the given calendar as date string.

formatDateTime

void formatDateTime(Calendar calendar,
                    boolean extendedDate,
                    boolean extendedTime,
                    boolean extendedTimezone,
                    Appendable buffer)

This method formats the given calendar as a date and time in the format "yyyy-MM-ddTHH:mm:ss±hh:mm" according to ISO 8601.

Parameters:

calendar - is the Calendar to format.

extendedDate - if false the basic date format ("yyyyMMdd") is used, if true the extended date format ("yyyy-MM-dd") is used.

extendedTime - if false the basic time format ("HHmmss") is used, if true the extended time format ("HH:mm:ss") is used.

extendedTimezone - if false the basic timezone format ("±HHmm[ss]") is used, if true the extended timezone format ("±HH:mm[:ss]") is used.

buffer - is where to append the formatted date and time.

formatTime

void formatTime(Calendar calendar,
                boolean extended,
                Appendable buffer)

This method formats the given calendar as time according to ISO 8601.

Parameters:

calendar - is the Calendar to format.

extended - if false the basic time format ("HHmmss") is used, if true the extended time format ("HH:mm:ss") is used.

buffer - is where to append the formatted date.

formatTimeZone

void formatTimeZone(int timezoneOffset,
                    boolean extended,
                    Appendable buffer)

This method formats the given timezone according to ISO 8601.

Parameters:

timezoneOffset - is the timezone-offset in milliseconds.

extended - - if false the basic timezone format ("±HHmm[ss]") is used, if true the extended timezone format ("±HH:mm[:ss]") is used.

buffer - is where to append the formatted timezone.

formatTimeZone

void formatTimeZone(Calendar calendar,
                    boolean extended,
                    Appendable buffer)

This method formats the given timezone according to ISO 8601.

Parameters:

calendar - is the Calendar to format.

extended - - if false the basic timezone format ("±HHmm[ss]") is used, if true the extended timezone format ("±HH:mm[:ss]") is used.

buffer - is where to append the formatted timezone.

Since:

2.0.0

parseDate

Date parseDate(String date)

This method parses the given string date according to ISO 8601.

Parameters:

date - is the date to parse.

Returns:

the parsed date.

parseCalendar

Calendar parseCalendar(String date)

This method parses the given string date according to ISO 8601.

Parameters:

date - is the date to parse.

Returns:

the parsed date.

parseCalendar

void parseCalendar(String date,
                   Calendar calendar)

This method parses the given date according to ISO 8601 using the given calendar. If the given date does NOT specify the time or timezone, the values from the given calendar will be kept.

Parameters:

date - is the date to parse.

calendar - is the calendar where the parsed date will be set.