http://xml.apache.org/commons/components/external/: xml-commons provides an Apache-hosted set of DOM, SAX, and JAXP interfaces for use in other xml-based projects. Our hope is that we can standardize on both a common version and packaging scheme for these critical XML standards interfaces to make the lives of both our developers and users easier. The External Components portion of xml-commons contains interfaces that are defined by external standards organizations. For DOM, that's the W3C; for SAX it's David Megginson and sax.sourceforge.net; for JAXP it's Sun. 
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

//$Id: Duration.java 759828 2009-03-30 01:26:29Z mrglavas $

package javax.xml.datatype;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;

import javax.xml.namespace.QName;


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. 
Author:Joseph Fialli, Kohsuke Kawaguchi, Jeff Suttor
See Also:
Version:$Revision: 759828 $, $Date: 2009-03-29 21:26:29 -0400 (Sun, 29 Mar 2009) $
Since:1.5
/**
 * <p>Immutable representation of a time span as defined in
 * the W3C XML Schema 1.0 specification.</p>
 * 
 * <p>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.</p>
 * 
 * <p>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.</p> 
 * 
 * <p>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.</p>
 * 
 * <h2>Order relationship</h2>
 * <p>Duration objects only have partial order, where two values A and B
 * maybe either:</p>
 * <ol>
 *  <li>A&lt;B (A is shorter than B)
 *  <li>A&gt;B (A is longer than B)
 *  <li>A==B   (A and B are of the same duration)
 *  <li>A&lt;>B (Comparison between A and B is indeterminate)
 * </ol>
 *
 * <p>For example, 30 days cannot be meaningfully compared to one month.
 * The {@link #compare(Duration duration)} method implements this
 * relationship.</p>
 * 
 * <p>See the {@link #isLongerThan(Duration)} method for details about
 * the order relationship among <code>Duration</code> objects.</p>
 * 
 * <h2>Operations over Duration</h2>
 * <p>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.</p>
 * 
 * <p>Also, division of a duration by a number is not provided because
 * the <code>Duration</code> class can only deal with finite precision
 * decimal numbers. For example, one cannot represent 1 sec divided by 3.</p> 
 * 
 * <p>However, you could substitute a division by 3 with multiplying
 * by numbers such as 0.3 or 0.333.</p>
 * 
 * <h2>Range of allowed values</h2>
 * <p>
 * Because some operations of <code>Duration</code> rely on {@link Calendar}
 * even though {@link Duration} can hold very large or very small values,
 * some of the methods may not work correctly on such <code>Duration</code>s.
 * The impacted methods document their dependency on {@link Calendar}.
 * 
 *  
 * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
 * @version $Revision: 759828 $, $Date: 2009-03-29 21:26:29 -0400 (Sun, 29 Mar 2009) $    
 * @see XMLGregorianCalendar#add(Duration)
 * @since 1.5
 */
