com.bea.p13n.xml.schema
Class TimeInstant

java.lang.Object
  com.bea.p13n.xml.schema.TimeInstant

All Implemented Interfaces:

Cloneable, Comparable, Serializable

public class TimeInstant

extends Object

implements Serializable, Cloneable, 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 corresponding to the current time in the local time zone.

Method Summary

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(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(Calendar c) Given a java.util.Calendar, returns a TimeInstant instance.
static TimeInstant	createTimeInstant(Date date) Given a java.util.Date, returns a TimeInstant instance.
static TimeInstant	createTimeInstant(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(long time) Given the value of milliseconds since January 1, 1970, 00:00:00 GMT, returns a TimeInstant.
static TimeInstant	createTimeInstant(String timeInstant) Given a string, returns a TimeInstant instance.
static TimeInstant	createTimeInstant(Timestamp timestamp) Given a java.util.Timestamp, returns a TimeInstant instance.
boolean	equals(Object object) Indicates whether some other object is "equal to" this one.
Calendar	getCalendar() Returns the Calendar representation of this class
int	getCalendarYear() Get the Calendar year
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	getMilliSeconds() Get the milliseconds portion of the second field.
int	getMinute() Returns the minute (mm) field
int	getMonth() Returns the month (MM) field.
double	getSecond() Returns the second (ss.sss) field with the milliseconds represented as a fraction of the second.
int	getSecondAsInt() Returns the integer part of the second field.
double	getTime() Returns the value of milliseconds since January 1, 1970, 00:00:00 GMT represented by this time instant object.
TimeZone	getTimeZone() Returns the time zone
long	getYear() Deprecated. Use int getCalendarYear()
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	setCalendarYear(int year) Sets the year (CCYY) field
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	setMilliSecond(int msec) Sets the milliseconds field as an integer
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 field in a fractional format
void	setSecond(int second) Sets the second field as an integer
void	setTimeZone(int zoneHour, int zoneMinute) Sets the time zone
void	setTimeZone(TimeZone timeZone) Sets the time zone
void	setYear(long year) Deprecated. Use setCalendarYear(int year)
void	setYear(long century, int year) Deprecated. Use setCalendarYear(int year) , eg, setCalendarYear(2004)
Date	toDate() Returns java.util.Date representation of timeInstant.
Date	toDate(Calendar calendarIn)
TimeInstant	toLocal() Offsets the current time instant to the local time zone.
Date	toSQLDate() Returns java.sql.Date representation of timeInstant.
String	toString() Returns a XML schema compliant timeInstant string.
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 corresponding to the current time in the local time zone.

Method Detail

clone

public Object clone()

Returns a copy of this TimeInstant. Actually clones the original Calendar object for the new TimeInstant so the original won't be modified.

Returns:

copy

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. Note this is NOT a java.util.Date, but is a com.bea.p13n.xml.schema.Date

Throws:

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

compareTo

public int compareTo(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 Comparable

Parameters:

anotherObject - 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:

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

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:

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

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:

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

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(Calendar c)

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

Returns:

instance of TimeInstant

createTimeInstant

public static TimeInstant createTimeInstant(Date date)

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

Parameters:

date - date

Returns:

instance of TimeInstant

createTimeInstant

public static TimeInstant createTimeInstant(Date date)

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

Parameters:

date - date

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

createTimeInstant

public static TimeInstant createTimeInstant(long 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

createTimeInstant

public static TimeInstant createTimeInstant(String timeInstant)
                                     throws ParseException

Given a string, returns a TimeInstant instance.

Parameters:

timeInstant - representation of XML schema timeInstant

Returns:

instance of TimeInstant

Throws:

ParseException - thrown due to illegal string argument

createTimeInstant

public static TimeInstant createTimeInstant(Timestamp timestamp)

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

Parameters:

timestamp - timestamp

Returns:

instance of TimeInstant

equals

public boolean equals(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.

getCalendar

public Calendar getCalendar()

Returns the Calendar representation of this class

getCalendarYear

public int getCalendarYear()

Get the Calendar year

getCentury

public long getCentury()

Returns the century (CC) field

Returns:

the year

getDay

public int getDay()

Returns the day (DD) of the month field

Returns:

the day of the month

getEra

public int getEra()

Returns the era (+/-)

Returns:

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

getHour

public int getHour()

Returns the hour (hh) field

Returns:

the hour

getMilliSeconds

public int getMilliSeconds()

Get the milliseconds portion of the second field. eg, 12.456 returns '456'

getMinute

public int getMinute()

Returns the minute (mm) field

Returns:

the minute

getMonth

public int getMonth()

Returns the month (MM) field. The month is assumed to be indexed at 1 (eg, January=1, February=2)

Returns:

the month

getSecond

public double getSecond()

Returns the second (ss.sss) field with the milliseconds represented as a fraction of the second.

getSecondAsInt

public int getSecondAsInt()

Returns the integer part of the second field.

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

getTimeZone

public TimeZone getTimeZone()

Returns the time zone

Returns:

timeZone the time zone

getYear

public long getYear()

Deprecated. Use int getCalendarYear()

Returns the year (CCYY) field

Returns:

the year

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

isTimeZoneUTC

public boolean isTimeZoneUTC()

Returns true if the time instant is based on UTC

Returns:

true if the time instant is based on UTC

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

setCalendarYear

public void setCalendarYear(int year)

Sets the year (CCYY) field

Parameters:

year - - the year (CCYY)

setCentury

public void setCentury(long century)

Sets the century (CC) field

Parameters:

century - the century

Throws:

IllegalArgumentException - thrown when the century and year arguments are illegal

setDay

public void setDay(int day)

Sets the day (DD) of the month field

Parameters:

day - the day of the month

Throws:

IllegalArgumentException - thrown when the date argument is illegal

setEra

public void setEra(int era)

Sets the era (+/-)

Parameters:

era - the era (+/-)

setHour

public void setHour(int hour)
             throws IllegalArgumentException

Sets the hour (hh) field

Parameters:

hour - the hour

Throws:

IllegalArgumentException - thrown when the hour argument is illegal

setMilliSecond

public void setMilliSecond(int msec)
                    throws IllegalArgumentException

Sets the milliseconds field as an integer

Throws:

IllegalArgumentException - thrown when the second argument is illegal

setMinute

public void setMinute(int minute)
               throws IllegalArgumentException

Sets the minute (mm) field

Parameters:

minute - the minute

Throws:

IllegalArgumentException - thrown when the minute argument is illegal

setMonth

public void setMonth(int month)
              throws IllegalArgumentException

Sets the month (MM) field. The month is assumed to be indexed at 1 (eg, January=1, February=2) for backward-compatability with the original code.

Parameters:

month - the month (MM)

Throws:

IllegalArgumentException - thrown when the month argument is illegal

setSecond

public void setSecond(double second)
               throws IllegalArgumentException

Sets the second field in a fractional format

Throws:

IllegalArgumentException - thrown when the second argument is illegal

setSecond

public void setSecond(int second)
               throws IllegalArgumentException

Sets the second field as an integer

Parameters:

second - the second

Throws:

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

setTimeZone

public void setTimeZone(TimeZone timeZone)

Sets the time zone

Parameters:

timeZone - an instance java.util.TimeZone

setYear

public void setYear(long year)

Deprecated. Use setCalendarYear(int year)

Sets the year (CCYY) field

Parameters:

year - - the year (CCYY)

setYear

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

Deprecated. Use setCalendarYear(int year) , eg, setCalendarYear(2004)

Sets the year (CCYY) field

Parameters:

century - the century (CC)

year - the year (YY)

Throws:

IllegalArgumentException - thrown when the century and year arguments are illegal

toDate

public 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

toDate

public Date toDate(Calendar calendarIn)

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.

toSQLDate

public 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

toString

public 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

toTimestamp

public 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

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