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:
A<B (A is shorter than B)
A>B (A is longer than B)
A==B (A and B are of the same duration)
A<>B (Comparison between A and B is indeterminate)
*
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.
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.
normalizeWith(Calendar startTimeInstant)
Converts the years and months fields into the days field
by using a specific time instant as the reference point.
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)
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.
Returns:
If the years field is present, return its value as an int, else return 0.
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() except
that this method works on the MONTHS field.
Returns:
Months of this 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() except
that this method works on the DAYS field.
Returns:
Days of this 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() except
that this method works on the HOURS field.
Returns:
Hours of this 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() except
that this method works on the MINUTES field.
Returns:
Minutes of this 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() 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
public long getTimeInMillis(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) method,
which may work incorrectly with Duration objects with
very large values in its fields. See the addTo(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
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) method,
which may work incorrectly with Duration objects with
very large values in its fields. See the addTo(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
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 - 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 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.
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.
Parameters:
calendar - A calendar object whose value will be modified.
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 to subtract from this Duration.
Returns:
New Duration created from subtracting rhs from this Duration.
Throws:
IllegalStateException - If two durations cannot be meaningfully subtracted. For
example, subtracting one day from one month causes
this exception.
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.
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.
Parameters:
startTimeInstant - Calendar reference point.
Returns:
Duration of years and months of this Duration as days.
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.
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 - 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.
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 - 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.
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,
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 - 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.
Submit a bug or feature For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.