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 TimeDuration

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

All Implemented Interfaces:
  Cloneable, Comparable, Serializable

public class TimeDuration
extends Object
implements Serializable, Cloneable, Comparable

This class provides the Java binding for the XML schema type timeDuration as specified in Section 3.2.6 of XML Schema Part 2: Datatypes.

timeDuration represents a duration of time. The value space of timeDuration is a six-dimensional space where the coordinates designate the Gregorial year, month, day, hour, minute, and second components defined in Sec 5.5.3.2 of ISO8601.

Example: `P2001Y1M18DT9H0M0S`.

The lexical representation for timeDuration is the ISO 8601 extended format PnYnMnDTnHnMnS, where nY represents the number of years, nM the number of months, nD the number of days, 'T' is the date/time separator, nH the number of hours, nM the number of minutes, nS is the number of seconds. The number of seconds can include decimal digits to arbitrary precision.

The values of year, month, day, hour and minute can be arbitrary integers. The value of second can be any arbitrary decimal. See the Precision Rules below.

Instances of `TimeDuration` may be constructed from timeDuration strings defined as per the XML Schema Specification. In addition, instances of `TimeDuration` may be compared for ordering.

Note on Ordering: As per the current schema specification, the ordering relation on timeDuration does not hold for certain values of timeDuration. This is due to the ambiguity associated with the number of days in a given month. This number may vary from 28 to 31 depending on how time duration is applied. For instance, the elapsed time in days/seconds of a given time duration (say P2M1D, i.e., 2 months and 1 day) from January 1, 1996 and January 1, 2001 are not equal. In order to resolve this indeterminism, this class requires a base `TimeInstant` to be specified to order instances of `TimeDuration`. In case a base time instant is not explicitly specified, this class uses the current time as the base.

Precision Rules:

1. The values of years, months, days, hours, and minutes are constrained to be in the range of -9223372036854775808 to 9223372036854775808.
2. 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.
3. Rules 1 and 2 are supported by `long` and `double` respectively in the Java programming language.
4. 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 values specified in Rule 1 above. 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.
5. Since the various date types (viz., `java.util.Date`, `java.sql.Date` and `java.sql.Timestamp`) can not represent values of years, months, days, hours, minutes, and seconds beyond the range of -2147483648 to 2147483647, this class chooses a higher precision for these values. Therefore, any conversion of instances of `TimeDuration` to instances of `java.util.Date`, `java.sql.Date` and `java.sql.Timestamp` may be subjected rounding and loss of information.
6. This class can be used by a "minimally conforming" XML processor as long as cases mentioned in Rule 5 are avoided.

See Also:
  Serialized Form

Constructor Summary
`protected` | `TimeDuration()` Creates an instance of TimeDuration

Method Summary
`Object` | `clone()` Returns a copy of this TimeDuration.
`int` | `compareTo(Object anotherObject)` Compares this TimeDuration with another object. if the other object is a TimeDuration, this method behaves like compareTo(TimeDuration).
`int` | `compareTo(TimeDuration anotherTimeDuration)` Compares this TimeDuration to another TimeDuration object.
`static TimeDuration` | `createTimeDuration(long years, long months, long days, long hours, long minutes, double seconds, boolean isPositive)` Given the individual fields, returns an instance of TimeDuration.
`static TimeDuration` | `createTimeDuration(String timeDuration)` Given a string, returns an instance of TimeDuration.
`TimeInstant` | `getBaseTimeInstant()` Returns the base TimeInstant for this TimeDuration.
`long` | `getDays()` Returns the days field
`long` | `getHours()` Retuns the hours field
`long` | `getMinutes()` Returns the minutes field
`long` | `getMonths()` Returns the months field
`boolean` | `getPositive()` Returns true if this time duration is positive.
`double` | `getSeconds()` Returns the seconds field
`long` | `getYears()` Returns the years field
`void` | `setBaseTimeInstant(TimeInstant base)` Sets the base TimeInstat for this TimeDuration.
`void` | `setDays(long days)` Sets the days field
`void` | `setHours(long hours)` Sets the hours field
`void` | `setMinutes(long minutes)` Sets the minutes field
`void` | `setMonths(long months)` Sets the months field
`void` | `setPositive(boolean positive)` Sets the time duration to be positive.
`void` | `setSeconds(double seconds)` Sets the seconds field
`void` | `setYears(long years)` Sets the years field
`String` | `toString()` Returns a XML schema timeDuration compliant string.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### TimeDuration

    protected TimeDuration()

  Creates an instance of TimeDuration

Method Detail

