com.bea.p13n.xml.schema
Class TimeInstant

java.lang.Object
  |
  +--com.bea.p13n.xml.schema.TimeInstant

public class TimeInstant

extends java.lang.Object

implements java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

This class provides the Java binding for the XML schema type timeInstant as specified in Section 3.2.24 of XML Schema Part 2: Datatypes.

timeInstant represents a specific instant of a time. The value space of timeInstant is the space of combinations of date and time of day values as defined in ISO 8601.

Time zone specification is not optional.

Example: 2001-01-18T09:00:00.0005Z.

In this representation, one can represent arbitrary precision seconds. Timezone offsets can be represented with the optional zone indicator Z for UTC or one of -hh::mm or +hh:mm to indicate the difference from UTC.

Instances of this type can be constructed from valid instances of timeInstant strings, java.util.Date, java.sql.Date, and java.util.Timestamp.

As the XML Schema specification allows arbitrary precision seconds representation, this class preserves the precision of seconds when instances of this class are created from a timeInstant string. However, such precision may be lost when instances of java.util.Date, java.sql.Date or java.sql.Timestamp are obtained from an instance of TimeInstant.

Precision Rules:

1. The values of years is constrained to be in the range of -9223372036854775808 to 9223372036854775808.
2. The values of months, days, hours, and minutes are constrained by their natural ranges. For instance, the range of months is constrained to be within 1-12, and the range of days is constrained to be with in 1-28 to 1-31 depending on the month.
3. The values of seconds are constrained to be within +/- m*2**e where m is a positive integer less than 2**53 (i.e., 9007199254740992) and e is an integer between -1075 and 970.
4. Rules 1 and 3 are supported by long and double respectively in the Java programming language.
5. The "XML Schema Part 2: Datatypes" document requires the values of years, months, days, hours, and minutes to be integers, and as per this document, a minimally confirming XML processor is required to guarantee a range of -9223372036854775808 to 9223372036854775808. Similarly, the value of seconds can be any arbitrary precision decimal, and a minimally confirming XML processor is required to guarantee a range of values specified in Rule 2 above.
6. Since the various date types (viz., java.util.Date, java.sql.Date and java.sql.Timestamp) can not represent values of years beyond the range of -2147483648 to 2147483647, this class chooses a higher precision for these values. The same applies to seconds. Therefore, any conversion between instances of TimeDuration and instances of java.util.Date, java.sql.Date and java.sql.Timestamp may be subjected rounding and loss of information.
7. This class can be used by a "minimally conforming" XML processor subjected to Rules 2 and 6 above.

Design Note: Although a timeInstant is a derived type (derived from recurringDuration), there is no inheritance association between TimeInstant and TimeDuration. From the point of XML Schema, a recurringDuration is a more general type, and all the derived types (including timeInstant, time, timePeriod, recurringDate, and recurringDay) can be created by restricting the values facets of recurringDuration. For instance, a timeInstant can be created by restricting both the duration and period facets to be P0Y.

However, in this design, the same notion is not applied to the corresponding Java types. This is to prevent extraneous methods appearing on classes for derived types. For instance, by not having a specialization association between TimeInstant and RecurringDuration, this design prevents methods such as getDuration() from the TimeInstant class. The design instead relies on delegation.

See Also:

Serialized Form

Constructor Summary

protected

TimeInstant() Constructs a new TimeInstant instance.

Method Summary

