TimeDuration Class

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:

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