### clone

    public Object clone()

  Returns a copy of this TimeDuration.

  Returns:
    copy

### compareTo

    public int compareTo(Object anotherObject)

  Compares this TimeDuration with another object. if the other object is a TimeDuration, this method behaves like compareTo(TimeDuration). Otherwise, it throws a ClassCastException.

  Specified by:
    `compareTo` in interface `Comparable`
  Returns:
    the value 0 if the argument TimeDuration is equal to this TimeDuratuon; a value less than 0 if this TimeDuration is less than the TimeDuration argument; and a value greater than 0 if this TimeDuration is less than the TimeDuration argument.
  Throws:
    `IllegalStateException` - thrown when the base TimeInstant is not specified for this TimeDuration.
    `IllegalStateException` - thrown when the base TimeInstant * is not specified for this TimeDuration.

### compareTo

    public int compareTo(TimeDuration anotherTimeDuration)

  Compares this TimeDuration to another TimeDuration object. If a base TimeInstant has not been specified for this TimeDuration, this method uses the current time as base.

  Returns:
    the value 0 if the argument TimeDuration is equal to this TimeDuratuon; a value less than 0 if this TimeDuration is less than the TimeDuration argument; and a value greater than 0 if this TimeDuration is less than the TimeDuration argument.

### createTimeDuration

    public static TimeDuration createTimeDuration(long years,
                                                  long months,
                                                  long days,
                                                  long hours,
                                                  long minutes,
                                                  double seconds,
                                                  boolean isPositive)

  Given the individual fields, returns an instance of TimeDuration.

  Parameters:
    `months` - months field
    `days` - days field
    `hours` - hours field
    `minutes` - minutes field
    `seconds` - seconds field
    `isPositive` - sign field
  Returns:
    instance of TimeDuration

### createTimeDuration

    public static TimeDuration createTimeDuration(String timeDuration)
                                           throws ParseException

  Given a string, returns an instance of TimeDuration.

  Returns:
    instance of Timeduration
  Throws:
    `ParseException` - thrown due to illegal string argument

### getBaseTimeInstant

    public TimeInstant getBaseTimeInstant()

  Returns the base TimeInstant for this TimeDuration. If a base TimeInstant has not been set for this TimeDuration, this class returns a TimeInstant based on the current (and local) time.

  Returns:
    base TimeInstant

### getDays

    public long getDays()

  Returns the days field

### getHours

    public long getHours()

  Retuns the hours field

  Returns:
    hours field

### getMinutes

    public long getMinutes()

  Returns the minutes field

  Returns:
    minutes field

### getMonths

    public long getMonths()

  Returns the months field

  Returns:
    months field

### getPositive

    public boolean getPositive()

  Returns true if this time duration is positive.

  Returns:
    true if this time duration is positive. Returns false otherwise.

### getSeconds

    public double getSeconds()

  Returns the seconds field

  Returns:
    seconds field

### getYears

    public long getYears()

  Returns the years field

  Returns:
    years field

### setBaseTimeInstant

    public void setBaseTimeInstant(TimeInstant base)

  Sets the base TimeInstat for this TimeDuration. The base TimeInstant is required for ordering purposes. This may not be set if ordering is not required.

  Parameters:
    `base` - base TimeInstant for ordering purposes

### setDays

    public void setDays(long days)

  Sets the days field

  Parameters:
    `days` - days field

### setHours

    public void setHours(long hours)

  Sets the hours field

  Parameters:
    `hours` - hours field

### setMinutes

    public void setMinutes(long minutes)

  Sets the minutes field

  Parameters:
    `minutes` - minutes field

### setMonths

    public void setMonths(long months)

  Sets the months field

  Parameters:
    `months` - months field

### setPositive

    public void setPositive(boolean positive)

  Sets the time duration to be positive.

  Parameters:
    `positive` - true for positive time duration. false otherwise.

### setSeconds

    public void setSeconds(double seconds)

  Sets the seconds field

  Parameters:
    `seconds` - seconds field

### setYears

    public void setYears(long years)

  Sets the years field

  Parameters:
    `years` - years field

### toString

    public String toString()

  Returns a XML schema timeDuration compliant string.

  This method uses the following rules:

  - A '-' or '+' symbol always precedes the duration depending on whether the duration is positive or negative.
  - If the numer of years, months, days, hours, minutes, or seconds in a given duration is zero, the number and its corresponding delimiter will be omitted from the return value.
  - The return string is guaranteed to preserve the precision subjected to the Precision Rules.

  The above rules imply that this method does not guarantee TimeDuration.createTimeDuration(_string).toString().equals(_string) to be true.

  Returns:
    string value

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