Class SaxonDuration
DurationValue
.
The JAXP specification for this class defines it in terms of XML Schema 1.0 semantics. This defines a structure with six independent components (year, month, day, hour, minute, second). This implementation is more aligned to the XPath 2.0 semantics of the data type, which essentially defines duration as an integer number of months plus a decimal number of seconds.
-
Constructor Summary
ConstructorsConstructorDescriptionSaxonDuration
(DurationValue duration) Create a SaxonDuration that wraps a supplied DurationValue -
Method Summary
Modifier and TypeMethodDescriptionComputes a new duration whose value isthis+rhs
.void
Adds this duration to aCalendar
object.int
Partial order relation comparison with thisDuration
instance.Get the underlying DurationValuegetField
(DatatypeConstants.Field field) Gets the value of a field.int
getSign()
Returns the sign of this duration in -1,0, or 1.Get the type of this duration, as one of the values xs:duration, xs:dayTimeDuration, or xs:yearMonthDuration.int
hashCode()
Returns a hash code consistent with the definition of the equals method.boolean
isSet
(DatatypeConstants.Field field) Checks if a field is set.multiply
(BigDecimal factor) Computes a new duration whose value isfactor
times longer than the value of this duration.negate()
Returns a newDuration
object whose value is-this
.normalizeWith
(Calendar startTimeInstant) 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 isthis-rhs
.Methods inherited from class javax.xml.datatype.Duration
addTo, equals, getDays, getHours, getMinutes, getMonths, getSeconds, getTimeInMillis, getTimeInMillis, getYears, isLongerThan, isShorterThan, multiply, toString
-
Constructor Details
-
SaxonDuration
Create a SaxonDuration that wraps a supplied DurationValue- Parameters:
duration
- the value to be wrapped.
-
-
Method Details
-
getDurationValue
Get the underlying DurationValue- Returns:
- the underlying DurationValue
-
getXMLSchemaType
Get the type of this duration, as one of the values xs:duration, xs:dayTimeDuration, or xs:yearMonthDuration. (Note that the XML Schema namespace URI is used, whereas the current implementation of the superclass uses a provisional URI allocated in a 2003 W3C working draft)- Overrides:
getXMLSchemaType
in classDuration
- Returns:
- the type of this duration, as one of the values xs:duration, xs:dayTimeDuration, or xs:yearMonthDuration
-
getSign
public int getSign()Returns the sign of this duration in -1,0, or 1. -
getField
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.
The Saxon implementation of duration uses normalized values. This means that the YEARS and DAYS fields may be arbitrarily large, but other components will be limited in size: for example MINUTES will never exceed 60 and MONTHS will never exceed 12.
- Specified by:
getField
in classDuration
- 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 aBigInteger
object. For SECONDS, this method returns aBigDecimal
. - Throws:
NullPointerException
- If thefield
isnull
.
-
isSet
Checks if a field is set. In this implementation, all fields are always set. -
add
Computes a new duration whose value is
this+rhs
.This implementation follows the XPath semantics. This means that the operation will fail if the duration is not a yearMonthDuration or a dayTimeDuration
- Specified by:
add
in classDuration
- Parameters:
rhs
-Duration
to add to thisDuration
- Returns:
- non-null valid Duration object.
- Throws:
NullPointerException
- If the rhs parameter is null.IllegalStateException
- If the durations are not both dayTimeDurations, or both yearMonthDurations.- See Also:
-
subtract
Computes a new duration whose value is
this-rhs
.This implementation follows the XPath semantics. This means that the operation will fail if the duration is not a yearMonthDuration or a dayTimeDuration.
- Overrides:
subtract
in classDuration
- Parameters:
rhs
-Duration
to subtract from thisDuration
- Returns:
- non-null valid Duration object.
- Throws:
NullPointerException
- If the rhs parameter is null.IllegalStateException
- If the durations are not both dayTimeDurations, or both yearMonthDurations.- See Also:
-
addTo
Adds this duration to aCalendar
object.Calls
Calendar.add(int, int)
in the order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS if those fields are present. Because theCalendar
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 usingint
,Duration
with values beyond the range ofint
in its fields will cause overflow/underflow to the givenCalendar
.XMLGregorianCalendar.add(javax.xml.datatype.Duration)
provides the same basic operation as this method while avoiding the overflow/underflow issues.- Specified by:
addTo
in classDuration
- Parameters:
calendar
- A calendar object whose value will be modified.- Throws:
NullPointerException
- if the calendar parameter is null.
-
multiply
Computes a new duration whose value isfactor
times longer than the value of this duration.This implementation follows the XPath semantics. This means that it is defined only on yearMonthDuration and dayTimeDuration. Other cases produce an IllegalStateException.
- Specified by:
multiply
in classDuration
- 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 thefactor
parameter isnull
.
-
negate
Returns a newDuration
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. -
normalizeWith
Converts the years and months fields into the days field by using a specific time instant as the reference point.
This implementation does not support this method
- Specified by:
normalizeWith
in classDuration
- Parameters:
startTimeInstant
-Calendar
reference point.- Returns:
Duration
of years and months of thisDuration
as days.- Throws:
NullPointerException
- If the startTimeInstant parameter is null.UnsupportedOperationException
- Always thrown by this implementation.
-
compare
Partial order relation comparison with this
Duration
instance.This implementation follows the XPath semantics. This means that the result is defined only for dayTimeDuration and yearMonthDuration values, and the result is never indeterminate.
Return:
DatatypeConstants.LESSER
if thisDuration
is shorter thanduration
parameterDatatypeConstants.EQUAL
if thisDuration
is equal toduration
parameterDatatypeConstants.GREATER
if thisDuration
is longer thanduration
parameterDatatypeConstants.INDETERMINATE
if a conclusive partial order relation cannot be determined
- Specified by:
compare
in classDuration
- Parameters:
rhs
- duration to compare- Returns:
- the relationship between
this
Duration
andduration
parameter asDatatypeConstants.LESSER
,DatatypeConstants.EQUAL
,DatatypeConstants.GREATER
orDatatypeConstants.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
- ifduration
isnull
.IllegalArgumentException
- if the operands are not dayTimeDuration or yearMonthDuration values.- See Also:
-
hashCode
public int hashCode()Returns a hash code consistent with the definition of the equals method.
-