javax.xml.datatype
Class Duration

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by javax.xml.datatype.Duration

public abstract class Duration
extends Object sample code for java.lang.Object definition code for java.lang.Object

Immutable representation of a time span as defined in the W3C XML Schema 1.0 specification.

A Duration object represents a period of Gregorian time, which consists of six fields (years, months, days, hours, minutes, and seconds) plus a sign (+/-) field.

The first five fields have non-negative (>=0) integers or null (which represents that the field is not set), and the seconds field has a non-negative decimal or null. A negative sign indicates a negative duration.

This class provides a number of methods that make it easy to use for the duration datatype of XML Schema 1.0 with the errata.

Order relationship

Duration objects only have partial order, where two values A and B maybe either:

  1. A<B (A is shorter than B)
  2. A>B (A is longer than B)
  3. A==B (A and B are of the same duration)
  4. A<>B (Comparison between A and B is indeterminate)
*

For example, 30 days cannot be meaningfully compared to one month. The compare(Duration duration) sample code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) method implements this relationship.

See the isLongerThan(Duration) sample code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) method for details about the order relationship among Duration objects.

Operations over Duration

This class provides a set of basic arithmetic operations, such as addition, subtraction and multiplication. Because durations don't have total order, an operation could fail for some combinations of operations. For example, you cannot subtract 15 days from 1 month. See the javadoc of those methods for detailed conditions where this could happen.

Also, division of a duration by a number is not provided because the Duration class can only deal with finite precision decimal numbers. For example, one cannot represent 1 sec divided by 3.

However, you could substitute a division by 3 with multiplying by numbers such as 0.3 or 0.333.

Range of allowed values

Because some operations of Duration rely on Calendar sample code for java.util.Calendar definition code for java.util.Calendar even though Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration can hold very large or very small values, some of the methods may not work correctly on such Durations. The impacted methods document their dependency on Calendar sample code for java.util.Calendar definition code for java.util.Calendar .

Since:
1.5
See Also:
XMLGregorianCalendar.add(Duration) sample code for javax.xml.datatype.XMLGregorianCalendar.add(javax.xml.datatype.Duration) definition code for javax.xml.datatype.XMLGregorianCalendar.add(javax.xml.datatype.Duration)

Constructor Summary
Duration sample code for javax.xml.datatype.Duration.Duration() definition code for javax.xml.datatype.Duration.Duration() ()
           
 
Method Summary
abstract  Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration add sample code for javax.xml.datatype.Duration.add(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.add(javax.xml.datatype.Duration) (Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  rhs)
          Computes a new duration whose value is this+rhs.
abstract  void addTo sample code for javax.xml.datatype.Duration.addTo(java.util.Calendar) definition code for javax.xml.datatype.Duration.addTo(java.util.Calendar) (Calendar sample code for java.util.Calendar definition code for java.util.Calendar  calendar)
          Adds this duration to a Calendar sample code for java.util.Calendar definition code for java.util.Calendar object.
 void addTo sample code for javax.xml.datatype.Duration.addTo(java.util.Date) definition code for javax.xml.datatype.Duration.addTo(java.util.Date) (Date sample code for java.util.Date definition code for java.util.Date  date)
          Adds this duration to a Date sample code for java.util.Date definition code for java.util.Date object.
abstract  int compare sample code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) (Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  duration)
          Partial order relation comparison with this Duration instance.
 boolean equals sample code for javax.xml.datatype.Duration.equals(java.lang.Object) definition code for javax.xml.datatype.Duration.equals(java.lang.Object) (Object sample code for java.lang.Object definition code for java.lang.Object  duration)
          Checks if this duration object has the same duration as another Duration object.
 int getDays sample code for javax.xml.datatype.Duration.getDays() definition code for javax.xml.datatype.Duration.getDays() ()
          Obtains the value of the DAYS field as an integer value, or 0 if not present.
