Overview | Package | Class | Tree | Deprecated | Index | Help
| © 2002 BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Tree | Deprecated | Index | Help
| © 2002 BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002 BEA Systems, Inc. All Rights Reserved