net.sf.mmm.util.date.api

Interface Iso8601Util

All Superinterfaces:

Iso8601UtilLimited

All Known Implementing Classes:

Iso8601UtilImpl

@ComponentSpecification
public interface Iso8601Util
extends Iso8601UtilLimited

This 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.
ATTENTION:
If you are using java 8+ please use java.time where everything is build in and APIs are clean.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

Iso8601UtilImpl

Field Summary

Fields

Modifier and Type	Field and Description
static String	CDI_NAME The CDI name.
static Pattern	PATTERN_ALL The regex-pattern to check the format.

Fields inherited from interface net.sf.mmm.util.date.api.Iso8601UtilLimited

PATTERN_STRING_ALL, PATTERN_STRING_DATE, PATTERN_STRING_TIME, PATTERN_STRING_TIMEZONE

Method Summary

Modifier and Type	Method and Description
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	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 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 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.
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.

Methods inherited from interface net.sf.mmm.util.date.api.Iso8601UtilLimited

formatDate, formatDate, formatDate, formatDateTime, formatDateTime, formatDateTime, formatTime, formatTimeZone, parseDate

Field Detail

CDI_NAME

static final String CDI_NAME

The CDI name.

See Also:

Constant Field Values

PATTERN_ALL

static final Pattern PATTERN_ALL

The regex-pattern to check the format.

Method Detail

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(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 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 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(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

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.