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