abstract public Duration add(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 .
 


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.

 abstract public  void addTo(Calendar calendar)
Adds this duration to a Calendar  object.


Calls 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  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 
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)  is using
int, Duration with values beyond the
range of int in its fields
will cause overflow/underflow to the given Calendar .
XMLGregorianCalendar#add(Duration)  provides the same
basic operation as this method while avoiding
the overflow/underflow issues.

 public  void addTo(Date date) 
{
        // check data parameter
        if (date == null) {
            throw new NullPointerException(
                    "Cannot call "
                    + this.getClass().getName()
                    + "#addTo(Date date) with date == null."
            );
        }
        Calendar cal = new GregorianCalendar();
        cal.setTime(date); 
        this.addTo(cal);
        date.setTime(getCalendarTimeInMillis(cal));
}

Adds this duration to a Date object.

The given date is first converted into a java.util.GregorianCalendar , then the duration is added exactly like the #addTo(Calendar) method.

The updated time instant is then converted back into a Date object and used to update the given Date object.

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

 abstract public int compare(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:

  
DatatypeConstants#LESSER  if this Duration is shorter than duration parameter
  
DatatypeConstants#EQUAL  if this Duration is equal to duration parameter
  
DatatypeConstants#GREATER  if this Duration is longer than duration parameter
  
DatatypeConstants#INDETERMINATE  if a conclusive partial order relation cannot be determined

 public boolean equals(Object duration) 
{
        if (duration == this) {
            return true;
        }
        if (duration instanceof Duration) {
            return compare((Duration) duration) == DatatypeConstants.EQUAL;
        }
        return false;
}

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"))

 public int getDays() 
{
        return getFieldValueAsInt(DatatypeConstants.DAYS);
}

Obtains the value of the DAYS field as an integer value, or 0 if not present. This method works just like #getYears() except that this method works on the DAYS field.

 abstract public Number getField(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  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.

 public int getHours() 
{
        return getFieldValueAsInt(DatatypeConstants.HOURS);
}

Obtains the value of the HOURS field as an integer value, or 0 if not present. This method works just like #getYears() except that this method works on the HOURS field.

 public int getMinutes() 
{
        return getFieldValueAsInt(DatatypeConstants.MINUTES);
}

Obtains the value of the MINUTES field as an integer value, or 0 if not present. This method works just like #getYears() except that this method works on the MINUTES field.

 public int getMonths() 
{
        return getFieldValueAsInt(DatatypeConstants.MONTHS);
}

Obtains the value of the MONTHS field as an integer value, or 0 if not present. This method works just like #getYears() except that this method works on the MONTHS field.

 public int getSeconds() 
{
        return getFieldValueAsInt(DatatypeConstants.SECONDS);
}

Obtains the value of the SECONDS field as an integer value, or 0 if not present. This method works just like #getYears() except that this method works on the SECONDS field.

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

 public long getTimeInMillis(Calendar startInstant) 
{
        Calendar cal = (Calendar) startInstant.clone();
        addTo(cal);
        return getCalendarTimeInMillis(cal)
        - getCalendarTimeInMillis(startInstant);
}

Returns the length of the duration in milliseconds.

If the seconds field carries more digits than millisecond 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) method, which may work incorrectly with Duration objects with very large values in its fields. See the #addTo(Calendar) method for details.

 public long getTimeInMillis(Date startInstant) 
{
        Calendar cal = new GregorianCalendar();
        cal.setTime(startInstant);
        this.addTo(cal);
        return getCalendarTimeInMillis(cal) - startInstant.getTime();
}

Returns the length of the duration in milliseconds.

If the seconds field carries more digits than millisecond 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) method, which may work incorrectly with Duration objects with very large values in its fields. See the #addTo(Date) method for details.

 public QName getXMLSchemaType() 
{
        boolean yearSet = isSet(DatatypeConstants.YEARS);
        boolean monthSet = isSet(DatatypeConstants.MONTHS);
        boolean daySet = isSet(DatatypeConstants.DAYS);
        boolean hourSet = isSet(DatatypeConstants.HOURS);
        boolean minuteSet = isSet(DatatypeConstants.MINUTES);
        boolean secondSet = isSet(DatatypeConstants.SECONDS);
        // DURATION
        if (yearSet
                && monthSet
                && daySet
                && hourSet
                && minuteSet
                && secondSet) {
            return DatatypeConstants.DURATION;
        }
        // DURATION_DAYTIME
        if (!yearSet
                && !monthSet
                && daySet
                && hourSet
                && minuteSet
                && secondSet) {
            return DatatypeConstants.DURATION_DAYTIME;
        }
        // DURATION_YEARMONTH
        if (yearSet
                && monthSet
                && !daySet
                && !hourSet
                && !minuteSet
                && !secondSet) {
            return DatatypeConstants.DURATION_YEARMONTH;
        }
        // nothing matches
        throw new IllegalStateException(
                "javax.xml.datatype.Duration#getXMLSchemaType():"
                + " this Duration does not match one of the XML Schema date/time datatypes:"
                + " year set = " + yearSet
                + " month set = " + monthSet
                + " day set = " + daySet
                + " hour set = " + hourSet
                + " minute set = " + minuteSet
                + " second set = " + secondSet
        );
}

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) == 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	X	X	X	X	X	X
DatatypeConstants#DURATION_DAYTIME			X	X	X	X
DatatypeConstants#DURATION_YEARMONTH	X	X

 public int getYears() 
{
        return getFieldValueAsInt(DatatypeConstants.YEARS);
}

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