abstract  Number sample code for java.lang.Number definition code for java.lang.Number getField sample code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field) definition code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field) (DatatypeConstants.Field sample code for javax.xml.datatype.DatatypeConstants.Field definition code for javax.xml.datatype.DatatypeConstants.Field  field)
          Gets the value of a field.
 int getHours sample code for javax.xml.datatype.Duration.getHours() definition code for javax.xml.datatype.Duration.getHours() ()
          Obtains the value of the HOURS field as an integer value, or 0 if not present.
 int getMinutes sample code for javax.xml.datatype.Duration.getMinutes() definition code for javax.xml.datatype.Duration.getMinutes() ()
          Obtains the value of the MINUTES field as an integer value, or 0 if not present.
 int getMonths sample code for javax.xml.datatype.Duration.getMonths() definition code for javax.xml.datatype.Duration.getMonths() ()
          Obtains the value of the MONTHS field as an integer value, or 0 if not present.
 int getSeconds sample code for javax.xml.datatype.Duration.getSeconds() definition code for javax.xml.datatype.Duration.getSeconds() ()
          Obtains the value of the SECONDS field as an integer value, or 0 if not present.
abstract  int getSign sample code for javax.xml.datatype.Duration.getSign() definition code for javax.xml.datatype.Duration.getSign() ()
          Returns the sign of this duration in -1,0, or 1.
 long getTimeInMillis sample code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Calendar) definition code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Calendar) (Calendar sample code for java.util.Calendar definition code for java.util.Calendar  startInstant)
          Returns the length of the duration in milli-seconds.
 long getTimeInMillis sample code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Date) definition code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Date) (Date sample code for java.util.Date definition code for java.util.Date  startInstant)
          Returns the length of the duration in milli-seconds.
 QName sample code for javax.xml.namespace.QName definition code for javax.xml.namespace.QName getXMLSchemaType sample code for javax.xml.datatype.Duration.getXMLSchemaType() definition code for javax.xml.datatype.Duration.getXMLSchemaType() ()
          Return the name of the XML Schema date/time type that this instance maps to.
 int getYears sample code for javax.xml.datatype.Duration.getYears() definition code for javax.xml.datatype.Duration.getYears() ()
          Get the years value of this Duration as an int or 0 if not present.
abstract  int hashCode sample code for javax.xml.datatype.Duration.hashCode() definition code for javax.xml.datatype.Duration.hashCode() ()
          Returns a hash code consistent with the definition of the equals method.
 boolean isLongerThan sample code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) (Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  duration)
          Checks if this duration object is strictly longer than another Duration object.
abstract  boolean isSet sample code for javax.xml.datatype.Duration.isSet(javax.xml.datatype.DatatypeConstants.Field) definition code for javax.xml.datatype.Duration.isSet(javax.xml.datatype.DatatypeConstants.Field) (DatatypeConstants.Field sample code for javax.xml.datatype.DatatypeConstants.Field definition code for javax.xml.datatype.DatatypeConstants.Field  field)
          Checks if a field is set.
 boolean isShorterThan sample code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration) (Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  duration)
          Checks if this duration object is strictly shorter than another Duration object.
abstract  Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration multiply sample code for javax.xml.datatype.Duration.multiply(java.math.BigDecimal) definition code for javax.xml.datatype.Duration.multiply(java.math.BigDecimal) (BigDecimal sample code for java.math.BigDecimal definition code for java.math.BigDecimal  factor)
          Computes a new duration whose value is factor times longer than the value of this duration.
 Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration multiply sample code for javax.xml.datatype.Duration.multiply(int) definition code for javax.xml.datatype.Duration.multiply(int) (int factor)
          Computes a new duration whose value is factor times longer than the value of this duration.
abstract  Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration negate sample code for javax.xml.datatype.Duration.negate() definition code for javax.xml.datatype.Duration.negate() ()
          Returns a new Duration object whose value is -this.
