TopBlend: Here is the first difference. There are 381 differences. is old. is new.

javax.xml.datatype
Class Duration


java.lang.Object
  extended by javax.xml.datatype.Duration
All Implemented Interfaces:
Serializable 
public abstract 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) compare(Duration, Duration) method implements this relationship.

See the isLongerThan(Duration) method for details about the order relationship among Duration 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 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 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. Duration s. 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
 
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 ()
           
Duration (boolean isPositive, BigInteger  years, BigInteger  months, BigInteger  days, BigInteger  hours, BigInteger  minutes, BigDecimal
          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
          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
abstract   Duration add ( Duration
          Computes a new duration whose value is this+rhs.
abstract  void addTo ( Calendar
          Adds this duration to a Calendar
 void addTo ( Date  date)
          Adds this duration to a Date object.
abstract  int static int compare compare ( Duration  lhs, Duration
          Partial order relation comparison with this between two Duration instance. instances.
 boolean equals ( Object
          Checks if this duration object has the same duration as another Duration object. Duration
 int getDays ()
          Obtains the value of the DAYS field as an integer value, or 0 if not present.
abstract   Number getField getField ( DatatypeConstants.Field Duration.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 milli-seconds.
 long getTimeInMillis ( Date  startInstant)
          Returns the length of the duration in milli-seconds.
abstract   QName getXMLSchemaType ()
          Return the name of the XML Schema date/time type that this instance maps to.
 int getYears ()
          Obtains the value of the YEARS field as an integer value, or 0 if not present.
 int getYears hashCode ()
          Get           Returns a hash code consistent with the years value definition of this Duration as an int or 0 if not present. the equals method.
abstract  int hashCode ()
          Returns a hash code consistent with the definition of the equals method.
 boolean isLongerThan ( Duration
          Checks if this duration object is strictly longer than another Duration
 boolean isLongerThan isSet ( Duration Duration.Field
          Checks if this duration object a field is strictly longer than another Duration object. set.
abstract  boolean isSet isShorterThan ( DatatypeConstants.Field Duration
          Checks if a field this duration object is set. strictly shorter than another Duration
 boolean isShorterThan ( Duration
          Checks if this duration object is strictly shorter than another Duration object.
  Duration multiply ( BigDecimal
          Computes a new duration whose value is factor times longer than the value of this duration.
abstract   Duration multiply multiply ( BigDecimal (int factor)
          Computes a new duration whose value is factor times longer than the value of this duration.
  Duration multiply negate (int factor) ()
          Computes           Returns a new duration whose value is factor times longer than the value of this duration. Duration
abstract   Duration negate ()
          Returns a new Duration object whose value is -this.
  Duration normalizeWith ( Calendar
          Converts the years and months fields into the days field by using a specific time instant as the reference point.
abstract   Duration normalizeWith ( Calendar
          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.
abstract   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
 

Constructor Field Detail

Duration LESSER 


public 
public static final int Duration LESSER ()
Partial order relation comparison result.

See Also:
compare(Duration, Duration) , Constant Field Values
Method Detail

getXMLSchemaType EQUAL 


public abstract QName
public static final int getXMLSchemaType EQUAL ()
Partial order relation comparison result.

Return the name of the XML Schema date/time type that this instance maps to. Type is computed based on fields that are set, i.e. isSet(DatatypeConstants.Field field) == true.

Required fields for XML Schema 1.0 Date/Time Datatypes.
(timezone is optional for all date/time datatypes)
Datatype year month day hour minute second
DatatypeConstants.DURATION X X X X X X
DatatypeConstants.DURATION_DAYTIME X X X X
DatatypeConstants.DURATION_YEARMONTH X X

Returns: See Also:
one of the following constants: DatatypeConstants.DURATION compare(Duration, Duration) , DatatypeConstants.DURATION_DAYTIME Constant Field Values or DatatypeConstants.DURATION_YEARMONTH
.

GREATER 


public static final int GREATER
Partial order relation comparison result.

Throws: See Also:
IllegalStateException compare(Duration, Duration) - If the combination of set fields does not match one of the XML Schema date/time datatypes. , Constant Field Values

getSign INDETERMINATE 

public abstract static final int getSign INDETERMINATE ()
Returns the sign of this duration in -1,0, or 1. Partial order relation comparison result.

Returns: See Also:
-1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is postive. compare(Duration, Duration) , Constant Field Values

getYears YEARS 


public int 
public static final Duration.FieldgetYears YEARS ()

Get the years value of this Duration as an int or 0 if not present. A constant that represents the years field.

getYears() is a convenience method for getField(DatatypeConstants.YEARS)

.

MONTHS 


public static final Duration.FieldMONTHS

As the return value is an int, an incorrect value will be returned for Durations with years that go beyond the range of an int. Use getField(DatatypeConstants.YEARS) to avoid possible loss of precision. A constant that represents the months field.

DAYS 


public static final Duration.FieldReturns: DAYS
If the years field is present, return its value as an int, else return 0.

A constant that represents the days field.

getMonths HOURS 


public int 
public static final Duration.FieldgetMonths HOURS ()
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.

A constant that represents the hours field.

MINUTES 


public static final Duration.FieldReturns: MINUTES
Months of this Duration.

A constant that represents the minutes field.

getDays SECONDS 


public int 
public static final Duration.FieldgetDays SECONDS ()
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.

A constant that represents the seconds field.

Returns:
Days of this Duration.
Constructor Detail

getHours Duration 

public int getHours Duration () (boolean isPositive,
 BigInteger years,
 BigInteger months,
 BigInteger days,
 BigInteger hours,
 BigInteger minutes,
 BigDecimal seconds)
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.

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
Returns: Throws:
Hours of this Duration. IllegalArgumentException - If years, months, days, hours, minutes and seconds parameters are all null. Or if any of those parameters are negative.

getMinutes Duration 

public int getMinutes Duration () (boolean isPositive,
 int years,
 int months,
 int days,
 int hours,
 int minutes,
 int seconds)
Obtains the value of the MINUTES field as an integer value, or 0 if not present. This method works just like getYears()

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 except that this method works on the MINUTES field. and BigDecimal . Zero value of int parameter is equivalent of null value of the corresponding field.

Returns: See Also:
Minutes of this Duration. Duration(boolean, BigInteger, BigInteger, BigInteger, BigInteger, BigInteger, BigDecimal)

getSeconds Duration 

public int getSeconds Duration () (long durationInMilliSeconds)
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.

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

Returns: Parameters:
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) durationInMilliSeconds - The length of the duration in milliseconds.

getTimeInMillis Duration 

public long getTimeInMillis Duration ( CalendarString startInstant)  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.

Returns the length of the duration in milli-seconds.

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

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,

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("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.
 
 new Duration(x).toString().equals(x)
Returns a non-null valid duration object that holds the value indicated by the lexicalRepresentation parameter.

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 lexicalRepresentation - Lexical representation of a duration.
Returns: Throws:
milliseconds between startInstant and startInstant plus this Duration
Throws: IllegalArgumentException - If the given string does not conform to the aforementioned specification.
NullPointerException - if startInstant parameter is null. - If the given string is null.
Method Detail

getTimeInMillis compare 


public long 
public static int getTimeInMillis compare ( DateDuration startInstant)  lhs,
 Duration rhs)

Returns the length of the duration in milli-seconds. Partial order relation comparison between two Duration instances.

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 Date value x, Comparison result must be in accordance with W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration . 


 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.

Note that this method uses the addTo(Date) method, which may work incorectly with Duration objects with very large values in its fields. See the addTo(Date) 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. lhs - instance of Duration to compare
rhs - instance of Duration to compare
Returns:
milliseconds between startInstant and startInstant plus this Duration the relationship between lhs and rhs as LESSER , EQUAL , GREATER or INDETERMINATE .
Throws:
NullPointerException - If the startInstant parameter is null. - if lhs or rhs parameters are null.
See Also:
getTimeInMillis(Calendar) isShorterThan(Duration) , isLongerThan(Duration)

getField isLongerThan 


public abstract Number
public final boolean getField isLongerThan ( DatatypeConstants.FieldDuration field)  rhs)
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

Checks if this duration object is strictly longer than another Duration 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.

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:
field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.) rhs - A non-null valid Duration instance.
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 . true if the duration represented by this object is longer than the given duration. false otherwise.
Throws:
NullPointerException - If the field is null. - if the rhs parameter is null.
See Also:
isShorterThan(Duration) , compare(Duration, Duration)

isSet isShorterThan 

public abstract final boolean isSet isShorterThan ( DatatypeConstants.FieldDuration field)  rhs)
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.

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:
field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.) rhs - Duration to test this Duration against.
Returns:
true if the field is present. false if not. true if Duration parameter is shorter than this Duration, else false.
Throws:
NullPointerException - If the field parameter is null. - if parameter is null.
See Also:
isLongerThan(Duration) , compare(Duration, Duration)

add equals 


public abstract Duration
public final boolean add equals ( DurationObject rhs)

Computes a new duration whose value is this+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 Duration s are "incomparable" to each other, like one month and 30 days. 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
 
 !new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in IllegalStateException

Overrides:
equals .

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.

in class Object

Parameters:
rhs - Duration to add to this Duration rhs - A non-null valid Duration object.
Returns:
non-null valid Duration object. 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 the rhs parameter is null. - if parameter is null.
See Also:
IllegalStateException compare(Duration, Duration) - If two durations cannot be meaningfully added. For example, adding negative one day to one month causes this exception.

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:
subtract(Duration) Object.hashCode()

addTo toString 


public abstract void 
public StringaddTo toString ( Calendar calendar) ()
Adds this duration to a Calendar object. Returns a string representation of this duration object.

Calls Calendar.add(int,int) 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) 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.)

constructor.

Also, since this duration class is a Gregorian duration, this method will not work correctly if the given Calendar Formally, the following holds for any Duration object is based on some other calendar systems. object x. 


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

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)

Overrides:
toString is using int , Duration with values beyond the range of int in its fields will cause overflow/underflow to the given Calendar in class Object . XMLGregorianCalendar.add(Duration)
Returns:
Always return a non-null valid String object.
provides the same basic operation as this method while avoiding the overflow/underflow issues.

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:
calendar - A calendar object whose value will be modified. 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 If the calendar field parameter is null.

addTo getField 


public void 
public NumberaddTo getField ( DateDuration.Field date)  field)
Adds this duration to a Date 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 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. 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 If the date field parameter is null.

subtract getYears 


public Duration
public int subtract getYears ( Duration rhs) ()
Obtains the value of the YEARS field as an integer value, or 0 if not present.

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 This method is a convenience method around the getField(Duration.Field) .

method.

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 Note that since this method returns F int is different from the sign of the most significant field, 1 (if , this method will return an incorrect value for Duration s with the year field that goes beyond the range of F int is negative) or -1 (otherwise) will be borrowed from the next bigger unit of F . Use getField(YEARS) to avoid possible loss of precision.

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: Returns:
rhs - Duration to substract from this Duration. 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:
New Duration created from subtracting rhs from this Duration.
Months of this Duration.

getDays 


public int Throws: getDays ()
IllegalStateException Obtains the value of the DAYS field as an integer value, or 0 if not present. This method works just like getYears() - If two durations cannot be meaningfully subtracted. For example, subtracting one day from one month causes this exception. except that this method works on the DAYS field.

NullPointerException - If the rhs parameter is null.
See Also: Returns:
add(Duration) Days of this Duration.

multiply getHours 


public Duration
public int multiply getHours (int factor) ()
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.

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:

Returns:
Hours of this Duration.

getMinutes 


 multiply(new BigDecimal(String.valueOf(factor)))
 
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.

Parameters: Returns:
factor - Factor times longer of new Duration to create.
Minutes of this Duration.

getSeconds 


public int Returns: getSeconds ()
New Duration that is factortimes longer than this Duration. 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.

See Also: Returns:
multiply(BigDecimal) 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)

multiply getTimeInMillis 


public abstract Duration
public final long multiply getTimeInMillis ( BigDecimalCalendar factor)  startInstant)
Computes a new duration whose value is factor times longer than the value of this duration.

For example, 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, 


 "P1M" (1 month) * "12" = "P12M" (12 months)
 "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
 "P1M" (1 month) * "1.5" = IllegalStateException
 
 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.

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 Note that this method uses the addTo(Calendar) . 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 method, which may work incorectly with Duration to be thrown. For example if you multiple one month by 0.5.

To avoid IllegalStateException objects with very large values in its fields. See the addTo(Calendar) , use the normalizeWith(Calendar) method to remove the years and months fields. method for details.

Parameters:
factor - to multiply by 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:
returns a non-null valid Duration object milliseconds between startInstant and startInstant plus this Duration
Throws:
IllegalStateException - if operation produces fraction in the months field.
NullPointerException - if the factor startInstant parameter is null.

negate getTimeInMillis 


public abstract Duration
public final long negate getTimeInMillis () ( Date startInstant)
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 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 Date value x, 


 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.

Note that this method uses the addTo(Date) method, which may work incorectly with Duration objects with very large values in its fields. See the addTo(Date) 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:
always return a non-null valid Duration object. milliseconds between startInstant and startInstant plus this Duration
Throws:
NullPointerException - If the startInstant parameter is null.
See Also:
getTimeInMillis(Calendar)

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 The given Calendar object is cloned
    2. cloned.
  2. the The years, months and days fields will be added to the Calendar object by using the Calendar.add(int,int)
    3. method.
  3. the The difference between the two Calendars in are computed in milliseconds and converted to days, if a remainder occurs due to Daylight Savings Time, it is discarded
    4. terms of days.
  4. the 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 multiply 


public abstract int 
public Durationcompare multiply ( Duration duration) (int factor)

Partial order relation comparison with this Duration instance. Computes a new duration whose value is factor times longer than the value of this duration.

Comparison result must be in accordance with W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration . This method is provided for the convenience. It is functionally equivalent to the following code: 


 multiply(new BigDecimal(String.valueOf(factor)))

Return:

Parameters:
duration - to compare factor - Factor times longer of new Duration to create.
Returns:
the relationship between this Durationand duration parameter as DatatypeConstants.LESSER , DatatypeConstants.EQUAL , DatatypeConstants.GREATER or DatatypeConstants.INDETERMINATE . New Duration that is factortimes longer than this Duration.
Throws:
NullPointerException - if duration is null.
See Also:
isShorterThan(Duration) multiply(BigDecimal) , isLongerThan(Duration)

isLongerThan multiply 


public boolean 
public final DurationisLongerThan multiply ( DurationBigDecimal duration)  factor)
Computes a new duration whose value is factor times longer than the value of this duration.

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

For example, 

 "P1M" (1 month) * "12" = "P12M" (12 months)
 "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
 "P1M" (1 month) * "1.5" = IllegalStateException

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

For example, "P1D" (one day) > "PT12H" (12 hours) and "P2Y" (two years) > "P23M" (23 months).

To avoid IllegalStateException , use the normalizeWith(Calendar) method to remove the years and months fields.

Parameters:
duration - Duration to test this Duration against. factor - to multiply by
Returns:
true if the duration represented by this object is longer than the given duration. false otherwise. returns a non-null valid Duration object
Throws:
NullPointerException IllegalStateException - if duration is null.
See Also: - if operation produces fraction in the months field.
isShorterThan(Duration) NullPointerException , compare(Duration duration) - if the factor parameter is null.

isShorterThan add 


public boolean 
public final DurationisShorterThan add (Duration duration)  rhs)

Checks if this duration object is strictly shorter than another Duration object. 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 Duration s 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 Duration s 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 Duration s are unset.

Note that lhs.add(rhs) will be always successful if lhs.signum()*rhs.signum()!=-1 or both of them are normalized.

Parameters:
duration rhs - Duration to test add to this Duration against.
Returns:
true if duration parameter is shorter than this Duration, else false. non-null valid Duration object.
Throws:
NullPointerException - if duration is null. - 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:
isLongerThan(Duration duration) subtract(Duration) , compare(Duration duration)

equals subtract 


public boolean 
public final Durationequals subtract ( ObjectDuration duration)  rhs)

