# com.bea.p13n.xml.schema
TimeDuration Class

public class TimeDuration
extends `Object`
implements `Cloneable`, `Comparable`, `Serializable`

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.

Hierarchy
  `Object`
  `TimeDuration`

All Implemented Interfaces
  `Cloneable`, `Comparable`, `Serializable`

## Constructor Summary

TimeDuration() Creates an instance of TimeDuration

## Method Summary

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

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

Methods from interface `java.lang.`Comparable``
`compareTo`

## Constructor Detail

### TimeDuration

    protected TimeDuration()

  Creates an instance of TimeDuration

## Method Detail

### clone() Method

    public Object clone()

Returns a copy of this TimeDuration.

Overrides
  `Object.clone()`

#### Returns

copy

### compareTo(TimeDuration) Method

    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.

#### Parameters

anotherTimeDuration
  another TimeDuration object to be compared.

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

### compareTo(Object) Method

    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.

#### Parameters

anotherObject
  the object to be compared

#### 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(long, long, long, long, long, double, boolean) Method

    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

years
  years field

months
  months field

days
  days field

hours
  hours field

minutes
  minutes field

seconds
  seconds field

isPositive
  sign field

#### Returns

instance of TimeDuration

### createTimeDuration(String) Method

    public static TimeDuration createTimeDuration(String timeDuration)
         throws ParseException

Given a string, returns an instance of TimeDuration.

#### Parameters

timeDuration
  representation of XML schema timeDuration

#### Returns

instance of Timeduration

#### Exceptions

``ParseException``

### getBaseTimeInstant() Method

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

    public long getDays()

Returns the days field

### getHours() Method

    public long getHours()

Retuns the hours field

#### Returns

hours field

### getMinutes() Method

    public long getMinutes()

Returns the minutes field

#### Returns

minutes field

### getMonths() Method

    public long getMonths()

Returns the months field

#### Returns

months field

### getPositive() Method

    public boolean getPositive()

Returns true if this time duration is positive.

#### Returns

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

### getSeconds() Method

    public double getSeconds()

Returns the seconds field

#### Returns

seconds field

### getYears() Method

    public long getYears()

Returns the years field

#### Returns

years field

### setBaseTimeInstant(TimeInstant) Method

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

    public void setDays(long days)

Sets the days field

#### Parameters

days
  days field

### setHours(long) Method

    public void setHours(long hours)

Sets the hours field

#### Parameters

hours
  hours field

### setMinutes(long) Method

    public void setMinutes(long minutes)

Sets the minutes field

#### Parameters

minutes
  minutes field

### setMonths(long) Method

    public void setMonths(long months)

Sets the months field

#### Parameters

months
  months field

### setPositive(boolean) Method

    public void setPositive(boolean positive)

Sets the time duration to be positive.

#### Parameters

positive
  true for positive time duration. false otherwise.

### setSeconds(double) Method

    public void setSeconds(double seconds)

Sets the seconds field

#### Parameters

seconds
  seconds field

### setYears(long) Method

    public void setYears(long years)

Sets the years field

#### Parameters

years
  years field

### toString() Method

    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.

Overrides
  `Object.toString()`

#### Returns

string value