public abstract class Duration {

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

  



Throws:
  • IllegalStateException – If the combination of set fields does not match one of the XML Schema date/time datatypes.
Returns:one of the following constants: DatatypeConstants.DURATION, DatatypeConstants.DURATION_DAYTIME or DatatypeConstants.DURATION_YEARMONTH.
/**
     * <p>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. {@link #isSet(DatatypeConstants.Field field)} == <code>true</code>.</p>
     *
     * <table border="2" rules="all" cellpadding="2">
     *   <thead>
     *     <tr>
     *       <th align="center" colspan="7">
     *         Required fields for XML Schema 1.0 Date/Time Datatypes.<br/>
     *         <i>(timezone is optional for all date/time datatypes)</i>
     *       </th>
     *     </tr>
     *   </thead>
     *   <tbody>
     *     <tr>
     *       <td>Datatype</td>
     *       <td>year</td>
     *       <td>month</td>
     *       <td>day</td>
     *       <td>hour</td>
     *       <td>minute</td>
     *       <td>second</td>
     *     </tr>
     *     <tr>
     *       <td>{@link DatatypeConstants#DURATION}</td>
     *       <td>X</td>
     *       <td>X</td>
     *       <td>X</td>
     *       <td>X</td>
     *       <td>X</td>
     *       <td>X</td>
     *     </tr>
     *     <tr>
     *       <td>{@link DatatypeConstants#DURATION_DAYTIME}</td>
     *       <td></td>
     *       <td></td>
     *       <td>X</td>
     *       <td>X</td>
     *       <td>X</td>
     *       <td>X</td>
     *     </tr>
     *     <tr>
     *       <td>{@link DatatypeConstants#DURATION_YEARMONTH}</td>
     *       <td>X</td>
     *       <td>X</td>
     *       <td></td>
     *       <td></td>
     *       <td></td>
     *       <td></td>
     *     </tr>
     *   </tbody>
     * </table>
     * 
     * @return one of the following constants:
     *   {@link DatatypeConstants#DURATION},
     *   {@link DatatypeConstants#DURATION_DAYTIME} or
     *   {@link DatatypeConstants#DURATION_YEARMONTH}.
     *  
     * @throws IllegalStateException If the combination of set fields does not match one of the XML Schema date/time datatypes.
     */
    public QName getXMLSchemaType() {

        boolean yearSet = isSet(DatatypeConstants.YEARS);
        boolean monthSet = isSet(DatatypeConstants.MONTHS);
        boolean daySet = isSet(DatatypeConstants.DAYS);
        boolean hourSet = isSet(DatatypeConstants.HOURS);
        boolean minuteSet = isSet(DatatypeConstants.MINUTES);
        boolean secondSet = isSet(DatatypeConstants.SECONDS);

        // DURATION
        if (yearSet
                && monthSet
                && daySet
                && hourSet
                && minuteSet
                && secondSet) {
            return DatatypeConstants.DURATION;
        }

        // DURATION_DAYTIME
        if (!yearSet
                && !monthSet
                && daySet
                && hourSet
                && minuteSet
                && secondSet) {
            return DatatypeConstants.DURATION_DAYTIME;
        }

        // DURATION_YEARMONTH
        if (yearSet
                && monthSet
                && !daySet
                && !hourSet
                && !minuteSet
                && !secondSet) {
            return DatatypeConstants.DURATION_YEARMONTH;
        }

        // nothing matches
        throw new IllegalStateException(
                "javax.xml.datatype.Duration#getXMLSchemaType():"
                + " this Duration does not match one of the XML Schema date/time datatypes:"
                + " year set = " + yearSet
                + " month set = " + monthSet
                + " day set = " + daySet
                + " hour set = " + hourSet
                + " minute set = " + minuteSet
                + " second set = " + secondSet
        );
    }

    
Returns the sign of this duration in -1,0, or 1.

Returns:
     -1 if this duration is negative, 0 if the duration is zero,
     and 1 if the duration is positive.
/**
     * Returns the sign of this duration in -1,0, or 1.
     * 
     * @return

     *      -1 if this duration is negative, 0 if the duration is zero,
     *      and 1 if the duration is positive.
     */
    public abstract int getSign();

    
Get the years value of this Duration as an int or 0 if not present.


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


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.


Returns:If the years field is present, return its value as an int, else return 0.
/**
     * <p>Get the years value of this <code>Duration</code> as an <code>int</code> or <code>0</code> if not present.</p>
     * 
     * <p><code>getYears()</code> is a convenience method for
     * {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)}.</p>
     * 
     * <p>As the return value is an <code>int</code>, an incorrect value will be returned for <code>Duration</code>s
     * with years that go beyond the range of an <code>int</code>.
     * Use {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)} to avoid possible loss of precision.</p>
     * 
     * @return If the years field is present, return its value as an <code>int</code>, else return <code>0</code>.
     */
    public int getYears() {
        return getFieldValueAsInt(DatatypeConstants.YEARS);
    }

    
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.
/**
     * Obtains the value of the MONTHS field as an integer value,
     * or 0 if not present.
     * 
     * This method works just like {@link #getYears()} except
     * that this method works on the MONTHS field.
     * 
     * @return Months of this <code>Duration</code>.
     */
    public int getMonths() {
        return getFieldValueAsInt(DatatypeConstants.MONTHS);
    }

    
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.
/**
     * Obtains the value of the DAYS field as an integer value,
     * or 0 if not present.
     * 
     * This method works just like {@link #getYears()} except
     * that this method works on the DAYS field.
     * 
     * @return Days of this <code>Duration</code>.
     */
    public int getDays() {
        return getFieldValueAsInt(DatatypeConstants.DAYS);
    }

    
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.
/**
     * Obtains the value of the HOURS field as an integer value,
     * or 0 if not present.
     * 
     * This method works just like {@link #getYears()} except
     * that this method works on the HOURS field.
     * 
     * @return Hours of this <code>Duration</code>.
     * 
     */
    public int getHours() {
        return getFieldValueAsInt(DatatypeConstants.HOURS);
    }

    
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.
/**
     * Obtains the value of the MINUTES field as an integer value,
     * or 0 if not present.
     * 
     * This method works just like {@link #getYears()} except
     * that this method works on the MINUTES field.
     * 
     * @return Minutes of this <code>Duration</code>.
     * 
     */
    public int getMinutes() {
        return getFieldValueAsInt(DatatypeConstants.MINUTES);
    }

    
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)
/**
     * Obtains the value of the SECONDS field as an integer value,
     * or 0 if not present.
     * 
     * This method works just like {@link #getYears()} except
     * that this method works on the SECONDS field.
     * 
     * @return 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)
     */
    public int getSeconds() {
        return getFieldValueAsInt(DatatypeConstants.SECONDS);
    }

    
