Added in API level 8

Duration

abstract class Duration

kotlin.Any
↳	javax.xml.datatype.Duration

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(javax.xml.datatype.Duration) method implements this relationship.

See the 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 even though 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.

Summary

Public constructors
Duration()

Public methods
abstract Duration!	add(rhs: Duration!) Computes a new duration whose value is this+rhs.
abstract Unit	addTo(calendar: Calendar!) Adds this duration to a Calendar object.
open Unit	addTo(date: Date!) Adds this duration to a Date object.
abstract Int	compare(duration: Duration!) Partial order relation comparison with this Duration instance.
open Boolean	equals(other: Any?) Checks if this duration object has the same duration as another Duration object.
open Int	getDays() Obtains the value of the DAYS field as an integer value, or 0 if not present.
abstract Number!	getField(field: DatatypeConstants.Field!) Gets the value of a field.
open Int	getHours() Obtains the value of the HOURS field as an integer value, or 0 if not present.
open Int	getMinutes() Obtains the value of the MINUTES field as an integer value, or 0 if not present.
open Int	getMonths() Obtains the value of the MONTHS field as an integer value, or 0 if not present.
open Int	getSeconds() Obtains the value of the SECONDS field as an integer value, or 0 if not present.
abstract Int	getSign() Returns the sign of this duration in -1,0, or 1.
open Long	getTimeInMillis(startInstant: Calendar!) Returns the length of the duration in milliseconds.
open Long	getTimeInMillis(startInstant: Date!) Returns the length of the duration in milliseconds.
open QName!	getXMLSchemaType() Return the name of the XML Schema date/time type that this instance maps to.
open Int	getYears() Get the years value of this Duration as an int or 0 if not present.
abstract Int	hashCode() Returns a hash code consistent with the definition of the equals method.
open Boolean	isLongerThan(duration: Duration!) Checks if this duration object is strictly longer than another Duration object.
abstract Boolean	isSet(field: DatatypeConstants.Field!) Checks if a field is set.
open Boolean	isShorterThan(duration: Duration!) Checks if this duration object is strictly shorter than another Duration object.
open Duration!	multiply(factor: Int) Computes a new duration whose value is factor times longer than the value of this duration.
abstract Duration!	multiply(factor: BigDecimal!) Computes a new duration whose value is factor times longer than the value of this duration.
abstract Duration!	negate() Returns a new Duration object whose value is -this.
abstract Duration!	normalizeWith(startTimeInstant: Calendar!) Converts the years and months fields into the days field by using a specific time instant as the reference point.
open Duration!	subtract(rhs: Duration!) Computes a new duration whose value is this-rhs.
open String	toString() Returns a String representation of this Duration Object.

Public constructors

Duration

Added in API level 8

Duration()

Public methods

add

Added in API level 8

abstract fun add(rhs: Duration!): Duration!

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.

Parameters
rhs	Duration!: Duration to add to this Duration

Return
Duration!	non-null valid Duration object.

Exceptions
java.lang.NullPointerException	If the rhs parameter is null.
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)

addTo

Added in API level 8

abstract fun addTo(calendar: Calendar!): Unit

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.

Parameters
calendar	Calendar!: A calendar object whose value will be modified.

Exceptions
java.lang.NullPointerException	if the calendar parameter is null.

addTo

Added in API level 8

open fun addTo(date: Date!): Unit

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(java.util.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.

Parameters
date	Date!: A date object whose value will be modified.

Exceptions
java.lang.NullPointerException	if the date parameter is null.

compare

Added in API level 8

abstract fun compare(duration: Duration!): Int

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

Parameters
duration	Duration!: to compare

Return
Int	the relationship between this Durationand duration parameter as DatatypeConstants#LESSER, DatatypeConstants#EQUAL, DatatypeConstants#GREATER or DatatypeConstants#INDETERMINATE.

Exceptions
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.
java.lang.NullPointerException	if duration is null.

See Also

• #isShorterThan(Duration)
• #isLongerThan(Duration)

equals

Added in API level 8

open fun equals(other: Any?): Boolean

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

Parameters
obj	the reference object with which to compare.
duration	A non-null valid Duration object.

Return
Boolean	true if this duration is the same length as duration. false if duration is not a Duration object, is null, or its length is different from this duration.

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

See Also

• #compare(Duration duration)

getDays

Added in API level 8

open fun getDays(): Int

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.

Return
Int	Days of this Duration.

getField

Added in API level 8

abstract fun getField(field: DatatypeConstants.Field!): Number!

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.

Parameters
field	DatatypeConstants.Field!: one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)

Return
Number!	If the specified field is present, this method returns a non-null non-negative Number object that represents its value. If it is not present, return null. For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method returns a java.math.BigInteger object. For SECONDS, this method returns a java.math.BigDecimal.