abstract  Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration normalizeWith sample code for javax.xml.datatype.Duration.normalizeWith(java.util.Calendar) definition code for javax.xml.datatype.Duration.normalizeWith(java.util.Calendar) (Calendar sample code for java.util.Calendar definition code for java.util.Calendar  startTimeInstant)
          Converts the years and months fields into the days field by using a specific time instant as the reference point.
 Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration subtract sample code for javax.xml.datatype.Duration.subtract(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.subtract(javax.xml.datatype.Duration) (Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  rhs)
          Computes a new duration whose value is this-rhs.
 String sample code for java.lang.String definition code for java.lang.String toString sample code for javax.xml.datatype.Duration.toString() definition code for javax.xml.datatype.Duration.toString() ()
          Returns a String representation of this Duration Object.
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Constructor Detail

Duration sample code for javax.xml.datatype.Duration() definition code for javax.xml.datatype.Duration()

public Duration()
Method Detail

getXMLSchemaType sample code for javax.xml.datatype.Duration.getXMLSchemaType() definition code for javax.xml.datatype.Duration.getXMLSchemaType()

public QName sample code for javax.xml.namespace.QName definition code for javax.xml.namespace.QName  getXMLSchemaType()

Return the name of the XML Schema date/time type that this instance maps to. Type is computed based on fields that are set, i.e. isSet(DatatypeConstants.Field field) sample code for javax.xml.datatype.Duration.isSet(javax.xml.datatype.DatatypeConstants.Field) definition code for javax.xml.datatype.Duration.isSet(javax.xml.datatype.DatatypeConstants.Field) == true.

Required fields for XML Schema 1.0 Date/Time Datatypes.
(timezone is optional for all date/time datatypes)
Datatype year month day hour minute second
DatatypeConstants.DURATION sample code for javax.xml.datatype.DatatypeConstants.DURATION definition code for javax.xml.datatype.DatatypeConstants.DURATION X X X X X X
DatatypeConstants.DURATION_DAYTIME sample code for javax.xml.datatype.DatatypeConstants.DURATION_DAYTIME definition code for javax.xml.datatype.DatatypeConstants.DURATION_DAYTIME X X X X
DatatypeConstants.DURATION_YEARMONTH sample code for javax.xml.datatype.DatatypeConstants.DURATION_YEARMONTH definition code for javax.xml.datatype.DatatypeConstants.DURATION_YEARMONTH X X

Returns:
one of the following constants: DatatypeConstants.DURATION sample code for javax.xml.datatype.DatatypeConstants.DURATION definition code for javax.xml.datatype.DatatypeConstants.DURATION , DatatypeConstants.DURATION_DAYTIME sample code for javax.xml.datatype.DatatypeConstants.DURATION_DAYTIME definition code for javax.xml.datatype.DatatypeConstants.DURATION_DAYTIME or DatatypeConstants.DURATION_YEARMONTH sample code for javax.xml.datatype.DatatypeConstants.DURATION_YEARMONTH definition code for javax.xml.datatype.DatatypeConstants.DURATION_YEARMONTH .
Throws:
IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException - If the combination of set fields does not match one of the XML Schema date/time datatypes.

getSign sample code for javax.xml.datatype.Duration.getSign() definition code for javax.xml.datatype.Duration.getSign()

public abstract int getSign()
Returns the sign of this duration in -1,0, or 1.

Returns:
-1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is positive.

getYears sample code for javax.xml.datatype.Duration.getYears() definition code for javax.xml.datatype.Duration.getYears()

public int getYears()

Get the years value of this Duration as an int or 0 if not present.

getYears() is a convenience method for getField(DatatypeConstants.YEARS) sample code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field) definition code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field) .

As the return value is an int, an incorrect value will be returned for Durations with years that go beyond the range of an int. Use getField(DatatypeConstants.YEARS) sample code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field) definition code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field) to avoid possible loss of precision.

Returns:
If the years field is present, return its value as an int, else return 0.

getMonths sample code for javax.xml.datatype.Duration.getMonths() definition code for javax.xml.datatype.Duration.getMonths()

public int getMonths()
Obtains the value of the MONTHS field as an integer value, or 0 if not present. This method works just like getYears() sample code for javax.xml.datatype.Duration.getYears() definition code for javax.xml.datatype.Duration.getYears() except that this method works on the MONTHS field.

