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

## 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.sss hh: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.sss hh: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.sss hh: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

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

Copyright © 2004 BEA Systems, Inc. All Rights Reserved