Returns the length of the duration in milliseconds.


If the seconds field carries more digits than millisecond 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 incorrectly with Duration objects with very large values in its fields. See the addTo(Calendar) method for details. 
Params:
  • 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
Throws:
Returns:milliseconds between startInstant and
  startInstant plus this Duration
/**
     * <p>Returns the length of the duration in milliseconds.</p>
     * 
     * <p>If the seconds field carries more digits than millisecond order,
     * those will be simply discarded (or in other words, rounded to zero.)  
     * For example, for any Calendar value <code>x</code>,</p>
     * <pre>
     * <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
     * <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
     * </pre>
     * 
     * <p>
     * Note that this method uses the {@link #addTo(Calendar)} method,
     * which may work incorrectly with <code>Duration</code> objects with
     * very large values in its fields. See the {@link #addTo(Calendar)}
     * method for details.
     * 
     * @param startInstant
     *      The length of a month/year varies. The <code>startInstant</code> is
     *      used to disambiguate this variance. Specifically, this method
     *      returns the difference between <code>startInstant</code> and
     *      <code>startInstant+duration</code>
     * 
     * @return milliseconds between <code>startInstant</code> and
     *   <code>startInstant</code> plus this <code>Duration</code>
     *
     * @throws NullPointerException if <code>startInstant</code> parameter 
     * is null.
     * 
     */
    public long getTimeInMillis(final Calendar startInstant) {
        Calendar cal = (Calendar) startInstant.clone();
        addTo(cal);
        return getCalendarTimeInMillis(cal)
        - getCalendarTimeInMillis(startInstant);
    }

    
Returns the length of the duration in milliseconds.


If the seconds field carries more digits than millisecond 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 incorrectly with Duration objects with very large values in its fields. See the addTo(Date) method for details. 
Params:
  • 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.
Throws:
See Also:
Returns:milliseconds between startInstant and
  startInstant plus this Duration
/**
     * <p>Returns the length of the duration in milliseconds.</p>
     * 
     * <p>If the seconds field carries more digits than millisecond order,
     * those will be simply discarded (or in other words, rounded to zero.)
     * For example, for any <code>Date</code> value <code>x</code>,</p>   
     * <pre>
     * <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
     * <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
     * </pre>
     * 
     * <p>
     * Note that this method uses the {@link #addTo(Date)} method,
     * which may work incorrectly with <code>Duration</code> objects with
     * very large values in its fields. See the {@link #addTo(Date)}
     * method for details.
     * 
     * @param startInstant
     *      The length of a month/year varies. The <code>startInstant</code> is
     *      used to disambiguate this variance. Specifically, this method
     *      returns the difference between <code>startInstant</code> and
     *      <code>startInstant+duration</code>.
     * 
     * @throws NullPointerException
     *      If the startInstant parameter is null.
     * 
     * @return milliseconds between <code>startInstant</code> and
     *   <code>startInstant</code> plus this <code>Duration</code>
     *
     * @see #getTimeInMillis(Calendar)
     */
    public long getTimeInMillis(final Date startInstant) {
        Calendar cal = new GregorianCalendar();
        cal.setTime(startInstant);
        this.addTo(cal);
        return getCalendarTimeInMillis(cal) - startInstant.getTime();
    }

    
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. 
Params:
  • field – 
     one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
     MINUTES, or SECONDS.)