Returns:
Months of this Duration.

getDays sample code for javax.xml.datatype.Duration.getDays() definition code for javax.xml.datatype.Duration.getDays()

public int getDays()
Obtains the value of the DAYS field as an integer value, or 0 if not present. This method works just like getYears() sample code for javax.xml.datatype.Duration.getYears() definition code for javax.xml.datatype.Duration.getYears() except that this method works on the DAYS field.

Returns:
Days of this Duration.

getHours sample code for javax.xml.datatype.Duration.getHours() definition code for javax.xml.datatype.Duration.getHours()

public int getHours()
Obtains the value of the HOURS field as an integer value, or 0 if not present. This method works just like getYears() sample code for javax.xml.datatype.Duration.getYears() definition code for javax.xml.datatype.Duration.getYears() except that this method works on the HOURS field.

Returns:
Hours of this Duration.

getMinutes sample code for javax.xml.datatype.Duration.getMinutes() definition code for javax.xml.datatype.Duration.getMinutes()

public int getMinutes()
Obtains the value of the MINUTES field as an integer value, or 0 if not present. This method works just like getYears() sample code for javax.xml.datatype.Duration.getYears() definition code for javax.xml.datatype.Duration.getYears() except that this method works on the MINUTES field.

Returns:
Minutes of this Duration.

getSeconds sample code for javax.xml.datatype.Duration.getSeconds() definition code for javax.xml.datatype.Duration.getSeconds()

public int getSeconds()
Obtains the value of the SECONDS field as an integer value, or 0 if not present. This method works just like getYears() sample code for javax.xml.datatype.Duration.getYears() definition code for javax.xml.datatype.Duration.getYears() except that this method works on the SECONDS field.

Returns:
seconds in the integer value. The fraction of seconds will be discarded (for example, if the actual value is 2.5, this method returns 2)

getTimeInMillis sample code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Calendar) definition code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Calendar)

public long getTimeInMillis(Calendar sample code for java.util.Calendar definition code for java.util.Calendar  startInstant)

Returns the length of the duration in milli-seconds.

If the seconds field carries more digits than milli-second order, those will be simply discarded (or in other words, rounded to zero.) For example, for any Calendar value x,

 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.
 

Note that this method uses the addTo(Calendar) sample code for javax.xml.datatype.Duration.addTo(java.util.Calendar) definition code for javax.xml.datatype.Duration.addTo(java.util.Calendar) method, which may work incorrectly with Duration objects with very large values in its fields. See the addTo(Calendar) sample code for javax.xml.datatype.Duration.addTo(java.util.Calendar) definition code for javax.xml.datatype.Duration.addTo(java.util.Calendar) method for details.

Parameters:
startInstant - The length of a month/year varies. The startInstant is used to disambiguate this variance. Specifically, this method returns the difference between startInstant and startInstant+duration
Returns:
milliseconds between startInstant and startInstant plus this Duration
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if startInstant parameter is null.

getTimeInMillis sample code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Date) definition code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Date)

public long getTimeInMillis(Date sample code for java.util.Date definition code for java.util.Date  startInstant)

Returns the length of the duration in milli-seconds.

If the seconds field carries more digits than milli-second order, those will be simply discarded (or in other words, rounded to zero.) For example, for any Date value x,

 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.
 

Note that this method uses the addTo(Date) sample code for javax.xml.datatype.Duration.addTo(java.util.Date) definition code for javax.xml.datatype.Duration.addTo(java.util.Date) method, which may work incorrectly with Duration objects with very large values in its fields. See the addTo(Date) sample code for javax.xml.datatype.Duration.addTo(java.util.Date) definition code for javax.xml.datatype.Duration.addTo(java.util.Date) method for details.

Parameters:
startInstant - The length of a month/year varies. The startInstant is used to disambiguate this variance. Specifically, this method returns the difference between startInstant and startInstant+duration.
Returns:
milliseconds between startInstant and startInstant plus this Duration
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - If the startInstant parameter is null.
See Also:
getTimeInMillis(Calendar) sample code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Calendar) definition code for javax.xml.datatype.Duration.getTimeInMillis(java.util.Calendar)

