Package com.globalmentor.iso.datetime

Class ISOTemporalComponents

java.lang.Object

com.globalmentor.iso.datetime.ISOTemporalComponents

public class ISOTemporalComponents
extends java.lang.Object

A lightweight structure for transferring components of ISO 8601 types.

Author:

Garret Wilson

Constructor Summary

Constructors

Constructor	Description
ISOTemporalComponents(int year, int month, int day, int hours, int minutes, int seconds, int microseconds, int utcOffsetHours, int utcOffsetMinutes)	Full constructor.
ISOTemporalComponents(long time)	Millisecond time constructor in terms of UTC.
ISOTemporalComponents(long time, java.util.TimeZone timeZone)	Millisecond time and time zone constructor.
ISOTemporalComponents(java.util.Date date)	Date constructor in terms of UTC.
ISOTemporalComponents(java.util.Date date, java.util.TimeZone timeZone)	Date and time zone constructor.

Method Summary

Modifier and Type	Method	Description
ISOTime	asTime()	Returns the temporal components as time information.
ISOUTCOffset	asUTCOffset()	Returns the temporal components as UTC offset information.
static java.util.GregorianCalendar	createCalendar(int year, int month, int day, int hours, int minutes, int seconds, int microseconds, ISOUTCOffset utcOffset, java.util.Locale locale)	Creates a calendar representing the given temporal component information.
static java.util.GregorianCalendar	createCalendar(int year, int month, int day, ISOTime time, java.util.Locale locale)	Creates a calendar representing the given temporal component information in the given locale.
int	getDay()
int	getHours()
int	getMicroseconds()
int	getMinutes()
int	getMonth()
int	getSeconds()
long	getTime()
int	getUTCOffsetHours()
int	getUTCOffsetMinutes()
int	getYear()
boolean	hasDateComponents()
boolean	hasTimeComponents()
static ISOTemporalComponents	parseDateTimeUTCOffset(java.io.Reader reader, boolean hasDate, boolean hasTime)	Parses a date, time, date time, and/or UTC offset lexical form from a reader.
ISOTime	toTime()	Returns the temporal components as an ISO time.

Methods inherited from class java.lang.Object

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

Constructor Detail

ISOTemporalComponents

public ISOTemporalComponents(int year,
                             int month,
                             int day,
                             int hours,
                             int minutes,
                             int seconds,
                             int microseconds,
                             int utcOffsetHours,
                             int utcOffsetMinutes)

Full constructor.

Parameters:

year - The year (0-9999), or -1 if there is no year specified.

month - The month (1-12), or -1 if there is no month specified.

day - The day (1-31), or -1 if there is no day specified.

hours - The hours (0-23), or -1 if there is no hours specified.

minutes - The minutes (0-59), or -1 if there is no minutes specified.

seconds - The seconds (0-60, allowing leap-seconds; see ISO 8601:2004(E) 4.2.1), or -1 if there is no seconds specified.

microseconds - The microseconds (0-999999), or -1 if there is no microseconds specified.

utcOffsetHours - The UTC offset hours.

utcOffsetMinutes - The UTC offset minutes, or -1 if there is no UTC offset hours or minutes specified.

ISOTemporalComponents

public ISOTemporalComponents(java.util.Date date)

Date constructor in terms of UTC.

Parameters:

date - The date representing the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

Throws:

java.lang.NullPointerException - if the given date is null.

ISOTemporalComponents

public ISOTemporalComponents(java.util.Date date,
                             java.util.TimeZone timeZone)

Date and time zone constructor.

Parameters:

date - The date representing the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

timeZone - The time zone in which the time should be interpreted.

Throws:

java.lang.NullPointerException - if the given date and/or time zone is null.

java.lang.IllegalArgumentException - if a time zone was provided with an unsupported offset for the given time.

ISOTemporalComponents

public ISOTemporalComponents(long time)

Millisecond time constructor in terms of UTC.

Parameters:

time - The difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

ISOTemporalComponents

public ISOTemporalComponents(long time,
                             java.util.TimeZone timeZone)

Millisecond time and time zone constructor. This method cannot handle offsets that do not fall on whole minutes.

Parameters:

time - The difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

timeZone - The time zone in which the time should be interpreted.

Throws:

java.lang.NullPointerException - if the given time zone is null.

java.lang.IllegalArgumentException - if a time zone was provided with an unsupported offset for the given time.

Method Detail

getYear

public final int getYear()

Returns:

The year (0-9999), or -1 if there is no year specified.

