Duration (Java 2 Platform SE 5.0) - JDK 5 Documentation v1.5.0, Java 2 SDK 英文文档

getField

public abstract Number getField(DatatypeConstants.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 is null.

isSet

public abstract boolean isSet(DatatypeConstants.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.

add

public abstract Duration add(Duration rhs)

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

Formally, the computation is defined as follows.

Firstly, we can assume that two Durations 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 Durations 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 Durations 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(Duration)

addTo

public abstract void addTo(Calendar calendar)

Adds this duration to a Calendar object.

Calls Calendar.add(int,int) in the order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS if those fields are present. Because the 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 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 using int, Duration with values beyond the range of int in its fields will cause overflow/underflow to the given Calendar. 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.

addTo

public void addTo(Date date)

Adds this duration to a Date object.

The given date is first converted into a GregorianCalendar, then the duration is added exactly like the addTo(Calendar) method.

The updated time instant is then converted back into a Date object and used to update the given 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.

subtract

public Duration subtract(Duration rhs)

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

Formally the computation is defined as follows. First, we can assume that two Durations 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 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(Duration)

multiply

public Duration multiply(int factor)

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 factortimes longer than this Duration.

See Also:

multiply(BigDecimal)

multiply

public abstract Duration multiply(BigDecimal factor)

Computes a new duration whose value is 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 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 IllegalStateException to be thrown. For example if you multiple one month by 0.5.

To avoid IllegalStateException, use the 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.

negate

public abstract Duration negate()

Returns a new 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.

normalizeWith

public 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:

1. the given Calendar object is cloned
2. the years, months and days fields will be added to the Calendar object by using the Calendar.add(int,int) method
3. the difference between the two Calendars in computed in milliseconds and converted to days, if a remainder occurs due to Daylight Savings Time, it is discarded
4. the computed days, along with the hours, minutes and seconds fields of this duration object is used to construct a new Duration object.

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.

compare

public abstract int compare(Duration duration)

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:

• DatatypeConstants.LESSER if this Duration is shorter than duration parameter
• DatatypeConstants.EQUAL if this Duration is equal to duration parameter
• DatatypeConstants.GREATER if this Duration is longer than duration parameter
• DatatypeConstants.INDETERMINATE if a conclusive partial order relation cannot be determined

Parameters:

duration - to compare

Returns:

the relationship between this Durationand duration parameter as DatatypeConstants.LESSER, DatatypeConstants.EQUAL, DatatypeConstants.GREATER or 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(Duration), isLongerThan(Duration)

isLongerThan

public boolean isLongerThan(Duration duration)

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), compare(Duration duration)

isShorterThan

public boolean isShorterThan(Duration duration)

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.

See Also:

isLongerThan(Duration duration), compare(Duration duration)

equals

public boolean equals(Object duration)

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:

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:

compare(Duration duration)

hashCode

public abstract 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 formatted according to the XML Schema 1.0 spec and can be always parsed back later into the equivalent Duration Object by DatatypeFactory.newDuration(String lexicalRepresentation).

Formally, the following holds for any Duration Object x:

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

Overrides:

toString in class Object

Returns:

A non-null valid String representation of this Duration.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.