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 Durations.
The impacted methods document their dependency on Calendar.
XMLGregorianCalendar#add(Duration)
| Modifier and Type | Class and Description |
|---|---|
| private static class | DurationImpl.
Representation of |
| Modifier and Type | Field and Description |
|---|---|
| protected BigInteger | days
Days of this |
| private static final BigDecimal[] | FACTORS
1 unit of FIELDS[i] is equivalent to |
| private static final DatatypeConstants. | FIELDS
Internal array of value Fields. |
| private static final TimeZone | GMT
TimeZone for GMT. |
| protected BigInteger | hours
Hours of this |
| private static final BigInteger | MaxIntAsBigInt
BigInteger value of Integer's max value. |
| protected BigInteger | minutes
Minutes of this |
| protected BigInteger | months
Months of this |
| protected BigDecimal | seconds
Seconds of this |
| private static final long | serialVersionUID
Stream Unique Identifier. |
| protected int | signum
Indicates the sign. |
| private static final XMLGregorianCalendar[] | TEST_POINTS
Four constants defined for the comparison of durations. |
| protected BigInteger | years
These were final since Duration is immutable. |
| private static final BigDecimal | ZERO
BigDecimal value of 0. |
| Access | Constructor and Description |
|---|---|
| protected | DurationImpl(boolean
Set to isPositive, BigInteger false to create a negative duration. When the length
of the duration is zero, this parameter will be ignored.of this years, BigInteger Durationof this months, BigInteger Durationof this days, BigInteger Durationof this hours, BigInteger Durationof this minutes, BigDecimal Durationof this seconds)DurationConstructs a new Duration object by specifying each field individually. |
| protected | DurationImpl(final boolean isPositive, final int years, final int months, final int days, final int hours, final int minutes, final int seconds)
Constructs a new Duration object by specifying each field individually. |
| protected | DurationImpl(final long
The length of the duration in milliseconds. durationInMilliSeconds)Constructs a new Duration object by specifying the duration in milliseconds. |
| protected | DurationImpl(String
Lexical representation of a duration. lexicalRepresentation)Constructs a new Duration object by parsing its string representation "PnYnMnDTnHnMnS" as defined in XML Schema 1.0 section 3.2.6.1. |
| Modifier and Type | Method and Description |
|---|---|
| public Duration | Returns: non-null valid Duration object.Duration to add to this DurationImplements abstract javax. Computes a new duration whose value is |
| public void | addTo(Calendar
A calendar object whose value will be modified. calendar)Implements abstract javax. Adds this duration to a |
| public void | addTo(Date
A date object whose value will be modified. date)Overrides javax. Adds this duration to a |
| private static void | |
| protected int | Returns: 1 if positive, -1 negative, or 0 if all fields are zero.Sign. isPositive)Determine the sign of the duration. |
| private void | checkMaxValue(Number
the value of a field field, DatatypeConstants.type of the field, e.g. year, month, day, hour, minute or second. fieldTypeCheck if a field exceeds the maximum value |
| public int | Returns: the relationship betweenthis Durationand duration parameter as
DatatypeConstants#LESSER, DatatypeConstants#EQUAL, DatatypeConstants#GREATER
or DatatypeConstants#INDETERMINATE.Implements abstract javax. Partial order relation comparison with this |
| private int | Returns: INDETERMINATE if the order relationship between date1 and date2 is indeterminate. EQUAL if the order relation between date1 and date2 is EQUAL. If the strict parameter is true, return LESS_THAN if date1 is less than date2 and return GREATER_THAN if date1 is greater than date2. If the strict parameter is false, return LESS_THAN if date1 is less than OR equal to date2 and return GREATER_THAN if date1 is greater than OR equal to date2Unnormalized duration duration1, Duration Unnormalized duration duration2)Compares 2 given durations. |
| private int | |
| private static long | Returns: time value Diff from Xerces; Use JDK 1.5 feature.A calendar object cal)Hides javax. Returns time value in milliseconds |
| public int | Returns: Days of thisDuration.Overrides javax. Obtains the value of the DAYS field as an integer value, or 0 if not present. |
| public Number | Returns: If the specified field is present, this method returns a non-null non-negativeNumber 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.one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
MINUTES, or SECONDS.) fieldImplements abstract javax. Gets the value of a field. |
| private BigDecimal | Returns: non-null validBigDecimal.Field to get value for. fGets the value of the field as a |
| public int | Returns: Hours of thisDuration.Overrides javax. Obtains the value of the HOURS field as an integer value, or 0 if not present. |
| private int | Returns: int value of field or 0 if field is not set.To get value for. fieldReturn the requested field value as an int. |
| public int | Returns: Minutes of thisDuration.Overrides javax. Obtains the value of the MINUTES field as an integer value, or 0 if not present. |
| public int | Returns: Months of thisDuration.Overrides javax. Obtains the value of the MONTHS field as an integer value, or 0 if not present. |
| public int | 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)Overrides javax. Obtains the value of the SECONDS field as an integer value, or 0 if not present. |
| public int | Returns: -1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is postive.Implements abstract javax. Returns the sign of this duration in -1,0, or 1. |
| public long | Returns: milliseconds betweenstartInstant and
startInstant plus this DurationThe length of a month/year varies. The startInstant)startInstant is
used to disambiguate this variance. Specifically, this method
returns the difference between startInstant and
startInstant+durationOverrides javax. Returns the length of the duration in milli-seconds. |
| public long | Returns: milliseconds betweenstartInstant and
startInstant plus this DurationThe length of a month/year varies. The startInstant)startInstant is
used to disambiguate this variance. Specifically, this method
returns the difference between startInstant and
startInstant+duration.Overrides javax. Returns the length of the duration in milli-seconds. |
| public int | Returns: If the YEARS field is present, return its value as an integer by using theNumber#intValue()
method. If the YEARS field is not present, return 0.Overrides javax. Obtains the value of the YEARS field as an integer value, or 0 if not present. |
| public int | hashCode()
Implements abstract javax. Returns a hash code consistent with the definition of the equals method. |
| private static boolean | |
| private static boolean | |
| public boolean | Returns: true if the field is present. false if not.one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
MINUTES, or SECONDS.) fieldImplements abstract javax. Checks if a field is set. |
| public Duration | Returns: NewDuration that is factortimes longer than this Duration.Factor times longer of new factor)Duration to create.Overrides javax. Computes a new duration whose value is |
| public Duration | Returns: returns a non-null validDuration objectto multiply by factor)Implements abstract javax. Computes a new duration whose value is |
| public Duration | Returns: always return a non-null validDuration object.Implements abstract javax. Returns a new |
| public Duration | Returns: Duration of years and months of this Duration as days.Calendar reference point.Implements abstract javax. Converts the years and months fields into the days field by using a specific time instant as the reference point. |
| private static void | organizeParts(String
Todo ??? Todo ??? Todo ??? Todo ??? Todo ??? Todo Javadoc. |
| private static BigDecimal | Returns: Todo ???. Todo ???. Todo ???. Todo ???. Todo Javadoc. |
| private static BigInteger | Returns: Todo ???. Todo ???. Todo ???. Todo ???. Todo Javadoc |
| private static String | |
| private static BigDecimal | Returns: non-nullBigDecimal.Value to sanitize. value, int 0 to sanitize to 0, > 0 to sanitize to signum)value, < 0 to sanitize to negative value.Compute |
| pack-priv static BigDecimal | Returns: non-nullBigDecimal.Value to sanitize. value, int 0 to sanitize to 0, > 0 to sanitize to signum)value, < 0 to sanitize to negative value.Compute |
| public int | Returns: -1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is postive.Returns the sign of this duration in -1,0, or 1. |
| public Duration | Returns: NewDuration created from subtracting rhs from this Duration.Duration to substract from this Duration.Overrides javax. Computes a new duration whose value is |
| protected static void | testNonNegative(BigInteger
Number to test. n, DatatypeConstants.Field to test. fMakes sure that the given number is non-negative. |
| protected static void | testNonNegative(BigDecimal
Number to test. n, DatatypeConstants.Field to test. fMakes sure that the given number is non-negative. |
| private static BigInteger | Returns: BigInteger value of BigDecimal, possibly null.Value to convert. value, boolean Can returned value be null? canBeNull)BigInteger value of BigDecimal value. |
| public String | Returns: Always return a non-null valid String object.Overrides javax. Returns a string representation of this duration object. |
| private String | Returns: String representation of BigDecimalBigDecimal to format as a StringHides javax. Turns |
| protected static BigInteger | Returns: BigInteger representation of int.int to convert to BigInteger. i)Todo Javadoc |
| private Object | Returns: An object that encapsulates the string returned bythis.toString().Writes |