Checks if this duration object has the same duration as another Duration object. Computes a new duration whose value is this-rhs.

For example, "P1D" (1 day) is equal to "PT24H" (24 hours). 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"

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. Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in IllegalStateException .

Note that there are cases where two Durations are "incomparable" to each other, like one month and 30 days. For example, Formally the computation is defined as follows. First, we can assume that two Duration s are both positive without losing generality. (i.e., (-X)-Y=-(X+Y), X-(-Y)=X+Y, (-X)-(-Y)=-(X-Y)) 


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

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 .

Overrides:
equals in class Object
Parameters:
duration - A non-null valid Duration object. rhs - Duration to substract from this Duration.
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. 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 If the rhs parameter is null.
See Also:
compare(Duration duration) add(Duration)

hashCode negate 


public abstract int 
public DurationhashCode negate ()
Returns a hash code consistent with the definition of the equals method. 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.

Overrides: Returns:
hashCode always return a non-null valid Duration in class Object object.

signum 


public int signum ()
Returns the sign of this duration in -1,0, or 1.

Returns:
a hash code value for this object.
See Also:
Object.hashCode() -1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is postive.

toString addTo 


public abstract String
public void toString addTo () ( Calendar calendar)
Adds this duration to a Calendar object.

Returns a string representation of this duration 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.)

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

Formally, the following holds for any Duration object x: 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. 


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

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.

Overrides:
toString in class Object
Returns:
A non-null valid String representation of this Duration.
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.