Throws:
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.
/**
     * Gets the value of a field. 
     * 
     * Fields of a duration object may contain arbitrary large value.
     * Therefore this method is designed to return a {@link 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.
     * 
     * @param field
     *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
     *      MINUTES, or SECONDS.)
     * @return

     *      If the specified field is present, this method returns
     *      a non-null non-negative {@link Number} object that
     *      represents its value. If it is not present, return null.
     *      For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method
     *      returns a {@link java.math.BigInteger} object. For SECONDS, this
     *      method returns a {@link java.math.BigDecimal}. 
     * 
     * @throws NullPointerException If the <code>field</code> is <code>null</code>.
     */
    public abstract Number getField(final DatatypeConstants.Field field);
    
    
Gets the value of a field as an int.

Params:
  • field – 
     one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
     MINUTES, or SECONDS.)
Returns:
     If the field is present, return its value as an int, 
     else return 0.
/**
     * Gets the value of a field as an <code>int</code>.
     * 
     * @param field 
     *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
     *      MINUTES, or SECONDS.)
     * @return 
     *      If the field is present, return its value as an <code>int</code>, 
     *      else return <code>0</code>.
     */
    private int getFieldValueAsInt(final DatatypeConstants.Field field) {
        Number n = getField(field);
        if (n != null) {
            return n.intValue();
        }
        return 0;
    }

    
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.

Params:
  • field – 
     one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
     MINUTES, or SECONDS.)
Throws:
Returns:
     true if the field is present. false if not.
/**
     * 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.
     * 
     * @param field
     *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
     *      MINUTES, or SECONDS.)
     * @return

     *      true if the field is present. false if not.
     * 
     * @throws NullPointerException
     *      If the field parameter is null.
     */
    public abstract boolean isSet(final DatatypeConstants.Field field);

    
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.


Params:
  • rhs – Duration to add to this Duration
Throws:
See Also:
Returns:
     non-null valid Duration object.
/**
     * <p>Computes a new duration whose value is <code>this+rhs</code>.</p>
     * 
     * <p>For example,</p>
     * <pre>
     * "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
     * </pre>
     * 
     * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
     * there are cases where the operation fails in
     * {@link IllegalStateException}.</p> 
     * 
     * <p>
     * Formally, the computation is defined as follows.</p>
     * <p>
     * Firstly, we can assume that two <code>Duration</code>s to be added
     * are both positive without losing generality (i.e.,
     * <code>(-X)+Y=Y-X</code>, <code>X+(-Y)=X-Y</code>,
     * <code>(-X)+(-Y)=-(X+Y)</code>)
     * 
     * <p>
     * Addition of two positive <code>Duration</code>s are simply defined as  
     * field by field addition where missing fields are treated as 0.
     * <p>
     * A field of the resulting <code>Duration</code> will be unset if and
     * only if respective fields of two input <code>Duration</code>s are unset. 
     * <p>
     * Note that <code>lhs.add(rhs)</code> will be always successful if
     * <code>lhs.signum()*rhs.signum()!=-1</code> or both of them are
     * normalized.</p>
     * 
     * @param rhs <code>Duration</code> to add to this <code>Duration</code>
     * 
     * @return

     *      non-null valid Duration object.
     * 
     * @throws NullPointerException
     *      If the rhs parameter is null.
     * @throws IllegalStateException
     *      If two durations cannot be meaningfully added. For
     *      example, adding negative one day to one month causes
     *      this exception.
     * 
     * 
     * @see #subtract(Duration)
     */
    public abstract Duration add(final Duration rhs);

    
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. 
Params:
  • calendar – 
     A calendar object whose value will be modified.
