java.lang.Object | |
↳ | 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.
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)
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
.
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
Computes a new duration whose value is
|
||||||||||
|
Adds this duration to a
Calendar
object.
|
||||||||||
|
Adds this duration to a
Date
object.
|
||||||||||
|
Partial order relation comparison with this
|
||||||||||
|
Checks if this duration object has the same duration
as another
|
||||||||||
|
Obtains the value of the DAYS field as an integer value,
or 0 if not present.
|
||||||||||
|
Gets the value of a field.
|
||||||||||
|
Obtains the value of the HOURS field as an integer value,
or 0 if not present.
|
||||||||||
|
Obtains the value of the MINUTES field as an integer value,
or 0 if not present.
|
||||||||||
|
Obtains the value of the MONTHS field as an integer value,
or 0 if not present.
|
||||||||||
|
Obtains the value of the SECONDS field as an integer value,
or 0 if not present.
|
||||||||||
|
Returns the sign of this duration in -1,0, or 1.
|
||||||||||
|
Returns the length of the duration in milliseconds. |
||||||||||
|
Returns the length of the duration in milliseconds. |
||||||||||
|
Return the name of the XML Schema date/time type that this instance maps to. |
||||||||||
|
Get the years value of this
|
||||||||||
|
Returns a hash code consistent with the definition of the equals method.
|
||||||||||
|
Checks if this duration object is strictly longer than
another
|
||||||||||
|
Checks if a field is set.
|
||||||||||
|
Checks if this duration object is strictly shorter than
another
|
||||||||||
|
Computes a new duration whose value is
|
||||||||||
|
Computes a new duration whose value is
factor
times
longer than the value of this duration.
|
||||||||||
|
Returns a new
Duration
object whose
value is
-this
.
|
||||||||||
|
Converts the years and months fields into the days field by using a specific time instant as the reference point. |
||||||||||
|
Computes a new duration whose value is
|
||||||||||
|
Returns a
|
[Expand]
Inherited Methods
|
|||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
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
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. |
Adds this duration to a
Calendar
object.
Calls
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
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
.
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. |
---|
Adds this duration to a
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. |
---|
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:
LESSER
if this
Duration
is shorter than
duration
parameter
EQUAL
if this
Duration
is equal to
duration
parameter
GREATER
if this
Duration
is longer than
duration
parameter
INDETERMINATE
if a conclusive partial order relation cannot be determined
duration | to compare |
---|
this
Duration
and
duration
parameter as
LESSER
,
EQUAL
,
GREATER
or
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
.
|
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
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"))
duration |
A non-null valid
Duration
object.
|
---|
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.
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. |
---|
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.
Duration
.
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.
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
.
|
---|
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.
Duration
.
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.
Duration
.
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.
Duration
.
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.
Returns the sign of this duration in -1,0, or 1.
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.
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.
|
---|
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.
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. |
---|
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)
==
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 |
DURATION
|
X | X | X | X | X | X |
DURATION_DAYTIME
|
X | X | X | X | ||
DURATION_YEARMONTH
|
X | X |
DURATION
,
DURATION_DAYTIME
or
DURATION_YEARMONTH
.
IllegalStateException | If the combination of set fields does not match one of the XML Schema date/time datatypes. |
---|
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
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
.
Returns a hash code consistent with the definition of the equals method.
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).
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.
|
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.
field | one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.) |
---|
NullPointerException | If the field parameter is null. |
---|
Checks if this duration object is strictly shorter than
another
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.
|
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)))
factor |
Factor times longer of new
Duration
to create.
|
---|
Duration
that is
factor
times longer than this
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(Calendar)
method to remove the years
and months fields.
factor | to multiply by |
---|
Duration
object
IllegalStateException | if operation produces fraction in the months field. |
---|---|
NullPointerException |
if the
factor
parameter is
null
.
|
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.
Duration
object.
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:
Calendar
object
by using the
add(int, int)
method
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.
startTimeInstant |
Calendar
reference point.
|
---|
Duration
of years and months of this
Duration
as days.
NullPointerException | If the startTimeInstant parameter is null. |
---|
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
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. |
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
newDuration(String)
.
Formally, the following holds for any
Duration
Object
x:
new Duration(x.toString()).equals(x)
null
valid
String
representation of this
Duration
.