java.lang.Object	clone() Returns a copy of this TimeInstant.
int	compareTo(Date date) Compares this TimeInstant to a Date object in their canonical representation.
int	compareTo(java.lang.Object anotherObject) Compares this TimeInstant with another object.
int	compareTo(Time time) Compares this TimeInstant to a Time object in their canonical representation.
int	compareTo(TimeInstant anotherTimeInstant) Compares this TimeInstant to another TimeInstant object (represented in the same time zone) in their canonical representation.
static TimeInstant	createTimeInstant() Returns a TimeInstant instance for the current time at the local time zone.
static TimeInstant	createTimeInstant(java.util.Calendar calendar) Given a java.util.Calendar, returns a TimeInstant instance.
static TimeInstant	createTimeInstant(java.util.Date date) Given a java.util.Date, returns a TimeInstant instance.
static TimeInstant	createTimeInstant(java.sql.Date date) Given a java.sql.Date, returns a TimeInstant instance.
static TimeInstant	createTimeInstant(double time) Given the value of milliseconds since January 1, 1970, 00:00:00 GMT, returns a TimeInstant.
static TimeInstant	createTimeInstant(java.lang.String timeInstant) Given a string, returns a TimeInstant instance.
static TimeInstant	createTimeInstant(java.sql.Timestamp timestamp) Given a java.util.Timestamp, returns a TimeInstant instance.
boolean	equals(java.lang.Object object) Indicates whether some other object is "equal to" this one.
long	getCentury() Returns the century (CC) field
int	getDay() Returns the day (DD) of the month field
int	getEra() Returns the era (+/-)
int	getHour() Returns the hour (hh) field
int	getMinute() Returns the minute (mm) field
int	getMonth() Returns the month (MM) field
double	getSecond() Returns the second (ss.sss) field
double	getTime() Returns the value of milliseconds since January 1, 1970, 00:00:00 GMT represented by this time instant object.
java.util.TimeZone	getTimeZone() Returns the time zone
long	getYear() Returns the year (CCYY) field
int	getZoneHour() Returns the hour field of time zone
int	getZoneMinute() Returns the minute field of time zone
boolean	isTimeZoneUTC() Returns true if the time instant is based on UTC
TimeInstant	offset(TimeDuration timeDuration) Creates an offset of this TimeInstant with a given TimeDuration.
void	setCentury(long century) Sets the century (CC) field
void	setDay(int day) Sets the day (DD) of the month field
void	setEra(int era) Sets the era (+/-)
void	setHour(int hour) Sets the hour (hh) field
void	setMinute(int minute) Sets the minute (mm) field
void	setMonth(int month) Sets the month (MM) field
void	setSecond(double second) Sets the second (ss.sss) field
void	setTimeZone(int zoneHour, int zoneMinute) Sets the time zone
void	setTimeZone(java.util.TimeZone timeZone) Sets the time zone
void	setYear(long year) Sets the year (CCYY) field
void	setYear(long century, int year) Sets the year (CCYY) field
java.util.Date	toDate() Returns java.util.Date representation of timeInstant.
TimeInstant	toLocal() Offsets the current time instant to the local time zone.
java.sql.Date	toSQLDate() Returns java.sql.Date representation of timeInstant.
java.lang.String	toString() Returns a XML schema compliant timeInstant string.
java.sql.Timestamp	toTimestamp() Returns java.sql.Timestamp representation of timeInstant.
TimeInstant	toUTC() Offsets the current time instant to UTC.

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TimeInstant

protected TimeInstant()

Constructs a new TimeInstant instance.

Method Detail

createTimeInstant

public static TimeInstant createTimeInstant()

Returns a TimeInstant instance for the current time at the local time zone.

Returns:

instance of TimeInstant

createTimeInstant

public static TimeInstant createTimeInstant(java.lang.String timeInstant)
                                     throws java.text.ParseException

Given a string, returns a TimeInstant instance.

Parameters:

String - representation of XML schema timeInstant

Returns:

instance of TimeInstant

Throws:

java.text.ParseException - thrown due to illegal string argument

createTimeInstant

public static TimeInstant createTimeInstant(java.util.Date date)

Given a java.util.Date, returns a TimeInstant instance.

Parameters:

date - date

Returns:

instance of TimeInstant

createTimeInstant

public static TimeInstant createTimeInstant(java.sql.Date date)

Given a java.sql.Date, returns a TimeInstant instance.

Parameters:

date - date

Returns:

instance of TimeInstant

createTimeInstant

public static TimeInstant createTimeInstant(java.sql.Timestamp timestamp)

Given a java.util.Timestamp, returns a TimeInstant instance.

Parameters:

timestamp - timestamp

Returns:

instance of TimeInstant

createTimeInstant

public static TimeInstant createTimeInstant(java.util.Calendar calendar)

Given a java.util.Calendar, returns a TimeInstant instance.

Parameters:

calendar - calendar

Returns:

instance of TimeInstant

createTimeInstant

public static TimeInstant createTimeInstant(double time)

Given the value of milliseconds since January 1, 1970, 00:00:00 GMT, returns a TimeInstant.

Parameters:

time - value of milliseconds since January 1, 1970, 00:00:00 GMT