getField sample code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field) definition code for javax.xml.datatype.Duration.getField(javax.xml.datatype.DatatypeConstants.Field)

public abstract Number sample code for java.lang.Number definition code for java.lang.Number  getField(DatatypeConstants.Field sample code for javax.xml.datatype.DatatypeConstants.Field definition code for javax.xml.datatype.DatatypeConstants.Field  field)
Gets the value of a field. Fields of a duration object may contain arbitrary large value. Therefore this method is designed to return a Number sample code for java.lang.Number definition code for java.lang.Number object. In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned number will be a non-negative integer. In case of seconds, the returned number may be a non-negative decimal value.

Parameters:
field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)
Returns:
If the specified field is present, this method returns a non-null non-negative Number sample code for java.lang.Number definition code for java.lang.Number object that represents its value. If it is not present, return null. For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method returns a BigInteger sample code for java.math.BigInteger definition code for java.math.BigInteger object. For SECONDS, this method returns a BigDecimal sample code for java.math.BigDecimal definition code for java.math.BigDecimal .
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - If the field is null.

isSet sample code for javax.xml.datatype.Duration.isSet(javax.xml.datatype.DatatypeConstants.Field) definition code for javax.xml.datatype.Duration.isSet(javax.xml.datatype.DatatypeConstants.Field)

public abstract boolean isSet(DatatypeConstants.Field sample code for javax.xml.datatype.DatatypeConstants.Field definition code for javax.xml.datatype.DatatypeConstants.Field  field)
Checks if a field is set. A field of a duration object may or may not be present. This method can be used to test if a field is present.

Parameters:
field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)
Returns:
true if the field is present. false if not.
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - If the field parameter is null.