getYears() is a convenience method for getField(DatatypeConstants.YEARS) .

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) to avoid possible loss of precision.

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

 public boolean isLongerThan(Duration duration) 
{
        return compare(duration) == DatatypeConstants.GREATER;
}

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

 abstract public boolean isSet(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.

 public boolean isShorterThan(Duration duration) 
{
        return compare(duration) == DatatypeConstants.LESSER;
}

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

 public Duration multiply(int factor) 
{
        return multiply(BigDecimal.valueOf(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)))

 abstract public Duration multiply(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 . 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  to be thrown. 
For example if you multiple one month by 0.5.


To avoid IllegalStateException , use
the #normalizeWith(Calendar)  method to remove the years
and months fields.

 abstract public 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.

 abstract public Duration normalizeWith(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:

 
the given Calendar object is cloned
 
the years, months and days fields will be added to the Calendar  object
     by using the Calendar#add(int,int)  method
 
 
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
 
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.

 public Duration subtract(Duration rhs) 
{
        return add(rhs.negate());
}

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 .

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 .

 public String toString() 
{
        StringBuffer buf = new StringBuffer();
        if (getSign() <  0) {
            buf.append('-');
        }
        buf.append('P');
        BigInteger years = (BigInteger) getField(DatatypeConstants.YEARS);
        if (years != null) {
            buf.append(years).append('Y');
        }
        BigInteger months = (BigInteger) getField(DatatypeConstants.MONTHS);
        if (months != null) {
            buf.append(months).append('M');
        }
        BigInteger days = (BigInteger) getField(DatatypeConstants.DAYS);
        if (days != null) {
            buf.append(days).append('D');
        }
        BigInteger hours = (BigInteger) getField(DatatypeConstants.HOURS);
        BigInteger minutes = (BigInteger) getField(DatatypeConstants.MINUTES);
        BigDecimal seconds = (BigDecimal) getField(DatatypeConstants.SECONDS);
        if (hours != null || minutes != null || seconds != null) {
            buf.append('T');
            if (hours != null) {
                buf.append(hours).append('H');
            }
            if (minutes != null) {
                buf.append(minutes).append('M');
            }
            if (seconds != null) {
                buf.append(toString(seconds)).append('S');
            }
        }
        return buf.toString();
}

Returns a String representation of this Duration Object.

The result is formatted according to the XML Schema 1.0 specification and can be always parsed back later into the equivalent Duration Object by DatatypeFactory#newDuration(String lexicalRepresentation) .

Formally, the following holds for any Duration Object x:

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