uws

Class ISO8601Format

java.lang.Object

uws.ISO8601Format

public class ISO8601Format
extends java.lang.Object

Let formatting and parsing date expressed in ISO8601 format.

Date formatting

Dates are formatted using the following format: "yyyy-MM-dd'T'hh:mm:ss'Z'" if in UTC or "yyyy-MM-dd'T'hh:mm:ss[+|-]hh:mm" otherwise. On the contrary to the time zone, by default the number of milliseconds is not displayed. However, when displayed, the format is: "yyyy-MM-dd'T'hh:mm:ss.sss'Z'" if in UTC or "yyyy-MM-dd'T'hh:mm:ss.sss[+|-]hh:mm" otherwise.

As said previously, it is possible to display or to hide the time zone and the milliseconds. This can be easily done by changing the value of the static attributes displayTimeZone and displayMilliseconds. By default displayTimeZone is true and displayMilliseconds is false.

By default the date will be formatted in the local time zone. But this could be specified either in the format function format(long, String, boolean, boolean) or by changing the static attribute targetTimeZone. The time zone must be specified with its ID. The list of all available time zone IDs is given by TimeZone.getAvailableIDs().

Date parsing

This class is able to parse dates - with the function parse(String) - formatted in ISO-8601. This parser allows the following general syntaxes:

• YYYY (e.g. 2015)
• YYYY-MM (e.g. 2015-12)
• YYYY-MM-DD (e.g. 2015-12-11)
• YYYY-MM-DD'T'hh:mmTZD (e.g. 2015-12-11T20:28+01:00 or 2015-12-11T19:28Z)
• YYYY-MM-DD'T'hh:mm:ssTZD (e.g. 2015-12-11T20:28:30+01:00 or 2015-12-11T19:28:30Z)
• YYYY-MM-DD'T'hh:mm:ss.sTZD (e.g. 2015-12-11T20:28:30.45+01:00 or 2015-12-11T19:28:30.45Z)

Where:

• YYYY = four-digit year
• 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)
• s = one or more digits representing a decimal fraction of a second (i.e. milliseconds)
• TZD = time zone designator (Z or +hh:mm or -hh:mm)

It is also possible to express the date in weeks with the following syntax: YYYY-'W'ww-D (e.g. 2015-W50, 2015-W50-5, 2015-W50-5T20:28:30.45+01:00). ww must a 2 digits number between 1 and the number of weeks available in the chosen year. D corresponds to the day of the week: Monday = 1, Tuesday = 2, ..., Sunday = 7.

A last representation of the date is possible: in days of year: YYYY-DDD (e.g. 2015-345, 2015-345T20:28:30.45+01:00). DDD must be a value between 1 and the number of days there is in the chosen year.

Separators (like '-', ':' and '.') are optional. The date and time separator ('T') may be replaced by a space.

Since:

4.1

Version:

4.2 (03/2017)

Author:

Grégory Mantelet (CDS;ARI)

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	displayMilliseconds Indicate whether any date formatted with this class displays the milliseconds.
static boolean	displayTimeZone Indicate whether any date formatted with this class displays the time zone.
protected static java.text.DecimalFormat	oneDigitFmt Object to use to format numbers with one digit (ie.
static java.lang.String	targetTimeZone Indicate the time zone in which the date and time should be formatted (whatever is the time zone of the given date).
protected static java.text.DecimalFormat	threeDigitsFmt Object to use to format numbers with three digits (ie.
protected static java.text.DecimalFormat	twoDigitsFmt Object to use to format numbers with two digits (ie.

Constructor Summary

Constructors

Constructor and Description
ISO8601Format()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	format(java.util.Date date) Format the given date-time in ISO8601 format.
static java.lang.String	format(long date) Format the given date-time in ISO8601 format.
static java.lang.String	format(long date, boolean withTimeZone) Convert the given date-time in the given time zone and format it in ISO8601 format.
protected static java.lang.String	format(long date, java.lang.String targetTimeZone, boolean withTimeZone, boolean withMillisec) Convert the given date in the given time zone and format it in ISO8601 format, with or without displaying the time zone and/or the milliseconds field.
static java.lang.String	formatInUTC(long date) Convert the given date-time in UTC and format it in ISO8601 format.
static java.lang.String	formatInUTC(long date, boolean withTimeZone) Convert the given date-time in UTC and format it in ISO8601 format.
static void	main(java.lang.String[] args)
static long	parse(java.lang.String strDate) Parse the given date expressed using the ISO8601 format ("yyyy-MM-dd'T'hh:mm:ss.sssZ" or "yyyy-MM-dd'T'hh:mm:ss.sssZ[+|-]hh:mm:ss").
static java.util.Date	parseToDate(java.lang.String strDate) Parse the given date expressed using the ISO8601 format ("yyyy-MM-dd'T'hh:mm:ss.sssZ" or "yyyy-MM-dd'T'hh:mm:ss.sssZ[+|-]hh:mm:ss").

Methods inherited from class java.lang.Object

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

Field Detail

displayTimeZone

public static boolean displayTimeZone

Indicate whether any date formatted with this class displays the time zone.

displayMilliseconds

public static boolean displayMilliseconds

Indicate whether any date formatted with this class displays the milliseconds.

targetTimeZone

public static java.lang.String targetTimeZone

Indicate the time zone in which the date and time should be formatted (whatever is the time zone of the given date). Note: for the local time zone, this attribute could be set to TimeZone.getDefault().getID().

oneDigitFmt

protected static final java.text.DecimalFormat oneDigitFmt

Object to use to format numbers with one digit (ie. 1, 2, 0).

Since:

4.2

twoDigitsFmt

protected static final java.text.DecimalFormat twoDigitsFmt

Object to use to format numbers with two digits (ie. 12, 02, 00).

threeDigitsFmt

protected static final java.text.DecimalFormat threeDigitsFmt

Object to use to format numbers with three digits (ie. 001, 000, 123).

Constructor Detail

ISO8601Format

public ISO8601Format()

Method Detail

format

public static java.lang.String format(java.util.Date date)

Format the given date-time in ISO8601 format.

Note: This function is equivalent to format(long, String, boolean, boolean) with the following parameters: d, ISO8601Format.targetTimeZone, ISO8601Format.displayTimeZone, ISO8601Format.displayMilliseconds.

Parameters:

date - Date-time.

Returns:

Date formatted in ISO8601.

format

public static java.lang.String format(long date)

Format the given date-time in ISO8601 format.

Note: This function is equivalent to format(long, String, boolean, boolean) with the following parameters: d, ISO8601Format.targetTimeZone, ISO8601Format.displayTimeZone, ISO8601Format.displayMilliseconds.

Parameters:

date - Date-time in milliseconds (from the 1st January 1970 ; this value is returned by java.util.Date#getTime()).

Returns:

Date formatted in ISO8601.

format

public static java.lang.String format(long date,
                                      boolean withTimeZone)

Convert the given date-time in the given time zone and format it in ISO8601 format.

Note: This function is equivalent to format(long, String, boolean, boolean) with the following parameters: d, ISO8601Format.targetTimeZone, withTimeZone, ISO8601Format.displayMilliseconds.

Parameters:

date - Date-time in milliseconds (from the 1st January 1970 ; this value is returned by java.util.Date#getTime()).

withTimeZone - Target time zone.

Returns:

Date formatted in ISO8601.

formatInUTC

public static java.lang.String formatInUTC(long date)

Convert the given date-time in UTC and format it in ISO8601 format.

Note: This function is equivalent to format(long, String, boolean, boolean) with the following parameters: d, "UTC", ISO8601Format.displayTimeZone, ISO8601Format.displayMilliseconds.

Parameters:

date - Date-time in milliseconds (from the 1st January 1970 ; this value is returned by java.util.Date#getTime()).

Returns:

Date formatted in ISO8601.

formatInUTC

public static java.lang.String formatInUTC(long date,
                                           boolean withTimeZone)

Convert the given date-time in UTC and format it in ISO8601 format.

Note: This function is equivalent to format(long, String, boolean, boolean) with the following parameters: d, "UTC", withTimeZone, ISO8601Format.displayMilliseconds.

Parameters:

date - Date-time in milliseconds (from the 1st January 1970 ; this value is returned by java.util.Date#getTime()).

withTimeZone - Target time zone.

Returns:

Date formatted in ISO8601.

format

protected static java.lang.String format(long date,
                                         java.lang.String targetTimeZone,
                                         boolean withTimeZone,
                                         boolean withMillisec)

Convert the given date in the given time zone and format it in ISO8601 format, with or without displaying the time zone and/or the milliseconds field.

Important Note: This function is synchronized because it is using (directly or in other static functions) static DecimalFormat instances. A DecimalFormat is a Java class which can be used only by one thread at a time. So format(long, String, boolean, boolean) and parse(String) (main public functions of ISO8601Format) must be synchronized in order to avoid concurrent access to the DecimalFormat instances and so to avoid unpredictable errors/results.

Parameters:

date - Date-time in milliseconds (from the 1st January 1970 ; this value is returned by java.util.Date#getTime()).

targetTimeZone - Target time zone.

withTimeZone - true to display the time zone, false otherwise.

withMillisec - true to display the milliseconds, false otherwise.

Returns:

Date formatted in ISO8601.

parseToDate

public static final java.util.Date parseToDate(java.lang.String strDate)
                                        throws java.text.ParseException

Parse the given date expressed using the ISO8601 format ("yyyy-MM-dd'T'hh:mm:ss.sssZ" or "yyyy-MM-dd'T'hh:mm:ss.sssZ[+|-]hh:mm:ss").

The syntax of the given date may be more or less strict. Particularly, separators like '-' and ':' are optional. Besides the date and time separator ('T') may be replaced by a space.

The minimum allowed string is the date: "yyyy-MM-dd". All other date-time fields are optional, BUT, the time zone can be given without the time.

If no time zone is specified (by a 'Z' or a time offset), the time zone in which the date is expressed is supposed to be the local one.

Note: This function is equivalent to parse(String), but whose the returned value is used to create a Date object, like this: return new Date(parse(strDate)).

Parameters:

strDate - Date expressed as a string in ISO8601 format.

Returns:

Parsed date (expressed in milliseconds from the 1st January 1970 ; a date can be easily built with this number using Date.Date(long)).

Throws:

java.text.ParseException - If the given date is not expressed in ISO8601 format or is not merely parseable with this implementation.

main

public static final void main(java.lang.String[] args)
                       throws java.lang.Throwable

Throws:

java.lang.Throwable

parse

public static long parse(java.lang.String strDate)
                  throws java.text.ParseException

Parse the given date expressed using the ISO8601 format ("yyyy-MM-dd'T'hh:mm:ss.sssZ" or "yyyy-MM-dd'T'hh:mm:ss.sssZ[+|-]hh:mm:ss").

This parser allows the following general syntaxes:

• YYYY (e.g. 2015)
• YYYY-MM (e.g. 2015-12)
• YYYY-MM-DD (e.g. 2015-12-11)
• YYYY-MM-DD'T'hh:mmTZD (e.g. 2015-12-11T20:28+01:00 or 2015-12-11T19:28Z)
• YYYY-MM-DD'T'hh:mm:ssTZD (e.g. 2015-12-11T20:28:30+01:00 or 2015-12-11T19:28:30Z)
• YYYY-MM-DD'T'hh:mm:ss.sTZD (e.g. 2015-12-11T20:28:30.45+01:00 or 2015-12-11T19:28:30.45Z)

Where:

• YYYY = four-digit year
• 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)
• s = one or more digits representing a decimal fraction of a second (i.e. milliseconds)
• TZD = time zone designator (Z or +hh:mm or -hh:mm)

It is also possible to express the date in weeks with the following syntax: YYYY-'W'ww-D (e.g. 2015-W50, 2015-W50-5, 2015-W50-5T20:28:30.45+01:00). ww must a 2 digits number between 1 and the number of weeks available in the chosen year. D corresponds to the day of the week: Monday = 1, Tuesday = 2, ..., Sunday = 7.

A last representation of the date is possible: in days of year: YYYY-DDD (e.g. 2015-345, 2015-345T20:28:30.45+01:00). DDD must be a value between 1 and the number of days there is in the chosen year.

If no time zone is specified (by a 'Z' or a time offset), the time zone in which the date is expressed is supposed to be the local one.

Separators (like '-', ':' and '.') are optional. The date and time separator ('T') may be replaced by a space.

Important Note: This function is synchronized because it is using (directly or in other static functions) static DecimalFormat instances. A DecimalFormat is a Java class which can be used only by one thread at a time. So format(long, String, boolean, boolean) and parse(String) (main public functions of ISO8601Format) must be synchronized in order to avoid concurrent access to the DecimalFormat instances and so to avoid unpredictable errors/results.

Parameters:

strDate - Date expressed as a string in ISO8601 format.

Returns:

Parsed date (expressed in milliseconds from the 1st January 1970 ; a date can be easily built with this number using Date.Date(long)).

Throws:

java.text.ParseException - If the given date is not expressed in ISO8601 format or is not merely parseable with this implementation.