Returns:

instance of TimeInstant

clone

public java.lang.Object clone()

Returns a copy of this TimeInstant.

Returns:

copy

Overrides:

clone in class java.lang.Object

compareTo

public int compareTo(TimeInstant anotherTimeInstant)

Compares this TimeInstant to another TimeInstant object (represented in the same time zone) in their canonical representation. Two time instances are considered to be equal if individual fields of the representation (<+/->CCYY:MM:DDThh:mm:ss.ssshh:ss>) are equal.

Parameters:

anotherTimeInstant - another TimeInstant object to be compared.

Returns:

the value 0 if the argument TimeInstant is equal to this TimeInstant; a value less than 0 if this TimeInstant is before the TimeInstant argument; and a value greater than 0 if this TimeInstant is after the TimeInstant argument.

Throws:

java.lang.IllegalArgumentException - thrown when the argument is represented in a different time zone from the current time instant.

compareTo

public int compareTo(Date date)

Compares this TimeInstant to a Date object in their canonical representation. A Date and a TimeInstant are considered to be equal if individual fields of the representation (<+/->CCYY:MM:DDThh:mm:ss.ssshh:ss>) are equal.

Parameters:

date - the Date object to be compared.

Returns:

the value 0 if the argument Date is equal to this TimeInstant; a value less than 0 if this TimeInstant is before the Date argument; and a value greater than 0 if this TimeInstant is after the Date argument.

Throws:

java.lang.IllegalArgumentException - thrown when the argument is represented in a different time zone from the current time instant.

compareTo

public int compareTo(Time time)

Compares this TimeInstant to a Time object in their canonical representation. A Time and a TimeInstant are considered to be equal if individual fields of the representation (hh:mm:ss.ssshh:ss>) are equal.

Parameters:

time - the Time object to be compared.

Returns:

the value 0 if the argument Time is equal to this TimeInstant; a value less than 0 if this Time is before the Time argument; and a value greater than 0 if this TimeInstant is after the Time argument.

Throws:

java.lang.IllegalArgumentException - thrown when the argument is represented in a different time zone from the current time instant.

compareTo

public int compareTo(java.lang.Object anotherObject)

Compares this TimeInstant with another object. If the other object is a TimeInstant, this method behaves like compareTo(TimeInstant). If the other object is a Time, this method behaves like compareTo(Time). If the other object is a Date, this method behaves like compareTo(Date). Otherwise, it throws a ClassCastException.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

object - the object to be compared

Returns:

the value 0 if the argument TimeInstant is equal to this TimeInstant; a value less than 0 if this TimeInstant is before the TimeInstant argument; and a value greater than 0 if this TimeInstant is after the TimeInstant argument.

Throws:

java.lang.ClassCastException - thrown if the argument is not an instance of TimeInstant.

offset

public TimeInstant offset(TimeDuration timeDuration)

Creates an offset of this TimeInstant with a given TimeDuration.

Note: This implementation does not guarantee the precision beyond those values representable by java.util.Calendar.

Parameters:

timeDuration - offset time duration

Returns:

offset time instant

getEra

public int getEra()

Returns the era (+/-)

Returns:

the era (one of java.util.GregorianCalendar.AD or java.util.GregorianCalendar.BC)

setEra

public void setEra(int era)

Sets the era (+/-)

Parameters:

era - the era (+/-)

getCentury

public long getCentury()

Returns the century (CC) field

Returns:

the year

setCentury

public void setCentury(long century)

Sets the century (CC) field

Parameters:

century - the century

Throws:

java.lang.IllegalArgumentException - thrown when the century and year arguments are illegal

getYear

public long getYear()

Returns the year (CCYY) field

Returns:

the year

setYear

public void setYear(long century,
                    int year)
             throws java.lang.IllegalArgumentException

Sets the year (CCYY) field

Parameters:

century - the century (CC)

year - the year (YY)

Throws:

java.lang.IllegalArgumentException - thrown when the century and year arguments are illegal

setYear

public void setYear(long year)

Sets the year (CCYY) field

Parameters:

the - year (CCYY)

getMonth

public int getMonth()

Returns the month (MM) field

Returns:

the month

setMonth

public void setMonth(int month)
              throws java.lang.IllegalArgumentException

