Duration

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.

Order relationship

Duration objects only have partial order, where two values A and B maybe either:

  1. A<B (A is shorter than B)
  2. A>B (A is longer than B)
  3. A==B (A and B are of the same duration)
  4. A<>B (Comparison between A and B is indeterminate)

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.

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.

See Also

Public Constructor Summary

Public Method Summary

abstract Duration
add(Duration rhs)

Computes a new duration whose value is this+rhs.

abstract void
addTo(Calendar calendar)
Adds this duration to a Calendar object.
void
addTo(Date date)
Adds this duration to a Date object.
abstract int
compare(Duration duration)

Partial order relation comparison with this Duration instance.

boolean
equals(Object duration)

Checks if this duration object has the same duration as another Duration object.

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 milliseconds.

long
getTimeInMillis(Date startInstant)

Returns the length of the duration in milliseconds.

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 Duration as an int or 0 if not present.

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 object.

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 object.

Duration
multiply(int factor)

Computes a new duration whose value is factor times longer than the value of this duration.

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.

Duration
subtract(Duration rhs)

Computes a new duration whose value is this-rhs.

String
toString()

Returns a String representation of this Duration Object.

Inherited Method Summary