Throws:
/**
     * Adds this duration to a {@link Calendar} object.
     * 
     * <p>
     * Calls {@link java.util.Calendar#add(int,int)} in the
     * order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS
     * if those fields are present. Because the {@link 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.) 
     * </p>
     * 
     * <p>
     * Also, since this duration class is a Gregorian duration, this
     * method will not work correctly if the given {@link Calendar}
     * object is based on some other calendar systems. 
     * </p>
     * 
     * <p>
     * Any fractional parts of this <code>Duration</code> 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. 
     * </p>
     * 
     * <p>
     * Note that because {@link Calendar#add(int, int)} is using
     * <tt>int</tt>, <code>Duration</code> with values beyond the
     * range of <tt>int</tt> in its fields
     * will cause overflow/underflow to the given {@link Calendar}.
     * {@link XMLGregorianCalendar#add(Duration)} provides the same
     * basic operation as this method while avoiding
     * the overflow/underflow issues.
     * 
     * @param calendar
     *      A calendar object whose value will be modified.
     * @throws NullPointerException
     *      if the calendar parameter is null.
     */
    public abstract void addTo(Calendar calendar);

    
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.

Params:
  • date – 
     A date object whose value will be modified.
Throws:
/**
     * Adds this duration to a {@link Date} object.
     * 
     * <p>
     * The given date is first converted into
     * a {@link java.util.GregorianCalendar}, then the duration
     * is added exactly like the {@link #addTo(Calendar)} method.
     * 
     * <p>
     * The updated time instant is then converted back into a
     * {@link Date} object and used to update the given {@link Date} object.
     * 
     * <p>
     * This somewhat redundant computation is necessary to unambiguously
     * determine the duration of months and years.
     * 
     * @param date
     *      A date object whose value will be modified.
     * @throws NullPointerException
     *      if the date parameter is null.
     */
    public void addTo(Date date) {

        // check data parameter
        if (date == null) {
            throw new NullPointerException(
                    "Cannot call "
                    + this.getClass().getName()
                    + "#addTo(Date date) with date == null."
            );
        }

        Calendar cal = new GregorianCalendar();
        cal.setTime(date); 
        this.addTo(cal);
        date.setTime(getCalendarTimeInMillis(cal));
    }

    
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.


Params:
  • rhs – Duration to subtract from this Duration.
Throws:
See Also:
Returns:New Duration created from subtracting rhs from this Duration.
/**
     * <p>Computes a new duration whose value is <code>this-rhs</code>.</p>
     * 
     * <p>For example:</p>
     * <pre>
     * "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"
     * </pre>
     * 
     * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
     * there are cases where the operation fails in {@link IllegalStateException}.</p> 
     * 
     * <p>Formally the computation is defined as follows.
     * First, we can assume that two <code>Duration</code>s are both positive
     * without losing generality.  (i.e.,
     * <code>(-X)-Y=-(X+Y)</code>, <code>X-(-Y)=X+Y</code>,
     * <code>(-X)-(-Y)=-(X-Y)</code>)</p>
     *  
     * <p>Then two durations are subtracted field by field.
     * If the sign of any non-zero field <tt>F</tt> is different from
     * the sign of the most significant field,
     * 1 (if <tt>F</tt> is negative) or -1 (otherwise)
     * will be borrowed from the next bigger unit of <tt>F</tt>.</p>
     * 
     * <p>This process is repeated until all the non-zero fields have
     * the same sign.</p> 
     * 
     * <p>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
     * {@link IllegalStateException}.</p>
     * 
     * @param rhs <code>Duration</code> to subtract from this <code>Duration</code>.
     *  
     * @return New <code>Duration</code> created from subtracting <code>rhs</code> from this <code>Duration</code>.
     * 
     * @throws IllegalStateException
     *      If two durations cannot be meaningfully subtracted. For
     *      example, subtracting one day from one month causes
     *      this exception.
     * 
     * @throws NullPointerException
     *      If the rhs parameter is null.
     * 
     * @see #add(Duration)
     */
    public Duration subtract(final Duration rhs) {
        return add(rhs.negate());
    }

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



Params:
  • factor – Factor times longer of new Duration to create.