getMonth

public final int getMonth()

Returns:

The month (1-12), or -1 if there is no month specified.

getDay

public final int getDay()

Returns:

The day (1-31), or -1 if there is no day specified.

getHours

public final int getHours()

Returns:

The hours (0-23), or -1 if there is no hours specified.

getMinutes

public final int getMinutes()

Returns:

The minutes (0-59), or -1 if there is no minutes specified.

getSeconds

public final int getSeconds()

Returns:

The seconds (0-60, allowing leap-seconds; see ISO 8601:2004(E) 4.2.1), or -1 if there is no seconds specified.

getMicroseconds

public final int getMicroseconds()

Returns:

The microseconds (0-999999), or -1 if there is no microseconds specified.

getUTCOffsetHours

public final int getUTCOffsetHours()

Returns:

The UTC offset hours.

getUTCOffsetMinutes

public final int getUTCOffsetMinutes()

Returns:

The UTC offset minutes, or -1 if there is no UTC offset hours or minutes specified.

getTime

public long getTime()

Returns:

The difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

hasDateComponents

public boolean hasDateComponents()

Returns:

true if there are sufficient components to create an ISODate.

hasTimeComponents

public boolean hasTimeComponents()

Returns:

true if there are sufficient components to create an ISOTime.

asTime

public ISOTime asTime()

Returns the temporal components as time information.

Returns:

A time object representing the time components, or null if time components are not represented.

toTime

public ISOTime toTime()

Returns the temporal components as an ISO time.

Returns:

A time object representing the time and optional UTC offset.

asUTCOffset

public ISOUTCOffset asUTCOffset()

Returns the temporal components as UTC offset information.

Returns:

A UTC offset object representing the UTC offset components, or null if UTC offset components are not represented.

createCalendar

public static java.util.GregorianCalendar createCalendar(int year,
                                                         int month,
                                                         int day,
                                                         ISOTime time,
                                                         java.util.Locale locale)

Creates a calendar representing the given temporal component information in the given locale.

Parameters:

year - The year, 0-9999.

month - The month, 1-12.

day - The day, 1-31.

time - The time, or null if there should be no time component (set to midnight).

locale - The locale for the calendar.

Returns:

The calendar representing the given temporal component information in the given locale

Throws:

java.lang.NullPointerException - if the given time and/or locale is null.

java.lang.IllegalArgumentException - if one of the given arguments is outside the allowed range.

createCalendar

public static java.util.GregorianCalendar createCalendar(int year,
                                                         int month,
                                                         int day,
                                                         int hours,
                                                         int minutes,
                                                         int seconds,
                                                         int microseconds,
                                                         ISOUTCOffset utcOffset,
                                                         java.util.Locale locale)

Creates a calendar representing the given temporal component information.

Parameters:

year - The year, 0-9999.

month - The month, 1-12.

day - The day, 1-31.

hours - The hours, 0-23.

minutes - The minutes, 0-59.

seconds - The seconds, 0-60 (allowing leap-seconds; see ISO 8601:2004(E) 4.2.1).

microseconds - The microseconds, 0-999999

utcOffset - The UTC offset, or null if no UTC offset is known.

locale - The locale for the calendar.

Returns:

The calendar representing the given temporal component information

Throws:

java.lang.NullPointerException - if the given locale is null.

java.lang.IllegalArgumentException - if one of the given arguments is outside the allowed range.

parseDateTimeUTCOffset

public static ISOTemporalComponents parseDateTimeUTCOffset(java.io.Reader reader,
                                                           boolean hasDate,
                                                           boolean hasTime)
                                                    throws java.io.IOException,
                                                           ParseIOException,
                                                           SyntaxException

Parses a date, time, date time, and/or UTC offset lexical form from a reader. This method restricts the syntax to a IS0 8601 subset. The current position must be that of the beginning date/time character. The new position will be that immediately after the last date/time character. If neither a date nor a time are requested, a UTC offset is required. Otherwise, a UTC offset is allowed unless only a date is requested.

Parameters:

reader - The reader the contents of which to be parsed.

hasDate - Whether this lexical representation has a date component.

hasTime - Whether this lexical representation has a time component.

Returns:

The temporal components parsed from the reader.

Throws:

java.lang.NullPointerException - if the given reader is null.

java.io.IOException - if there is an error reading from the reader.

ParseIOException - if the reader has no more characters before the current date/time is completely parsed.

SyntaxException - if the date/time is not of the correct format.