Sets the month (MM) field

Parameters:

month - the month (MM)

Throws:

java.lang.IllegalArgumentException - thrown when the month argument is illegal

getDay

public int getDay()

Returns the day (DD) of the month field

Returns:

the day of the month

setDay

public void setDay(int day)

Sets the day (DD) of the month field

Parameters:

date - the day of the month

Throws:

java.lang.IllegalArgumentException - thrown when the date argument is illegal

getHour

public int getHour()

Returns the hour (hh) field

Returns:

the hour

setHour

public void setHour(int hour)
             throws java.lang.IllegalArgumentException

Sets the hour (hh) field

Parameters:

hour - the hour

Throws:

java.lang.IllegalArgumentException - thrown when the hour argument is illegal

getMinute

public int getMinute()

Returns the minute (mm) field

Returns:

the minute

setMinute

public void setMinute(int minute)
               throws java.lang.IllegalArgumentException

Sets the minute (mm) field

Parameters:

minute - the minute

Throws:

java.lang.IllegalArgumentException - thrown when the minute argument is illegal

getSecond

public double getSecond()

Returns the second (ss.sss) field

Returns:

the integer part of second

setSecond

public void setSecond(double second)
               throws java.lang.IllegalArgumentException

Sets the second (ss.sss) field

Parameters:

second - the second

Throws:

java.lang.IllegalArgumentException - thrown when the second argument is illegal

setTimeZone

public void setTimeZone(int zoneHour,
                        int zoneMinute)

Sets the time zone

Parameters:

zoneHour - the hour field of timeZone. Can be negative to indicate negative offset.

zoneMinute - the minute field of timeZone

getZoneHour

public int getZoneHour()

Returns the hour field of time zone

Returns:

hour for time zone

getZoneMinute

public int getZoneMinute()

Returns the minute field of time zone

Returns:

minute field of time zone

setTimeZone

public void setTimeZone(java.util.TimeZone timeZone)

Sets the time zone

Parameters:

timeZone - an instance java.util.TimeZone

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the time zone

Returns:

timeZone the time zone

isTimeZoneUTC

public boolean isTimeZoneUTC()

Returns true if the time instant is based on UTC

Returns:

true if the time instant is based on UTC

toString

public java.lang.String toString()

Returns a XML schema compliant timeInstant string.

This method uses the following rules:

• A '-' or '+' symbol always precedes the time instant depending on whether the era is BC or AD.
• The return string is guaranteed to preserve the precision subjected to the Precision Rules.

The above rules imply that this method does not guarantee TimeInstant.createTimeInstant(_string).toString().equals(_string) to be true.

Returns:

string value

Overrides:

toString in class java.lang.Object

toDate

public java.util.Date toDate()

Returns java.util.Date representation of timeInstant. Note that following:

• The returned date will be in local time zone.
• The returned date will maintain the precesion upto milliseconds only.

Returns:

java.util.Date

toSQLDate

public java.sql.Date toSQLDate()

Returns java.sql.Date representation of timeInstant. Note that following:

• The returned date will be in local time zone.
• The returned date will maintain the precesion upto milliseconds only.

Returns:

java.sql.Date

toTimestamp

public java.sql.Timestamp toTimestamp()

Returns java.sql.Timestamp representation of timeInstant. Note that following:

• The returned timestamp will be in local time zone.
• The returned date will maintain the precesion upto nanoseconds only.

Returns:

java.sql.Timestamp

getTime

public double getTime()

Returns the value of milliseconds since January 1, 1970, 00:00:00 GMT represented by this time instant object.

Returns:

value of milliseconds

toUTC

public TimeInstant toUTC()

Offsets the current time instant to UTC.

Note: This implementation does not guarantee the precision beyond those values representable by java.util.Calendar.

Returns:

instance of TimeInstant offset to UTC

toLocal

public TimeInstant toLocal()

Offsets the current time instant to the local time zone.

Note: This implementation does not guarantee the precision beyond those values representable by java.util.Calendar.

Returns:

instance of TimeInstant offset to the local time zone.

equals

public boolean equals(java.lang.Object object)

Indicates whether some other object is "equal to" this one.

Parameters:

object - the reference object with which to compare.

Returns:

true if this object is the same as the object argument; false otherwise.

Overrides:

equals in class java.lang.Object