TimeInstant Class

com.bea.p13n.xml.schema
TimeInstant Class

public class TimeInstant

    extends Object
    implements Cloneable, Comparable, Serializable

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.


Hierarchy
Object
  TimeInstant
All Implemented Interfaces

Cloneable, Comparable, Serializable

Constructor Summary

TimeInstant()

Constructs a new TimeInstant instance corresponding to the current time in the local time zone.
 

Method Summary

public Object
clone()
Returns a copy of this TimeInstant.
public int
compareTo(TimeInstant anotherTimeInstant)
Compares this TimeInstant to another TimeInstant object (represented in the same time zone) in their canonical representation.
public int
compareTo(Date date)
Compares this TimeInstant to a Date object in their canonical representation.
public int
compareTo(Time time)
Compares this TimeInstant to a Time object in their canonical representation.
public int
compareTo(Object anotherObject)
Compares this TimeInstant with another object.
public static TimeInstant
createTimeInstant()
Returns a TimeInstant instance for the current time at the local time zone.
public static TimeInstant
createTimeInstant(String timeInstant)
Given a string, returns a TimeInstant instance.
public static TimeInstant
createTimeInstant(Date date)
Given a java.util.Date, returns a TimeInstant instance.
public static TimeInstant
createTimeInstant(Date date)
Given a java.sql.Date, returns a TimeInstant instance.
public static TimeInstant
createTimeInstant(Timestamp timestamp)
Given a java.util.Timestamp, returns a TimeInstant instance.
public static TimeInstant
createTimeInstant(Calendar c)
Given a java.util.Calendar, returns a TimeInstant instance.
public static TimeInstant
createTimeInstant(double time)
Given the value of milliseconds since January 1, 1970, 00:00:00 GMT, returns a TimeInstant.
public static TimeInstant
createTimeInstant(long time)
Given the value of milliseconds since January 1, 1970, 00:00:00 GMT, returns a TimeInstant.
public boolean
equals(Object object)
Indicates whether some other object is "equal to" this one.
public Calendar
getCalendar()
Returns the Calendar representation of this class
public int
getCalendarYear()
Get the Calendar year
public long
getCentury()
Returns the century (CC) field
public int
getDay()
Returns the day (DD) of the month field
public int
getEra()
Returns the era (+/-)
public int
getHour()
Returns the hour (hh) field
public int
getMilliSeconds()
Get the milliseconds portion of the second field.
public int
getMinute()
Returns the minute (mm) field
public int
getMonth()
Returns the month (MM) field.
public double
getSecond()
Returns the second (ss.sss) field with the milliseconds represented as a fraction of the second.
public int
getSecondAsInt()
Returns the integer part of the second field.
public double
getTime()
Returns the value of milliseconds since January 1, 1970, 00:00:00 GMT represented by this time instant object.
public TimeZone
getTimeZone()
Returns the time zone
public long
getYear()
Returns the year (CCYY) field
public int
getZoneHour()
Returns the hour field of time zone
public int
getZoneMinute()
Returns the minute field of time zone
public boolean
isTimeZoneUTC()
Returns true if the time instant is based on UTC
public TimeInstant
offset(TimeDuration timeDuration)

Creates an offset of this TimeInstant with a given TimeDuration.

public void
setCalendarYear(int year)
Sets the year (CCYY) field
public void
setCentury(long century)
Sets the century (CC) field
public void
setDay(int day)
Sets the day (DD) of the month field
public void
setEra(int era)
Sets the era (+/-)
public void
setHour(int hour)
Sets the hour (hh) field
public void
setMilliSecond(int msec)
Sets the milliseconds field as an integer
public void
setMinute(int minute)
Sets the minute (mm) field
public void
setMonth(int month)
Sets the month (MM) field.
public void
setSecond(double second)
Sets the second field in a fractional format
public void
setSecond(int second)
Sets the second field as an integer
public void
setTimeZone(int zoneHour, int zoneMinute)
Sets the time zone
public void
setTimeZone(TimeZone timeZone)
Sets the time zone
public void
setYear(long century, int year)
Sets the year (CCYY) field
public void
setYear(long year)
Sets the year (CCYY) field
public Date
toDate()
Returns java.util.Date representation of timeInstant.
public Date
toDate(Calendar calendarIn)
public TimeInstant
toLocal()

Offsets the current time instant to the local time zone.

public Date
toSQLDate()
Returns java.sql.Date representation of timeInstant.
public String
toString()

Returns a XML schema compliant timeInstant string.

public Timestamp
toTimestamp()
Returns java.sql.Timestamp representation of timeInstant.
public TimeInstant
toUTC()

Offsets the current time instant to UTC.

 
Methods from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
   
Methods from interface java.lang.Comparable
compareTo
 

Constructor Detail

TimeInstant

protected TimeInstant()
Constructs a new TimeInstant instance corresponding to the current time in the local time zone.
 

Method Detail

clone() Method

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.

Overrides
Object.clone()

Returns

copy

compareTo(TimeInstant) Method

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.

compareTo(Date) Method

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

compareTo(Time) Method

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.

compareTo(Object) Method

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.

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.

createTimeInstant() Method

public static TimeInstant createTimeInstant()
Returns a TimeInstant instance for the current time at the local time zone.

Returns

instance of TimeInstant

