javax.xml.datatype
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 {@link #compare(Duration duration)} method implements this relationship.
See the {@link #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 {@link Calendar}
even though {@link 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 {@link Calendar}.
Since: 1.5
Version: $Revision: 292853 $, $Date: 2005-09-30 16:42:07 -0400 (Fri, 30 Sep 2005) $
See Also: add
Method Summary | |
---|---|
abstract Duration | add(Duration rhs) Computes a new duration whose value is 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 {@link IllegalStateException}. Formally, the computation is defined as follows.
Firstly, we can assume that two
Addition of two positive |
abstract void | addTo(Calendar calendar)
Adds this duration to a {@link Calendar} object.
|
void | addTo(Date date)
Adds this duration to a {@link Date} object.
|
abstract int | compare(Duration duration) Partial order relation comparison with this 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:
|
boolean | equals(Object duration) Checks if this duration object has the same duration
as another 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 |
int | getDays()
Obtains the value of the DAYS field as an integer value,
or 0 if not present.
|
abstract Number | getField(DatatypeConstants.Field field)
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(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.) |
long | getTimeInMillis(Date 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.) |
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
As the return value is an |
abstract int | hashCode()
Returns a hash code consistent with the definition of the equals method.
|
boolean | isLongerThan(Duration duration) Checks if this duration object is strictly longer than
another 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 boolean | isSet(DatatypeConstants.Field field)
Checks if a field is set.
|
boolean | isShorterThan(Duration duration) Checks if this duration object is strictly shorter than
another |
Duration | multiply(int factor) Computes a new duration whose value is This method is provided for the convenience. |
abstract Duration | multiply(BigDecimal factor)
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(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:
Note that since the Calendar class uses |
Duration | subtract(Duration rhs) Computes a new duration whose value is 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 {@link IllegalStateException}. Formally the computation is defined as follows. |
String | toString() Returns a The result is formatted according to the XML Schema 1.0 spec and can be always parsed back later into the
equivalent Formally, the following holds for any new Duration(x.toString()).equals(x) |
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 {@link 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.
Parameters: rhs Duration
to add to this Duration
Returns: non-null valid Duration object.
Throws: 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.
See Also: subtract
Calls {@link 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 {@link 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 {@link 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 {@link 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 {@link Calendar}.
{@link 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.
Throws: NullPointerException if the calendar parameter is null.
The given date is first converted into a {@link java.util.GregorianCalendar}, then the duration is added exactly like the {@link #addTo(Calendar)} method.
The updated time instant is then converted back into a {@link Date} object and used to update the given {@link Date} object.
This somewhat redundant computation is necessary to unambiguously determine the duration of months and years.
Parameters: date A date object whose value will be modified.
Throws: 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:
Duration
is shorter than duration
parameterDuration
is equal to duration
parameterDuration
is longer than duration
parameterParameters: duration to compare
Returns: the relationship between this
Duration
and duration
parameter as
{@link DatatypeConstants#LESSER}, {@link DatatypeConstants#EQUAL}, {@link DatatypeConstants#GREATER}
or {@link DatatypeConstants#INDETERMINATE}.
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. NullPointerException if duration
is null
.
See Also: isShorterThan isLongerThan
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"))
Parameters: duration
A non-null valid Duration
object.
Returns:
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. NullPointerException if parameter is null.
See Also: Duration
Returns: Days of this Duration
.
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 {@link Number} object that represents its value. If it is not present, return null. For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method returns a {@link java.math.BigInteger} object. For SECONDS, this method returns a {@link java.math.BigDecimal}.
Throws: NullPointerException If the field
is null
.
Returns: Hours of this Duration
.
Returns: Minutes of this Duration
.
Returns: Months of this Duration
.
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)
Returns: -1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is positive.
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 {@link #addTo(Calendar)} method,
which may work incorrectly with Duration
objects with
very large values in its fields. See the {@link #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
Throws: NullPointerException if startInstant
parameter
is null.
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 {@link #addTo(Date)} method,
which may work incorrectly with Duration
objects with
very large values in its fields. See the {@link #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
Throws: NullPointerException If the startInstant parameter is null.
See Also: getTimeInMillis
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. {@link #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 |
{@link DatatypeConstants#DURATION} | X | X | X | X | X | X |
{@link DatatypeConstants#DURATION_DAYTIME} | X | X | X | X | ||
{@link DatatypeConstants#DURATION_YEARMONTH} | X | X |
Returns: one of the following constants: {@link DatatypeConstants#DURATION}, {@link DatatypeConstants#DURATION_DAYTIME} or {@link DatatypeConstants#DURATION_YEARMONTH}.
Throws: 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
{@link #getField(DatatypeConstants.Field field) 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 {@link #getField(DatatypeConstants.Field field) 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
.
See Also: Object#hashCode()
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. NullPointerException If duration
is null.
See Also: isShorterThan Duration
Parameters: field one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)
Returns: true if the field is present. false if not.
Throws: NullPointerException If the field parameter is null.
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. 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)))
Parameters: factor Factor times longer of new Duration
to create.
Returns: New Duration
that is factor
times longer than this Duration
.
See Also: multiply
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 {@link 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 {@link IllegalStateException} to be thrown. For example if you multiple one month by 0.5.
To avoid {@link IllegalStateException}, use the {@link #normalizeWith(Calendar)} method to remove the years and months fields.
Parameters: factor to multiply by
Returns:
returns a non-null valid Duration
object
Throws: IllegalStateException if operation produces fraction in
the months field.
NullPointerException if the factor
parameter is
null
.
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.
Returns:
always return a non-null valid 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:
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.
Throws: 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 {@link 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 {@link 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. NullPointerException If the rhs parameter is null.
See Also: add
Returns a 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 {@link DatatypeFactory#newDuration(String lexicalRepresentation)}.
Formally, the following holds for any Duration
Object
x:
new Duration(x.toString()).equals(x)
Returns: A non-null
valid String
representation of this Duration
.