org.apache.jackrabbit.util

Class ISO8601

java.lang.Object

org.apache.jackrabbit.util.ISO8601

public final class ISO8601
extends Object

The ISO8601 utility class provides helper methods to deal with date/time formatting using a specific ISO8601-compliant format (see ISO 8601).

The currently supported format is:

   ±YYYY-MM-DDThh:mm:ss.SSSTZD
 

where:

   ±YYYY = four-digit year with optional sign where values <= 0 are
           denoting years BCE and values > 0 are denoting years CE,
           e.g. -0001 denotes the year 2 BCE, 0000 denotes the year 1 BCE,
           0001 denotes the year 1 CE, and so on...
   MM    = two-digit month (01=January, etc.)
   DD    = two-digit day of month (01 through 31)
   hh    = two digits of hour (00 through 23) (am/pm NOT allowed)
   mm    = two digits of minute (00 through 59)
   ss    = two digits of second (00 through 59)
   SSS   = three digits of milliseconds (000 through 999)
   TZD   = time zone designator, Z for Zulu (i.e. UTC) or an offset from UTC
           in the form of +hh:mm or -hh:mm
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ISO8601.SHORT Variants that exclude the milliseconds from the formatted string.

Constructor Summary

Constructors

Constructor and Description
ISO8601()

Method Summary

Modifier and Type	Method and Description
static String	format(Calendar cal) Formats a Calendar value into an ISO8601-compliant date/time string.
static String	format(Clock clock) Formats a clock time instant into an ISO8601-compliant date/time string.
static String	format(Date date) Formats a time instant into an ISO8601-compliant date/time string using the UTC timezone.
static String	format(Date date, int tzOffsetInSeconds) Formats a time instant and a timezone offset into an ISO8601-compliant date/time string.
static String	format(long millisSinceEpoch) Formats a time instant into an ISO8601-compliant date/time string using the UTC timezone.
static String	format(long millisSinceEpoch, int tzOffsetInSeconds) Formats a time instant and a timezone offset into an ISO8601-compliant date/time string.
static int	getYear(Calendar cal) Returns the astronomical year of the given calendar.
static Calendar	parse(String text) Parses an ISO8601-compliant date/time string.

Methods inherited from class java.lang.Object

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

Constructor Detail

ISO8601

public ISO8601()

Method Detail

parse

public static Calendar parse(String text)

Parses an ISO8601-compliant date/time string.

Parameters:

text - the date/time string to be parsed

Returns:

a Calendar, or null if the input could not be parsed

Throws:

IllegalArgumentException - if a null argument is passed

format

public static String format(Date date)
                     throws IllegalArgumentException

Formats a time instant into an ISO8601-compliant date/time string using the UTC timezone.

Parameters:

date - date to be formatted

Returns:

the formatted date/time string.

Throws:

IllegalArgumentException - if the calendar cannot be represented as defined by ISO 8601 (i.e. year with more than four digits).

format

public static String format(Clock clock)
                     throws IllegalArgumentException

Formats a clock time instant into an ISO8601-compliant date/time string.

Parameters:

clock - clock to obtain time and time zone from

Returns:

the formatted date/time string.

Throws:

IllegalArgumentException - if the calendar cannot be represented as defined by ISO 8601 (i.e. year with more than four digits).

format

public static String format(long millisSinceEpoch)
                     throws IllegalArgumentException

Formats a time instant into an ISO8601-compliant date/time string using the UTC timezone.

Parameters:

millisSinceEpoch - milliseconds since the epoch

Returns:

the formatted date/time string.

Throws:

IllegalArgumentException - if the calendar cannot be represented as defined by ISO 8601 (i.e. year with more than four digits).

format

public static String format(Date date,
                            int tzOffsetInSeconds)
                     throws IllegalArgumentException

Formats a time instant and a timezone offset into an ISO8601-compliant date/time string.

Parameters:

date - date to be formatted

tzOffsetInSeconds - timezone offset from UTC in seconds

Returns:

the formatted date/time string.

Throws:

IllegalArgumentException - if the calendar cannot be represented as defined by ISO 8601 (i.e. year with more than four digits).

format

public static String format(long millisSinceEpoch,
                            int tzOffsetInSeconds)
                     throws IllegalArgumentException

Formats a time instant and a timezone offset into an ISO8601-compliant date/time string.

Parameters:

millisSinceEpoch - milliseconds since the epoch

tzOffsetInSeconds - timezone offset from UTC in seconds

Returns:

the formatted date/time string.

Throws:

IllegalArgumentException - if a null argument is passed the calendar cannot be represented as defined by ISO 8601 (i.e. year with more than four digits).

format

public static String format(Calendar cal)
                     throws IllegalArgumentException

Formats a Calendar value into an ISO8601-compliant date/time string.

Parameters:

cal - the time value to be formatted into a date/time string.

Returns:

the formatted date/time string.

Throws:

IllegalArgumentException - if a null argument is passed or the calendar cannot be represented as defined by ISO 8601 (i.e. year with more than four digits).

getYear

public static int getYear(Calendar cal)
                   throws IllegalArgumentException

Returns the astronomical year of the given calendar.

Parameters:

cal - a calendar instance.

Returns:

the astronomical year.

Throws:

IllegalArgumentException - if calendar cannot be represented as defined by ISO 8601 (i.e. year with more than four digits).