createTimeInstant(String) Method

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

Exceptions

ParseException

createTimeInstant(Date) Method

public static TimeInstant createTimeInstant(Date date)
Given a java.util.Date, returns a TimeInstant instance.

Parameters

date
date

Returns

instance of TimeInstant

createTimeInstant(Date) Method

public static TimeInstant createTimeInstant(Date date)
Given a java.sql.Date, returns a TimeInstant instance.

Parameters

date
date

Returns

instance of TimeInstant

createTimeInstant(Timestamp) Method

public static TimeInstant createTimeInstant(Timestamp timestamp)
Given a java.util.Timestamp, returns a TimeInstant instance.

Parameters

timestamp
timestamp

Returns

instance of TimeInstant

createTimeInstant(Calendar) Method

public static TimeInstant createTimeInstant(Calendar c)
Given a java.util.Calendar, returns a TimeInstant instance.

Parameters

c
calendar

Returns

instance of TimeInstant

createTimeInstant(double) Method

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(long) Method

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

equals(Object) Method

public boolean equals(Object object)
Indicates whether some other object is "equal to" this one.

Overrides
Object.equals(Object)

Parameters

object
the reference object with which to compare.

Returns

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

getCalendar() Method

public Calendar getCalendar()
Returns the Calendar representation of this class


getCalendarYear() Method

public int getCalendarYear()
Get the Calendar year


getCentury() Method

DEPRECATED

public long getCentury()
Returns the century (CC) field

Returns

the year

getDay() Method

public int getDay()
Returns the day (DD) of the month field

Returns

the day of the month

getEra() Method

public int getEra()
Returns the era (+/-)

Returns

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

getHour() Method

public int getHour()
Returns the hour (hh) field

Returns

the hour

getMilliSeconds() Method

public int getMilliSeconds()
Get the milliseconds portion of the second field. eg, 12.456 returns '456'


getMinute() Method

public int getMinute()
Returns the minute (mm) field

Returns

the minute

getMonth() Method

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() Method

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


getSecondAsInt() Method

public int getSecondAsInt()
Returns the integer part of the second field.


getTime() Method

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() Method

public TimeZone getTimeZone()
Returns the time zone

Returns

timeZone the time zone

getYear() Method

DEPRECATED Use int getCalendarYear()

public long getYear()
Returns the year (CCYY) field

Returns

the year

getZoneHour() Method

public int getZoneHour()
Returns the hour field of time zone

Returns

hour for time zone

getZoneMinute() Method

public int getZoneMinute()
Returns the minute field of time zone

Returns

minute field of time zone

isTimeZoneUTC() Method

public boolean isTimeZoneUTC()
Returns true if the time instant is based on UTC

Returns

true if the time instant is based on UTC

offset(TimeDuration) Method

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(int) Method

public void setCalendarYear(int year)
Sets the year (CCYY) field

Parameters

year
- the year (CCYY)

setCentury(long) Method

DEPRECATED

public void setCentury(long century)
Sets the century (CC) field

Parameters

century
the century

setDay(int) Method

public void setDay(int day)
Sets the day (DD) of the month field

Parameters

day
the day of the month

setEra(int) Method

public void setEra(int era)
Sets the era (+/-)

Parameters

era
the era (+/-)

setHour(int) Method

public void setHour(int hour)
throws IllegalArgumentException
Sets the hour (hh) field

Parameters

hour
the hour

Exceptions

IllegalArgumentException
thrown when the hour argument is illegal

setMilliSecond(int) Method

public void setMilliSecond(int msec)
throws IllegalArgumentException
Sets the milliseconds field as an integer

Exceptions

IllegalArgumentException
thrown when the second argument is illegal

setMinute(int) Method

public void setMinute(int minute)
throws IllegalArgumentException
Sets the minute (mm) field

Parameters

minute
the minute

Exceptions

IllegalArgumentException
thrown when the minute argument is illegal

setMonth(int) Method

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)

Exceptions

IllegalArgumentException
thrown when the month argument is illegal

setSecond(double) Method

public void setSecond(double second)
throws IllegalArgumentException
Sets the second field in a fractional format

Exceptions

IllegalArgumentException
thrown when the second argument is illegal

setSecond(int) Method

public void setSecond(int second)
throws IllegalArgumentException
Sets the second field as an integer

Parameters

second
the second

Exceptions

IllegalArgumentException
thrown when the second argument is illegal

setTimeZone(int, int) Method

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(TimeZone) Method

public void setTimeZone(TimeZone timeZone)
Sets the time zone

Parameters

timeZone
an instance java.util.TimeZone

setYear(long, int) Method

DEPRECATED Use setCalendarYear(int year) , eg, setCalendarYear(2004)

public void setYear(long century, 
                    int year)
throws IllegalArgumentException
Sets the year (CCYY) field

Parameters

century
the century (CC)
year
the year (YY)

Exceptions

IllegalArgumentException
thrown when the century and year arguments are illegal

setYear(long) Method

DEPRECATED Use setCalendarYear(int year)

public void setYear(long year)
Sets the year (CCYY) field

Parameters

year
- the year (CCYY)

toDate() Method

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

public Date toDate(Calendar calendarIn)

toLocal() Method

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() Method

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() Method

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.

Overrides
Object.toString()

Returns

string value

toTimestamp() Method

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() Method

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