add sample code for javax.xml.datatype.Duration.add(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.add(javax.xml.datatype.Duration)

public abstract Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  add(Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  rhs)

Computes a new duration whose value is this+rhs.

For example,

 "1 day" + "-3 days" = "-2 days"
 "1 year" + "1 day" = "1 year and 1 day"
 "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"
 "15 hours" + "-3 days" = "-(2 days,9 hours)"
 "1 year" + "-1 day" = IllegalStateException
 

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException .

Formally, the computation is defined as follows.

Firstly, we can assume that two Durations to be added are both positive without losing generality (i.e., (-X)+Y=Y-X, X+(-Y)=X-Y, (-X)+(-Y)=-(X+Y))

Addition of two positive Durations are simply defined as field by field addition where missing fields are treated as 0.

A field of the resulting Duration will be unset if and only if respective fields of two input Durations are unset.

Note that lhs.add(rhs) will be always successful if lhs.signum()*rhs.signum()!=-1 or both of them are normalized.

Parameters:
rhs - Duration to add to this Duration
Returns:
non-null valid Duration object.
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - If the rhs parameter is null.
IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException - If two durations cannot be meaningfully added. For example, adding negative one day to one month causes this exception.
See Also:
subtract(Duration) sample code for javax.xml.datatype.Duration.subtract(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.subtract(javax.xml.datatype.Duration)

addTo sample code for javax.xml.datatype.Duration.addTo(java.util.Calendar) definition code for javax.xml.datatype.Duration.addTo(java.util.Calendar)

public abstract void addTo(Calendar sample code for java.util.Calendar definition code for java.util.Calendar  calendar)
Adds this duration to a Calendar sample code for java.util.Calendar definition code for java.util.Calendar object.

Calls Calendar.add(int,int) sample code for java.util.Calendar.add(int, int) definition code for java.util.Calendar.add(int, int) in the order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS if those fields are present. Because the Calendar sample code for java.util.Calendar definition code for java.util.Calendar class uses int to hold values, there are cases where this method won't work correctly (for example if values of fields exceed the range of int.)

Also, since this duration class is a Gregorian duration, this method will not work correctly if the given Calendar sample code for java.util.Calendar definition code for java.util.Calendar object is based on some other calendar systems.

Any fractional parts of this Duration object beyond milliseconds will be simply ignored. For example, if this duration is "P1.23456S", then 1 is added to SECONDS, 234 is added to MILLISECONDS, and the rest will be unused.

Note that because Calendar.add(int, int) sample code for java.util.Calendar.add(int, int) definition code for java.util.Calendar.add(int, int) is using int, Duration with values beyond the range of int in its fields will cause overflow/underflow to the given Calendar sample code for java.util.Calendar definition code for java.util.Calendar . XMLGregorianCalendar.add(Duration) sample code for javax.xml.datatype.XMLGregorianCalendar.add(javax.xml.datatype.Duration) definition code for javax.xml.datatype.XMLGregorianCalendar.add(javax.xml.datatype.Duration) provides the same basic operation as this method while avoiding the overflow/underflow issues.

Parameters:
calendar - A calendar object whose value will be modified.
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if the calendar parameter is null.

addTo sample code for javax.xml.datatype.Duration.addTo(java.util.Date) definition code for javax.xml.datatype.Duration.addTo(java.util.Date)

public void addTo(Date sample code for java.util.Date definition code for java.util.Date  date)
Adds this duration to a Date sample code for java.util.Date definition code for java.util.Date object.

The given date is first converted into a GregorianCalendar sample code for java.util.GregorianCalendar definition code for java.util.GregorianCalendar , then the duration is added exactly like the addTo(Calendar) sample code for javax.xml.datatype.Duration.addTo(java.util.Calendar) definition code for javax.xml.datatype.Duration.addTo(java.util.Calendar) method.

The updated time instant is then converted back into a Date sample code for java.util.Date definition code for java.util.Date object and used to update the given Date sample code for java.util.Date definition code for java.util.Date object.

This somewhat redundant computation is necessary to unambiguously determine the duration of months and years.

Parameters:
date - A date object whose value will be modified.
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if the date parameter is null.

subtract sample code for javax.xml.datatype.Duration.subtract(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.subtract(javax.xml.datatype.Duration)

public Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  subtract(Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  rhs)

Computes a new duration whose value is this-rhs.

For example:

 "1 day" - "-3 days" = "4 days"
 "1 year" - "1 day" = IllegalStateException
 "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
 "15 hours" - "-3 days" = "3 days and 15 hours"
 "1 year" - "-1 day" = "1 year and 1 day"
 

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException .

Formally the computation is defined as follows. First, we can assume that two Durations are both positive without losing generality. (i.e., (-X)-Y=-(X+Y), X-(-Y)=X+Y, (-X)-(-Y)=-(X-Y))

Then two durations are subtracted field by field. If the sign of any non-zero field F is different from the sign of the most significant field, 1 (if F is negative) or -1 (otherwise) will be borrowed from the next bigger unit of F.

This process is repeated until all the non-zero fields have the same sign.

If a borrow occurs in the days field (in other words, if the computation needs to borrow 1 or -1 month to compensate days), then the computation fails by throwing an IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException .

Parameters:
rhs - Duration to subtract from this Duration.
Returns:
New Duration created from subtracting rhs from this Duration.
Throws:
IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException - If two durations cannot be meaningfully subtracted. For example, subtracting one day from one month causes this exception.
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - If the rhs parameter is null.
See Also:
add(Duration) sample code for javax.xml.datatype.Duration.add(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.add(javax.xml.datatype.Duration)

multiply sample code for javax.xml.datatype.Duration.multiply(int) definition code for javax.xml.datatype.Duration.multiply(int)

public Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  multiply(int factor)

Computes a new duration whose value is factor times longer than the value of this duration.

This method is provided for the convenience. It is functionally equivalent to the following code:

 multiply(new BigDecimal(String.valueOf(factor)))
 

Parameters:
factor - Factor times longer of new Duration to create.
Returns:
New Duration that is factortimes longer than this Duration.
See Also:
multiply(BigDecimal) sample code for javax.xml.datatype.Duration.multiply(java.math.BigDecimal) definition code for javax.xml.datatype.Duration.multiply(java.math.BigDecimal)

multiply sample code for javax.xml.datatype.Duration.multiply(java.math.BigDecimal) definition code for javax.xml.datatype.Duration.multiply(java.math.BigDecimal)

public abstract Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  multiply(BigDecimal sample code for java.math.BigDecimal definition code for java.math.BigDecimal  factor)
Computes a new duration whose value is factor times longer than the value of this duration.

For example,

 "P1M" (1 month) * "12" = "P12M" (12 months)
 "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
 "P1M" (1 month) * "1.5" = IllegalStateException
 

Since the Duration class is immutable, this method doesn't change the value of this object. It simply computes a new Duration object and returns it.

The operation will be performed field by field with the precision of BigDecimal sample code for java.math.BigDecimal definition code for java.math.BigDecimal . Since all the fields except seconds are restricted to hold integers, any fraction produced by the computation will be carried down toward the next lower unit. For example, if you multiply "P1D" (1 day) with "0.5", then it will be 0.5 day, which will be carried down to "PT12H" (12 hours). When fractions of month cannot be meaningfully carried down to days, or year to months, this will cause an IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException to be thrown. For example if you multiple one month by 0.5.

To avoid IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException , use the normalizeWith(Calendar) sample code for javax.xml.datatype.Duration.normalizeWith(java.util.Calendar) definition code for javax.xml.datatype.Duration.normalizeWith(java.util.Calendar) method to remove the years and months fields.

Parameters:
factor - to multiply by
Returns:
returns a non-null valid Duration object
Throws:
IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException - if operation produces fraction in the months field.
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if the factor parameter is null.

negate sample code for javax.xml.datatype.Duration.negate() definition code for javax.xml.datatype.Duration.negate()

public abstract Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  negate()
Returns a new Duration object whose value is -this.

Since the Duration class is immutable, this method doesn't change the value of this object. It simply computes a new Duration object and returns it.

Returns:
always return a non-null valid Duration object.

normalizeWith sample code for javax.xml.datatype.Duration.normalizeWith(java.util.Calendar) definition code for javax.xml.datatype.Duration.normalizeWith(java.util.Calendar)

public abstract Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  normalizeWith(Calendar sample code for java.util.Calendar definition code for java.util.Calendar  startTimeInstant)

Converts the years and months fields into the days field by using a specific time instant as the reference point.

For example, duration of one month normalizes to 31 days given the start time instance "July 8th 2003, 17:40:32".

Formally, the computation is done as follows:

  1. the given Calendar object is cloned
  2. the years, months and days fields will be added to the Calendar sample code for java.util.Calendar definition code for java.util.Calendar object by using the Calendar.add(int,int) sample code for java.util.Calendar.add(int, int) definition code for java.util.Calendar.add(int, int) method
  3. the difference between the two Calendars in computed in milliseconds and converted to days, if a remainder occurs due to Daylight Savings Time, it is discarded
  4. the computed days, along with the hours, minutes and seconds fields of this duration object is used to construct a new Duration object.

Note that since the Calendar class uses int to hold the value of year and month, this method may produce an unexpected result if this duration object holds a very large value in the years or months fields.

Parameters:
startTimeInstant - Calendar reference point.
Returns:
Duration of years and months of this Duration as days.
Throws:
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - If the startTimeInstant parameter is null.

compare sample code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration)

public abstract int compare(Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  duration)

Partial order relation comparison with this Duration instance.

Comparison result must be in accordance with W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration.

Return:

Parameters:
duration - to compare
Returns:
the relationship between this Durationand duration parameter as DatatypeConstants.LESSER sample code for javax.xml.datatype.DatatypeConstants.LESSER definition code for javax.xml.datatype.DatatypeConstants.LESSER , DatatypeConstants.EQUAL sample code for javax.xml.datatype.DatatypeConstants.EQUAL definition code for javax.xml.datatype.DatatypeConstants.EQUAL , DatatypeConstants.GREATER sample code for javax.xml.datatype.DatatypeConstants.GREATER definition code for javax.xml.datatype.DatatypeConstants.GREATER or DatatypeConstants.INDETERMINATE sample code for javax.xml.datatype.DatatypeConstants.INDETERMINATE definition code for javax.xml.datatype.DatatypeConstants.INDETERMINATE .
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if duration is null.
See Also:
isShorterThan(Duration) sample code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration) , isLongerThan(Duration) sample code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration)

isLongerThan sample code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration)

