javax.xml.datatype
Class Duration

java.lang.Object
  javax.xml.datatype.Duration

All Implemented Interfaces:

Serializable

public class Duration

extends Object

implements Serializable

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

Since:

1.5

See Also:

XMLGregorianCalendar.add(Duration), Serialized Form

Nested Class Summary
static class	Duration.Field           Type-safe enum class that represents six fields of the Duration class.

 

Field Summary
static Duration.Field	DAYS           A constant that represents the days field.
static int	EQUAL           Partial order relation comparison result.
static int	GREATER           Partial order relation comparison result.
static Duration.Field	HOURS           A constant that represents the hours field.
static int	INDETERMINATE           Partial order relation comparison result.
static int	LESSER           Partial order relation comparison result.
static Duration.Field	MINUTES           A constant that represents the minutes field.
static Duration.Field	MONTHS           A constant that represents the months field.
static Duration.Field	SECONDS           A constant that represents the seconds field.
static Duration.Field	YEARS           A constant that represents the years field.

 

Constructor Summary
Duration(boolean isPositive, BigInteger years, BigInteger months, BigInteger days, BigInteger hours, BigInteger minutes, BigDecimal seconds)           Constructs a new Duration object by specifying each field individually.
Duration(boolean isPositive, int years, int months, int days, int hours, int minutes, int seconds)           Constructs a new Duration object by specifying each field individually.
Duration(long durationInMilliSeconds)           Constructs a new Duration object by specifying the duration in milliseconds.
Duration(String lexicalRepresentation)           Constructs a new Duration object by parsing its string representation "PnYnMnDTnHnMnS" as defined in XML Schema 1.0 section 3.2.6.1.

 

Method Summary
Duration	add(Duration rhs)           Computes a new duration whose value is this+rhs.
void	addTo(Calendar calendar)           Adds this duration to a Calendar object.
void	addTo(Date date)           Adds this duration to a Date object.
static int	compare(Duration lhs, Duration rhs)           Partial order relation comparison between two Duration instances.
boolean	equals(Object rhs)           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.
Number	getField(Duration.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.
long	getTimeInMillis(Calendar startInstant)           Returns the length of the duration in milli-seconds.
long	getTimeInMillis(Date startInstant)           Returns the length of the duration in milli-seconds.
int	getYears()           Obtains the value of the YEARS field as an integer value, or 0 if not present.
int	hashCode()           Returns a hash code consistent with the definition of the equals method.
boolean	isLongerThan(Duration rhs)           Checks if this duration object is strictly longer than another Duration object.
boolean	isSet(Duration.Field field)           Checks if a field is set.
boolean	isShorterThan(Duration rhs)           Checks if this duration object is strictly shorter than another Duration object.
Duration	multiply(BigDecimal factor)           Computes a new duration whose value is factor times longer than the value of this duration.
Duration	multiply(int factor)           Computes a new duration whose value is factor times longer than the value of this duration.
Duration	negate()           Returns a new Duration object whose value is -this.
Duration	normalizeWith(Calendar startTimeInstant)           Converts the years and months fields into the days field by using a specific time instant as the reference point.
int	signum()           Returns the sign of this duration in -1,0, or 1.
Duration	subtract(Duration rhs)           Computes a new duration whose value is this-rhs.
String	toString()           Returns a string representation of this duration object.

 

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

 

Field Detail

LESSER

public static final int LESSER

Partial order relation comparison result.

See Also:

compare(Duration, Duration), Constant Field Values

EQUAL

public static final int EQUAL

Partial order relation comparison result.

See Also:

compare(Duration, Duration), Constant Field Values

GREATER

public static final int GREATER

Partial order relation comparison result.

See Also:

compare(Duration, Duration), Constant Field Values

INDETERMINATE

public static final int INDETERMINATE

Partial order relation comparison result.

See Also:

compare(Duration, Duration), Constant Field Values

YEARS

public static final Duration.Field YEARS

A constant that represents the years field.

MONTHS

public static final Duration.Field MONTHS

A constant that represents the months field.

DAYS

public static final Duration.Field DAYS

A constant that represents the days field.

HOURS

public static final Duration.Field HOURS

A constant that represents the hours field.

MINUTES

public static final Duration.Field MINUTES

A constant that represents the minutes field.

SECONDS

public static final Duration.Field SECONDS

A constant that represents the seconds field.

Duration

public Duration(boolean isPositive,
                BigInteger years,
                BigInteger months,
                BigInteger days,
                BigInteger hours,
                BigInteger minutes,
                BigDecimal seconds)

Constructs a new Duration object by specifying each field individually.

All the parameters are optional as long as at least one field is present. If specified, parameters have to be zero or positive.

Parameters:

isPositive - Set to false to create a negative duration. When the length of the duration is zero, this parameter will be ignored.

years - of this Duration

months - of this Duration

days - of this Duration

hours - of this Duration

minutes - of this Duration

seconds - of this Duration

Throws:

IllegalArgumentException - If years, months, days, hours, minutes and seconds parameters are all null. Or if any of those parameters are negative.

Duration

public Duration(boolean isPositive,
                int years,
                int months,
                int days,
                int hours,
                int minutes,
                int seconds)

Constructs a new Duration object by specifying each field individually.

This method is functionally equivalent to invoking another constructor by wrapping all non-zero parameters into BigInteger and BigDecimal. Zero value of int parameter is equivalent of null value of the corresponding field.

See Also:

Duration(boolean, BigInteger, BigInteger, BigInteger, BigInteger, BigInteger, BigDecimal)

Duration

public Duration(long durationInMilliSeconds)

Constructs a new Duration object by specifying the duration in milliseconds.

The DAYS, HOURS, MINUTES and SECONDS fields are used to represent the specifed duration in a reasonable way. That is, the constructed object x satisfies the following conditions:

• x.getHours()<24
• x.getMinutes()<60
• x.getSeconds()<60

Parameters:

durationInMilliSeconds - The length of the duration in milliseconds.

Duration

public Duration(String lexicalRepresentation)
         throws IllegalArgumentException

Constructs a new Duration object by parsing its string representation "PnYnMnDTnHnMnS" as defined in XML Schema 1.0 section 3.2.6.1.

The string representation may not have any leading and trailing whitespaces.

For example, this method parses strings like "P1D" (1 day), "-PT100S" (-100 sec.), "P1DT12H" (1 days and 12 hours).

The parsing is done field by field so that the following holds for any lexically correct string x:

 new Duration(x).toString().equals(x)
 

Returns a non-null valid duration object that holds the value indicated by the lexicalRepresentation parameter.

Parameters:

lexicalRepresentation - Lexical representation of a duration.

Throws:

IllegalArgumentException - If the given string does not conform to the aforementioned specification.

NullPointerException - If the given string is null.

compare

public static int compare(Duration lhs,
                          Duration rhs)

Partial order relation comparison between two Duration instances.

Comparison result must be in accordance with W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration.

Parameters:

lhs - instance of Duration to compare

rhs - instance of Duration to compare

Returns:

the relationship between lhs and rhs as LESSER, EQUAL, GREATER or INDETERMINATE.

Throws:

NullPointerException - if lhs or rhs parameters are null.

See Also:

isShorterThan(Duration), isLongerThan(Duration)

isLongerThan

public final boolean isLongerThan(Duration rhs)

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:

rhs - A non-null valid Duration instance.

Returns:

true if the duration represented by this object is longer than the given duration. false otherwise.

Throws:

NullPointerException - if the rhs parameter is null.

See Also:

isShorterThan(Duration), compare(Duration, Duration)

isShorterThan

public final boolean isShorterThan(Duration rhs)

Checks if this duration object is strictly shorter than another Duration object.

This method is really just a convenience method of rhs.isLongerThan(this).

Parameters:

rhs - Duration to test this Duration against.

Returns:

true if Duration parameter is shorter than this Duration, else false.

Throws:

NullPointerException - if parameter is null.

See Also:

isLongerThan(Duration), compare(Duration, Duration)

equals

public final boolean equals(Object rhs)

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,

 !new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))
 

