# 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