public boolean isLongerThan(Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  duration)

Checks if this duration object is strictly longer than another Duration object.

Duration X is "longer" than Y if and only if X>Y as defined in the section 3.2.6.2 of the XML Schema 1.0 specification.

For example, "P1D" (one day) > "PT12H" (12 hours) and "P2Y" (two years) > "P23M" (23 months).

Parameters:
duration - Duration to test this Duration against.
Returns:
true if the duration represented by this object is longer than the given duration. false otherwise.
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - If duration is null.
See Also:
isShorterThan(Duration) sample code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration) , compare(Duration duration) sample code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration)

isShorterThan sample code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isShorterThan(javax.xml.datatype.Duration)

public boolean isShorterThan(Duration sample code for javax.xml.datatype.Duration definition code for javax.xml.datatype.Duration  duration)

Checks if this duration object is strictly shorter than another Duration object.

Parameters:
duration - Duration to test this Duration against.
Returns:
true if duration parameter is shorter than this Duration, else false.
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if duration is null.
See Also:
isLongerThan(Duration duration) sample code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.isLongerThan(javax.xml.datatype.Duration) , compare(Duration duration) sample code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration)

equals sample code for javax.xml.datatype.Duration.equals(java.lang.Object) definition code for javax.xml.datatype.Duration.equals(java.lang.Object)

