public abstract class Duration extends 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.
Duration objects only have partial order, where two values A and B maybe either:
For example, 30 days cannot be meaningfully compared to one month. The compare(Duration duration)
method implements this relationship.
See the isLongerThan(Duration)
method for details about the order relationship among Duration
objects.
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.
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 Duration
s. The impacted methods document their dependency on Calendar
.
Constructor | Description |
---|---|
Duration() |
Default no-arg constructor. |
Modifier and Type | Method | Description |
---|---|---|
abstract Duration |
add |
Computes a new duration whose value is this+rhs . |
abstract void |
addTo |
Adds this duration to a Calendar object. |
void |
addTo |
Adds this duration to a Date object. |
abstract int |
compare |
Partial order relation comparison with this Duration instance. |
boolean |
equals |
Checks if this duration object has the same duration as another Duration object. |
int |
getDays() |
Obtains the value of the DAYS field as an integer value, or 0 if not present. |
abstract Number |
getField |
Gets the value of a field. |
int |
getHours() |
Obtains the value of the HOURS field as an integer value, or 0 if not present. |
int |
getMinutes() |
Obtains the value of the MINUTES field as an integer value, or 0 if not present. |
int |
getMonths() |
Obtains the value of the MONTHS field as an integer value, or 0 if not present. |
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. |
long |
getTimeInMillis |
Returns the length of the duration in milli-seconds. |
long |
getTimeInMillis |
Returns the length of the duration in milli-seconds. |
QName |
getXMLSchemaType() |
Return the name of the XML Schema date/time type that this instance maps to. |
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. |
boolean |
isLongerThan |
Checks if this duration object is strictly longer than another Duration object. |
abstract boolean |
isSet |
Checks if a field is set. |
boolean |
isShorterThan |
Checks if this duration object is strictly shorter than another Duration object. |
Duration |
multiply |
Computes a new duration whose value is factor times longer than the value of this duration. |
abstract Duration |
multiply |
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 |
Converts the years and months fields into the days field by using a specific time instant as the reference point. |
Duration |
subtract |
Computes a new duration whose value is this-rhs . |
String |
toString() |
Returns a String representation of this Duration Object . |
public Duration()
Note: Always use the DatatypeFactory
to construct an instance of Duration
. The constructor on this class cannot be guaranteed to produce an object with a consistent state and may be removed in the future.
public QName getXMLSchemaType()
isSet(DatatypeConstants.Field field)
== true
. 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 |
DatatypeConstants.DURATION
, DatatypeConstants.DURATION_DAYTIME
or DatatypeConstants.DURATION_YEARMONTH
.IllegalStateException
- If the combination of set fields does not match one of the XML Schema date/time datatypes.public abstract int getSign()
public int getYears()
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 Duration
s with years that go beyond the range of an int
. Use getField(DatatypeConstants.YEARS)
to avoid possible loss of precision.
int
, else return 0
.public int getMonths()
getYears()
except that this method works on the MONTHS field.Duration
.public int getDays()
getYears()
except that this method works on the DAYS field.Duration
.public int getHours()
getYears()
except that this method works on the HOURS field.Duration
.public int getMinutes()
getYears()
except that this method works on the MINUTES field.Duration
.public int getSeconds()
getYears()
except that this method works on the SECONDS field.public long getTimeInMillis(Calendar startInstant)
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)
method, which may work incorrectly with Duration
objects with very large values in its fields. See the addTo(Calendar)
method for details.
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
startInstant
and startInstant
plus this Duration
NullPointerException
- if startInstant
parameter is null.public long getTimeInMillis(Date startInstant)
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)
method, which may work incorrectly with Duration
objects with very large values in its fields. See the addTo(Date)
method for details.
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
.startInstant
and startInstant
plus this Duration
NullPointerException
- If the startInstant parameter is null.public abstract Number getField(DatatypeConstants.Field field)
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.field
- one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)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
object. For SECONDS, this method returns a BigDecimal
.NullPointerException
- If the field
is null
.public abstract boolean isSet(DatatypeConstants.Field field)
field
- one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)NullPointerException
- If the field parameter is null.public abstract Duration add(Duration rhs)
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 Duration
s 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 Duration
s 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 Duration
s are unset.
Note that lhs.add(rhs)
will be always successful if lhs.signum()*rhs.signum()!=-1
or both of them are normalized.
rhs
- Duration
to add to this Duration
NullPointerException
- If the rhs parameter is null.IllegalStateException
- If two durations cannot be meaningfully added. For example, adding negative one day to one month causes this exception.public abstract void addTo(Calendar calendar)
Calendar
object. Calls 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.
calendar
- A calendar object whose value will be modified.NullPointerException
- if the calendar parameter is null.public void addTo(Date date)
Date
object. The given date is first converted into a 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.
date
- A date object whose value will be modified.NullPointerException
- if the date parameter is null.public Duration subtract(Duration rhs)
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 Duration
s 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
.
rhs
- Duration
to subtract from this Duration
.Duration
created from subtracting rhs
from this Duration
.IllegalStateException
- If two durations cannot be meaningfully subtracted. For example, subtracting one day from one month causes this exception.NullPointerException
- If the rhs parameter is null.public Duration multiply(int factor)
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)))
factor
- Factor times longer of new Duration
to create.Duration
that is factor
times longer than this Duration
.public abstract Duration multiply(BigDecimal factor)
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.
factor
- to multiply byDuration
objectIllegalStateException
- if operation produces fraction in the months field.NullPointerException
- if the factor
parameter is null
.public abstract Duration negate()
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.
Duration
object.public abstract Duration normalizeWith(Calendar startTimeInstant)
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:
Calendar
object by using the Calendar.add(int,int)
methodNote 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.
startTimeInstant
- Calendar
reference point.Duration
of years and months of this Duration
as days.NullPointerException
- If the startTimeInstant parameter is null.public abstract int compare(Duration duration)
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
parameterDatatypeConstants.EQUAL
if this Duration
is equal to duration
parameterDatatypeConstants.GREATER
if this Duration
is longer than duration
parameterDatatypeConstants.INDETERMINATE
if a conclusive partial order relation cannot be determinedduration
- to comparethis Duration
and duration
parameter as DatatypeConstants.LESSER
, DatatypeConstants.EQUAL
, DatatypeConstants.GREATER
or DatatypeConstants.INDETERMINATE
.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
- if duration
is null
.public boolean isLongerThan(Duration duration)
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).
duration
- Duration
to test this Duration
against.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
- If duration
is null.public boolean isShorterThan(Duration duration)
Duration
object.duration
- Duration
to test this Duration
against.true
if duration
parameter is shorter than this Duration
, else false
.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
- if duration
is null.public boolean equals(Object duration)
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 Duration
s 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"))
equals
in class Object
duration
- The object to compare this Duration
against.true
if this duration is the same length as duration
. false
if duration
is null
, is not a Duration
object, or its length is different from this duration.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.public abstract int hashCode()
public String toString()
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)
.
Formally, the following holds for any Duration
Object
x:
new Duration(x.toString()).equals(x)
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.xml/javax/xml/datatype/Duration.html