See Also:
Returns:New Duration that is factortimes longer than this Duration.
/**
     * <p>Computes a new duration whose value is <code>factor</code> times
     * longer than the value of this duration.</p>
     * 
     * <p>This method is provided for the convenience.
     * It is functionally equivalent to the following code:</p>
     * <pre>
     * multiply(new BigDecimal(String.valueOf(factor)))
     * </pre>
     * 
     * @param factor Factor times longer of new <code>Duration</code> to create.
     * 
     * @return New <code>Duration</code> that is <code>factor</code>times longer than this <code>Duration</code>.
     * 
     * @see #multiply(BigDecimal)
     */
    public Duration multiply(int factor) {
        return multiply(BigDecimal.valueOf(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. 
Params:
  • factor – to multiply by
Throws:
Returns:
     returns a non-null valid Duration object
/**
     * Computes a new duration whose value is <code>factor</code> times
     * longer than the value of this duration.
     * 
     * <p>
     * For example,
     * <pre>
     * "P1M" (1 month) * "12" = "P12M" (12 months)
     * "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
     * "P1M" (1 month) * "1.5" = IllegalStateException
     * </pre>
     *  
     * <p>
     * Since the <code>Duration</code> class is immutable, this method
     * doesn't change the value of this object. It simply computes
     * a new Duration object and returns it.
     * 
     * <p>
     * The operation will be performed field by field with the precision
     * of {@link 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
     * {@link IllegalStateException} to be thrown. 
     * For example if you multiple one month by 0.5.</p>
     * 
     * <p>
     * To avoid {@link IllegalStateException}, use
     * the {@link #normalizeWith(Calendar)} method to remove the years
     * and months fields.
     * 
     * @param factor to multiply by
     * 
     * @return

     *      returns a non-null valid <code>Duration</code> object
     *
     * @throws IllegalStateException if operation produces fraction in 
     * the months field.
     *
     * @throws NullPointerException if the <code>factor</code> parameter is 
     * <code>null</code>.
     *
     */
    public abstract Duration multiply(final BigDecimal factor);

    
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.
/**
     * Returns a new <code>Duration</code> object whose
     * value is <code>-this</code>.
     * 
     * <p>
     * Since the <code>Duration</code> class is immutable, this method
     * doesn't change the value of this object. It simply computes
     * a new Duration object and returns it.
     * 
     * @return

     *      always return a non-null valid <code>Duration</code> object.
     */
    public abstract Duration negate();	

    
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. 
 
  2. the years, months and days fields will be added to the Calendar object by using the Calendar.add(int, int) method
    3.  
 
  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. 
 
  4. the computed days, along with the hours, minutes and seconds
     fields of this duration object is used to construct a new
     Duration object.
    5. 



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.


Params:
  • startTimeInstant – Calendar reference point.
Throws:
Returns:Duration of years and months of this Duration as days.
/**
     * <p>Converts the years and months fields into the days field
     * by using a specific time instant as the reference point.</p>
     * 
     * <p>For example, duration of one month normalizes to 31 days
     * given the start time instance "July 8th 2003, 17:40:32".</p>
     * 
     * <p>Formally, the computation is done as follows:</p>
     * <ol>
     *  <li>the given Calendar object is cloned</li>
     *  <li>the years, months and days fields will be added to the {@link Calendar} object
     *      by using the {@link Calendar#add(int,int)} method</li> 
     *  <li>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</li>
     *  <li>the computed days, along with the hours, minutes and seconds
     *      fields of this duration object is used to construct a new
     *      Duration object.</li>
     * </ol>
     * 
     * <p>Note that since the Calendar class uses <code>int</code> 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.</p>
     *
     * @param startTimeInstant <code>Calendar</code> reference point.
     *  
     * @return <code>Duration</code> of years and months of this <code>Duration</code> as days.
     * 
     * @throws NullPointerException If the startTimeInstant parameter is null.
     */
    public abstract Duration normalizeWith(final Calendar startTimeInstant);

    
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:



Params:
  • duration – to compare
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:
Returns:the relationship between this Durationand duration parameter as DatatypeConstants.LESSER, DatatypeConstants.EQUAL, DatatypeConstants.GREATER or DatatypeConstants.INDETERMINATE.
/**
     * <p>Partial order relation comparison with this <code>Duration</code> instance.</p>
     * 
     * <p>Comparison result must be in accordance with
     * <a href="http://www.w3.org/TR/xmlschema-2/#duration-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2,
     * <i>Order relation on duration</i></a>.</p>
     * 
     * <p>Return:</p>
     * <ul>
     *   <li>{@link DatatypeConstants#LESSER} if this <code>Duration</code> is shorter than <code>duration</code> parameter</li>
     *   <li>{@link DatatypeConstants#EQUAL} if this <code>Duration</code> is equal to <code>duration</code> parameter</li>
     *   <li>{@link DatatypeConstants#GREATER} if this <code>Duration</code> is longer than <code>duration</code> parameter</li>
     *   <li>{@link DatatypeConstants#INDETERMINATE} if a conclusive partial order relation cannot be determined</li>
     * </ul>
     *
     * @param duration to compare
     * 
     * @return the relationship between <code>this</code> <code>Duration</code>and <code>duration</code> parameter as
     *   {@link DatatypeConstants#LESSER}, {@link DatatypeConstants#EQUAL}, {@link DatatypeConstants#GREATER}
     *   or {@link 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.
     * @throws NullPointerException if <code>duration</code> is <code>null</code>. 
     *
     * @see #isShorterThan(Duration)
     * @see #isLongerThan(Duration)
     */
    public abstract int compare(final 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).
 

Params:
  • duration – Duration to test this Duration against.
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:
Returns:
     true if the duration represented by this object
     is longer than the given duration. false otherwise.
/**
     * <p>Checks if this duration object is strictly longer than
     * another <code>Duration</code> object.</p>
     * 
     * <p>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.</p>
     * 
     * <p>For example, "P1D" (one day) > "PT12H" (12 hours) and
     * "P2Y" (two years) > "P23M" (23 months).</p> 
     * 
     * @param duration <code>Duration</code> to test this <code>Duration</code> against.
     * 
     * @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.
     * @throws NullPointerException If <code>duration</code> is null.
     * 
     * @return

     *      true if the duration represented by this object
     *      is longer than the given duration. false otherwise.
     * 
     * @see #isShorterThan(Duration)
     * @see #compare(Duration duration)
     */
    public boolean isLongerThan(final Duration duration) {
        return compare(duration) == DatatypeConstants.GREATER;
    }

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


Params:
  • duration – Duration to test this Duration against.
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:
Returns:true if duration parameter is shorter than this Duration,
  else false.
/**
     * <p>Checks if this duration object is strictly shorter than
     * another <code>Duration</code> object.</p>
     * 
     * @param duration <code>Duration</code> to test this <code>Duration</code> against.
     * 
     * @return <code>true</code> if <code>duration</code> parameter is shorter than this <code>Duration</code>,
     *   else <code>false</code>. 
     * 
     * @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.
     * @throws NullPointerException if <code>duration</code> is null.
     *
     * @see #isLongerThan(Duration duration)
     * @see #compare(Duration duration)
     */
    public boolean isShorterThan(final Duration duration) {
        return compare(duration) == DatatypeConstants.LESSER;
    }

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



Params:
  • duration – 
     A non-null valid Duration object.
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.
See Also:
Returns:
     true if this duration is the same length as
        duration.
     false if duration is not a
        Duration object, is null,
        or its length is different from this duration.
/**
     * <p>Checks if this duration object has the same duration
     * as another <code>Duration</code> object.</p>
     * 
     * <p>For example, "P1D" (1 day) is equal to "PT24H" (24 hours).</p>
     * 
     * <p>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.</p>
     * 
     * <p>Note that there are cases where two <code>Duration</code>s are
     * "incomparable" to each other, like one month and 30 days.
     * For example,</p>
     * <pre>
     * !new Duration("P1M").isShorterThan(new Duration("P30D"))
     * !new Duration("P1M").isLongerThan(new Duration("P30D"))
     * !new Duration("P1M").equals(new Duration("P30D"))
     * </pre>
     * 
     * @param duration
     *      A non-null valid <code>Duration</code> object.
     * 
     * @return

     *      <code>true</code> if this duration is the same length as
     *         <code>duration</code>.
     *      <code>false</code> if <code>duration</code> is not a
     *         <code>Duration</code> object, is <code>null</code>,
     *         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.
     *
     * @see #compare(Duration duration)
     */
    public boolean equals(final Object duration) {
        if (duration == this) {
            return true;
        }
        if (duration instanceof Duration) {
            return compare((Duration) duration) == DatatypeConstants.EQUAL;
        }
        return false;
    }

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

See Also:
  • hashCode.hashCode()
/**
     * Returns a hash code consistent with the definition of the equals method.
     * 
     * @see Object#hashCode() 
     */
    public abstract int hashCode();

    
Returns a String representation of this Duration Object.


The result is formatted according to the XML Schema 1.0 specification 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)



Returns:A non-null valid String representation of this Duration.
/**
     * <p>Returns a <code>String</code> representation of this <code>Duration</code> <code>Object</code>.</p>
     * 
     * <p>The result is formatted according to the XML Schema 1.0 specification and can be always parsed back later into the
     * equivalent <code>Duration</code> <code>Object</code> by {@link DatatypeFactory#newDuration(String  lexicalRepresentation)}.</p>
     * 
     * <p>Formally, the following holds for any <code>Duration</code>
     * <code>Object</code> x:</p> 
     * <pre>
     * new Duration(x.toString()).equals(x)
     * </pre>
     * 
     * @return A non-<code>null</code> valid <code>String</code> representation of this <code>Duration</code>.
     */
    public String toString() {

        StringBuffer buf = new StringBuffer();

        if (getSign() < 0) {
            buf.append('-');
        }
        buf.append('P');

        BigInteger years = (BigInteger) getField(DatatypeConstants.YEARS);
        if (years != null) {
            buf.append(years).append('Y');
        }

        BigInteger months = (BigInteger) getField(DatatypeConstants.MONTHS);
        if (months != null) {
            buf.append(months).append('M');
        }

        BigInteger days = (BigInteger) getField(DatatypeConstants.DAYS);
        if (days != null) {
            buf.append(days).append('D');
        }

        BigInteger hours = (BigInteger) getField(DatatypeConstants.HOURS);
        BigInteger minutes = (BigInteger) getField(DatatypeConstants.MINUTES);
        BigDecimal seconds = (BigDecimal) getField(DatatypeConstants.SECONDS);
        if (hours != null || minutes != null || seconds != null) {
            buf.append('T');
            if (hours != null) {
                buf.append(hours).append('H');
            }
            if (minutes != null) {
                buf.append(minutes).append('M');
            }
            if (seconds != null) {
                buf.append(toString(seconds)).append('S');
            }
        }

        return buf.toString();
    }

    
Turns BigDecimal to a string representation.


Due to a behavior change in the BigDecimal.toString() method in JDK1.5, this had to be implemented here.


Params:
  • bd – BigDecimal to format as a String
Returns: String representation of BigDecimal
/**
     * <p>Turns {@link BigDecimal} to a string representation.</p>
     * 
     * <p>Due to a behavior change in the {@link BigDecimal#toString()}
     * method in JDK1.5, this had to be implemented here.</p>
     * 
     * @param bd <code>BigDecimal</code> to format as a <code>String</code>
     * 
     * @return  <code>String</code> representation of <code>BigDecimal</code> 
     */
    private String toString(BigDecimal bd) {
        String intString = bd.unscaledValue().toString();
        int scale = bd.scale();

        if (scale == 0) {
            return intString;
        }

        /* Insert decimal point */
        StringBuffer buf;
        int insertionPoint = intString.length() - scale;
        if (insertionPoint == 0) { /* Point goes right before intVal */
            return "0." + intString;
        } 
        else if (insertionPoint > 0) { /* Point goes inside intVal */
            buf = new StringBuffer(intString);
            buf.insert(insertionPoint, '.');
        } 
        else { /* We must insert zeros between point and intVal */
            buf = new StringBuffer(3 - insertionPoint + intString.length());
            buf.append("0.");
            for (int i = 0; i < -insertionPoint; i++) {
                buf.append('0');
            }
            buf.append(intString);
        }
        return buf.toString();
    }


    
Calls the Calendar.getTimeInMillis method. Prior to JDK1.4, this method was protected and therefore cannot be invoked directly.


TODO: In future, this should be replaced by cal.getTimeInMillis().


Params:
  • cal – Calendar to get time in milliseconds.
Returns:Milliseconds of cal.
/**
     * <p>Calls the {@link Calendar#getTimeInMillis} method.
     * Prior to JDK1.4, this method was protected and therefore
     * cannot be invoked directly.</p>
     * 
     * <p>TODO: In future, this should be replaced by <code>cal.getTimeInMillis()</code>.</p>
     * 
     * @param cal <code>Calendar</code> to get time in milliseconds.
     * 
     * @return Milliseconds of <code>cal</code>.
     */
    private static long getCalendarTimeInMillis(final Calendar cal) {
        return cal.getTime().getTime();
    }
}