Exceptions
java.lang.NullPointerException	If the field is null.

getHours

Added in API level 8

open fun getHours(): Int

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.

Return
Int	Hours of this Duration.

getMinutes

Added in API level 8

open fun getMinutes(): Int

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.

Return
Int	Minutes of this Duration.

getMonths

Added in API level 8

open fun getMonths(): Int

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.

Return
Int	Months of this Duration.

getSeconds

Added in API level 8

open fun getSeconds(): Int

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.

Return
Int	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)

getSign

Added in API level 8

abstract fun getSign(): Int

Returns the sign of this duration in -1,0, or 1.

Return
Int	-1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is positive.

getTimeInMillis

Added in API level 8

open fun getTimeInMillis(startInstant: Calendar!): Long

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,

<code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
  <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
  

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

Parameters
startInstant	Calendar!: 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

Return
Long	milliseconds between startInstant and startInstant plus this Duration

Exceptions
java.lang.NullPointerException	if startInstant parameter is null.

getTimeInMillis

Added in API level 8

open fun getTimeInMillis(startInstant: Date!): Long

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,

<code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
  <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
  

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

Parameters
startInstant	Date!: 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.

Return
Long	milliseconds between startInstant and startInstant plus this Duration

Exceptions
java.lang.NullPointerException	If the startInstant parameter is null.

See Also

• #getTimeInMillis(Calendar)

getXMLSchemaType

Added in API level 8

open fun getXMLSchemaType(): QName!

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

Return
QName!	one of the following constants: DatatypeConstants#DURATION, DatatypeConstants#DURATION_DAYTIME or DatatypeConstants#DURATION_YEARMONTH.

Exceptions
java.lang.IllegalStateException	If the combination of set fields does not match one of the XML Schema date/time datatypes.

getYears

Added in API level 8

open fun getYears(): Int

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.

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

hashCode

Added in API level 8

abstract fun hashCode(): Int

Returns a hash code consistent with the definition of the equals method.

Return
Int	a hash code value for this object.

See Also

• java.lang.Object#hashCode()

isLongerThan

Added in API level 8

open fun isLongerThan(duration: Duration!): Boolean

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!: Duration to test this Duration against.

Return
Boolean	true if the duration represented by this object is longer than the given duration. false otherwise.

Exceptions
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.
java.lang.NullPointerException	If duration is null.

See Also

• #isShorterThan(Duration)
• #compare(Duration duration)

isSet

Added in API level 8

abstract fun isSet(field: DatatypeConstants.Field!): Boolean

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	DatatypeConstants.Field!: one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)

Return
Boolean	true if the field is present. false if not.

Exceptions
java.lang.NullPointerException	If the field parameter is null.

isShorterThan

Added in API level 8

open fun isShorterThan(duration: Duration!): Boolean

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

Parameters
duration	Duration!: Duration to test this Duration against.

Return
Boolean	true if duration parameter is shorter than this Duration, else false.

Exceptions
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.
java.lang.NullPointerException	if duration is null.

See Also

• #isLongerThan(Duration duration)
• #compare(Duration duration)

multiply

Added in API level 8

open fun multiply(factor: Int): Duration!

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	Int: Factor times longer of new Duration to create.

Return
Duration!	New Duration that is factortimes longer than this Duration.

See Also

• #multiply(BigDecimal)

multiply

Added in API level 8

abstract fun multiply(factor: BigDecimal!): Duration!

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(java.util.Calendar) method to remove the years and months fields.

Parameters
factor	BigDecimal!: to multiply by

Return
Duration!	returns a non-null valid Duration object

Exceptions
java.lang.IllegalStateException	if operation produces fraction in the months field.
java.lang.NullPointerException	if the factor parameter is null.

negate

Added in API level 8

abstract fun negate(): Duration!

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.

Return
Duration!	always return a non-null valid Duration object.

normalizeWith

Added in API level 8

abstract fun normalizeWith(startTimeInstant: Calendar!): Duration!

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 object by using the 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!: Calendar reference point.

Return
Duration!	Duration of years and months of this Duration as days.

Exceptions
java.lang.NullPointerException	If the startTimeInstant parameter is null.

subtract

Added in API level 8

open fun subtract(rhs: Duration!): Duration!

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.

Parameters
rhs	Duration!: Duration to subtract from this Duration.

Return
Duration!	New Duration created from subtracting rhs from this Duration.

Exceptions
java.lang.IllegalStateException	If two durations cannot be meaningfully subtracted. For example, subtracting one day from one month causes this exception.
java.lang.NullPointerException	If the rhs parameter is null.

See Also

• #add(Duration)

toString

Added in API level 8

open fun toString(): String

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)
  

Return
String	A non-null valid String representation of this Duration.