public boolean equals(Object sample code for java.lang.Object definition code for java.lang.Object  duration)

Checks if this duration object has the same duration as another Duration object.

For example, "P1D" (1 day) is equal to "PT24H" (24 hours).

Duration X is equal to Y if and only if time instant t+X and t+Y are the same for all the test time instants specified in the section 3.2.6.2 of the XML Schema 1.0 specification.

Note that there are cases where two Durations are "incomparable" to each other, like one month and 30 days. For example,

 !new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))
 

Overrides:
equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) in class Object sample code for java.lang.Object definition code for java.lang.Object
Parameters:
duration - A non-null valid Duration object.
Returns:
true if this duration is the same length as duration. false if duration is not a Duration object or its length is different from this duration.
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
NullPointerException sample code for java.lang.NullPointerException definition code for java.lang.NullPointerException - if parameter is null.
See Also:
compare(Duration duration) sample code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration) definition code for javax.xml.datatype.Duration.compare(javax.xml.datatype.Duration)

hashCode sample code for javax.xml.datatype.Duration.hashCode() definition code for javax.xml.datatype.Duration.hashCode()

public abstract int hashCode()
Returns a hash code consistent with the definition of the equals method.

Overrides:
hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() in class Object sample code for java.lang.Object definition code for java.lang.Object
Returns:
a hash code value for this object.
See Also:
Object.hashCode() sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode()

toString sample code for javax.xml.datatype.Duration.toString() definition code for javax.xml.datatype.Duration.toString()

public String sample code for java.lang.String definition code for java.lang.String  toString()

Returns a String representation of this Duration Object.

The result is formatted according to the XML Schema 1.0 spec and can be always parsed back later into the equivalent Duration Object by DatatypeFactory.newDuration(String lexicalRepresentation) sample code for javax.xml.datatype.DatatypeFactory.newDuration(java.lang.String) definition code for javax.xml.datatype.DatatypeFactory.newDuration(java.lang.String) .

Formally, the following holds for any Duration Object x:

 new Duration(x.toString()).equals(x)
 

Overrides:
toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() in class Object sample code for java.lang.Object definition code for java.lang.Object
Returns:
A non-null valid String representation of this Duration.