Overrides:

equals in class Object

Parameters:

rhs - A non-null valid Duration object.

Returns:

true if this duration is the same length as rhs. false if rhs is not a Duration object or its length is different from this duration.

Throws:

NullPointerException - if parameter is null.

See Also:

compare(Duration, Duration)

hashCode

public int hashCode()

Returns a hash code consistent with the definition of the equals method.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

See Also:

Object.hashCode()

toString

public String toString()

Returns a string representation of this duration object.

The result is formatter according to the XML Schema 1.0 spec and can be always parsed back later into the equivalent duration object by the Duration(String) constructor.

Formally, the following holds for any Duration object x.

 new Duration(x.toString()).equals(x)
 

Overrides:

toString in class Object

Returns:

Always return a non-null valid String object.

isSet

public boolean isSet(Duration.Field field)

Checks if a field is set. A field of a duration object may or may not be present. This method can be used to test if a field is present.

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.

getField

public Number getField(Duration.Field field)

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.

Throws:

NullPointerException - If the field parameter is null.

getYears

public int getYears()

Obtains the value of the YEARS field as an integer value, or 0 if not present.

This method is a convenience method around the getField(Duration.Field) method.

Note that since this method returns int, this method will return an incorrect value for Durations with the year field that goes beyond the range of int. Use getField(YEARS) to avoid possible loss of precision.

Returns:

If the YEARS field is present, return its value as an integer by using the Number.intValue() method. If the YEARS field is not present, 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 final 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 incorectly 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

Throws:

NullPointerException - if startInstant parameter is null.

public final long getTimeInMillis(Date startInstant)

public Duration normalizeWith(Calendar startTimeInstant)

public Duration multiply(int factor)

public final Duration multiply(BigDecimal factor)

public final Duration add(Duration rhs)

public final Duration subtract(Duration rhs)

public Duration negate()

public int signum()

public void addTo(Calendar calendar)

public void addTo(Date date)