Home » xml-commons-external-1.4.01-src » javax » xml » datatype » [javadoc | source]

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
   10    *
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   
   18   //$Id: Duration.java 759828 2009-03-30 01:26:29Z mrglavas $
   19   
   20   package javax.xml.datatype;
   21   
   22   import java.math.BigDecimal;
   23   import java.math.BigInteger;
   24   import java.util.Calendar;
   25   import java.util.Date;
   26   import java.util.GregorianCalendar;
   27   
   28   import javax.xml.namespace.QName;
   29   
   30   /**
   31    * <p>Immutable representation of a time span as defined in
   32    * the W3C XML Schema 1.0 specification.</p>
   33    * 
   34    * <p>A Duration object represents a period of Gregorian time,
   35    * which consists of six fields (years, months, days, hours,
   36    * minutes, and seconds) plus a sign (+/-) field.</p>
   37    * 
   38    * <p>The first five fields have non-negative (>=0) integers or null
   39    * (which represents that the field is not set),
   40    * and the seconds field has a non-negative decimal or null.
   41    * A negative sign indicates a negative duration.</p> 
   42    * 
   43    * <p>This class provides a number of methods that make it easy
   44    * to use for the duration datatype of XML Schema 1.0 with
   45    * the errata.</p>
   46    * 
   47    * <h2>Order relationship</h2>
   48    * <p>Duration objects only have partial order, where two values A and B
   49    * maybe either:</p>
   50    * <ol>
   51    *  <li>A&lt;B (A is shorter than B)
   52    *  <li>A&gt;B (A is longer than B)
   53    *  <li>A==B   (A and B are of the same duration)
   54    *  <li>A&lt;>B (Comparison between A and B is indeterminate)
   55    * </ol>
   56    *
   57    * <p>For example, 30 days cannot be meaningfully compared to one month.
   58    * The {@link #compare(Duration duration)} method implements this
   59    * relationship.</p>
   60    * 
   61    * <p>See the {@link #isLongerThan(Duration)} method for details about
   62    * the order relationship among <code>Duration</code> objects.</p>
   63    * 
   64    * <h2>Operations over Duration</h2>
   65    * <p>This class provides a set of basic arithmetic operations, such
   66    * as addition, subtraction and multiplication.
   67    * Because durations don't have total order, an operation could
   68    * fail for some combinations of operations. For example, you cannot
   69    * subtract 15 days from 1 month. See the javadoc of those methods
   70    * for detailed conditions where this could happen.</p>
   71    * 
   72    * <p>Also, division of a duration by a number is not provided because
   73    * the <code>Duration</code> class can only deal with finite precision
   74    * decimal numbers. For example, one cannot represent 1 sec divided by 3.</p> 
   75    * 
   76    * <p>However, you could substitute a division by 3 with multiplying
   77    * by numbers such as 0.3 or 0.333.</p>
   78    * 
   79    * <h2>Range of allowed values</h2>
   80    * <p>
   81    * Because some operations of <code>Duration</code> rely on {@link Calendar}
   82    * even though {@link Duration} can hold very large or very small values,
   83    * some of the methods may not work correctly on such <code>Duration</code>s.
   84    * The impacted methods document their dependency on {@link Calendar}.
   85    * 
   86    *  
   87    * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
   88    * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
   89    * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
   90    * @version $Revision: 759828 $, $Date: 2009-03-29 21:26:29 -0400 (Sun, 29 Mar 2009) $    
   91    * @see XMLGregorianCalendar#add(Duration)
   92    * @since 1.5
   93    */
   94   public abstract class Duration {
   95   
   96       /**
   97        * <p>Return the name of the XML Schema date/time type that this instance 
   98        * maps to. Type is computed based on fields that are set,
   99        * i.e. {@link #isSet(DatatypeConstants.Field field)} == <code>true</code>.</p>
  100        *
  101        * <table border="2" rules="all" cellpadding="2">
  102        *   <thead>
  103        *     <tr>
  104        *       <th align="center" colspan="7">
  105        *         Required fields for XML Schema 1.0 Date/Time Datatypes.<br/>
  106        *         <i>(timezone is optional for all date/time datatypes)</i>
  107        *       </th>
  108        *     </tr>
  109        *   </thead>
  110        *   <tbody>
  111        *     <tr>
  112        *       <td>Datatype</td>
  113        *       <td>year</td>
  114        *       <td>month</td>
  115        *       <td>day</td>
  116        *       <td>hour</td>
  117        *       <td>minute</td>
  118        *       <td>second</td>
  119        *     </tr>
  120        *     <tr>
  121        *       <td>{@link DatatypeConstants#DURATION}</td>
  122        *       <td>X</td>
  123        *       <td>X</td>
  124        *       <td>X</td>
  125        *       <td>X</td>
  126        *       <td>X</td>
  127        *       <td>X</td>
  128        *     </tr>
  129        *     <tr>
  130        *       <td>{@link DatatypeConstants#DURATION_DAYTIME}</td>
  131        *       <td></td>
  132        *       <td></td>
  133        *       <td>X</td>
  134        *       <td>X</td>
  135        *       <td>X</td>
  136        *       <td>X</td>
  137        *     </tr>
  138        *     <tr>
  139        *       <td>{@link DatatypeConstants#DURATION_YEARMONTH}</td>
  140        *       <td>X</td>
  141        *       <td>X</td>
  142        *       <td></td>
  143        *       <td></td>
  144        *       <td></td>
  145        *       <td></td>
  146        *     </tr>
  147        *   </tbody>
  148        * </table>
  149        * 
  150        * @return one of the following constants:
  151        *   {@link DatatypeConstants#DURATION},
  152        *   {@link DatatypeConstants#DURATION_DAYTIME} or
  153        *   {@link DatatypeConstants#DURATION_YEARMONTH}.
  154        *  
  155        * @throws IllegalStateException If the combination of set fields does not match one of the XML Schema date/time datatypes.
  156        */
  157       public QName getXMLSchemaType() {
  158   
  159           boolean yearSet = isSet(DatatypeConstants.YEARS);
  160           boolean monthSet = isSet(DatatypeConstants.MONTHS);
  161           boolean daySet = isSet(DatatypeConstants.DAYS);
  162           boolean hourSet = isSet(DatatypeConstants.HOURS);
  163           boolean minuteSet = isSet(DatatypeConstants.MINUTES);
  164           boolean secondSet = isSet(DatatypeConstants.SECONDS);
  165   
  166           // DURATION
  167           if (yearSet
  168                   && monthSet
  169                   && daySet
  170                   && hourSet
  171                   && minuteSet
  172                   && secondSet) {
  173               return DatatypeConstants.DURATION;
  174           }
  175   
  176           // DURATION_DAYTIME
  177           if (!yearSet
  178                   && !monthSet
  179                   && daySet
  180                   && hourSet
  181                   && minuteSet
  182                   && secondSet) {
  183               return DatatypeConstants.DURATION_DAYTIME;
  184           }
  185   
  186           // DURATION_YEARMONTH
  187           if (yearSet
  188                   && monthSet
  189                   && !daySet
  190                   && !hourSet
  191                   && !minuteSet
  192                   && !secondSet) {
  193               return DatatypeConstants.DURATION_YEARMONTH;
  194           }
  195   
  196           // nothing matches
  197           throw new IllegalStateException(
  198                   "javax.xml.datatype.Duration#getXMLSchemaType():"
  199                   + " this Duration does not match one of the XML Schema date/time datatypes:"
  200                   + " year set = " + yearSet
  201                   + " month set = " + monthSet
  202                   + " day set = " + daySet
  203                   + " hour set = " + hourSet
  204                   + " minute set = " + minuteSet
  205                   + " second set = " + secondSet
  206           );
  207       }
  208   
  209       /**
  210        * Returns the sign of this duration in -1,0, or 1.
  211        * 
  212        * @return
  213        *      -1 if this duration is negative, 0 if the duration is zero,
  214        *      and 1 if the duration is positive.
  215        */
  216       public abstract int getSign();
  217   
  218       /**
  219        * <p>Get the years value of this <code>Duration</code> as an <code>int</code> or <code>0</code> if not present.</p>
  220        * 
  221        * <p><code>getYears()</code> is a convenience method for
  222        * {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)}.</p>
  223        * 
  224        * <p>As the return value is an <code>int</code>, an incorrect value will be returned for <code>Duration</code>s
  225        * with years that go beyond the range of an <code>int</code>.
  226        * Use {@link #getField(DatatypeConstants.Field field) getField(DatatypeConstants.YEARS)} to avoid possible loss of precision.</p>
  227        * 
  228        * @return If the years field is present, return its value as an <code>int</code>, else return <code>0</code>.
  229        */
  230       public int getYears() {
  231           return getFieldValueAsInt(DatatypeConstants.YEARS);
  232       }
  233   
  234       /**
  235        * Obtains the value of the MONTHS field as an integer value,
  236        * or 0 if not present.
  237        * 
  238        * This method works just like {@link #getYears()} except
  239        * that this method works on the MONTHS field.
  240        * 
  241        * @return Months of this <code>Duration</code>.
  242        */
  243       public int getMonths() {
  244           return getFieldValueAsInt(DatatypeConstants.MONTHS);
  245       }
  246   
  247       /**
  248        * Obtains the value of the DAYS field as an integer value,
  249        * or 0 if not present.
  250        * 
  251        * This method works just like {@link #getYears()} except
  252        * that this method works on the DAYS field.
  253        * 
  254        * @return Days of this <code>Duration</code>.
  255        */
  256       public int getDays() {
  257           return getFieldValueAsInt(DatatypeConstants.DAYS);
  258       }
  259   
  260       /**
  261        * Obtains the value of the HOURS field as an integer value,
  262        * or 0 if not present.
  263        * 
  264        * This method works just like {@link #getYears()} except
  265        * that this method works on the HOURS field.
  266        * 
  267        * @return Hours of this <code>Duration</code>.
  268        * 
  269        */
  270       public int getHours() {
  271           return getFieldValueAsInt(DatatypeConstants.HOURS);
  272       }
  273   
  274       /**
  275        * Obtains the value of the MINUTES field as an integer value,
  276        * or 0 if not present.
  277        * 
  278        * This method works just like {@link #getYears()} except
  279        * that this method works on the MINUTES field.
  280        * 
  281        * @return Minutes of this <code>Duration</code>.
  282        * 
  283        */
  284       public int getMinutes() {
  285           return getFieldValueAsInt(DatatypeConstants.MINUTES);
  286       }
  287   
  288       /**
  289        * Obtains the value of the SECONDS field as an integer value,
  290        * or 0 if not present.
  291        * 
  292        * This method works just like {@link #getYears()} except
  293        * that this method works on the SECONDS field.
  294        * 
  295        * @return seconds in the integer value. The fraction of seconds
  296        *   will be discarded (for example, if the actual value is 2.5,
  297        *   this method returns 2)
  298        */
  299       public int getSeconds() {
  300           return getFieldValueAsInt(DatatypeConstants.SECONDS);
  301       }
  302   
  303       /**
  304        * <p>Returns the length of the duration in milliseconds.</p>
  305        * 
  306        * <p>If the seconds field carries more digits than millisecond order,
  307        * those will be simply discarded (or in other words, rounded to zero.)  
  308        * For example, for any Calendar value <code>x</code>,</p>
  309        * <pre>
  310        * <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
  311        * <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
  312        * </pre>
  313        * 
  314        * <p>
  315        * Note that this method uses the {@link #addTo(Calendar)} method,
  316        * which may work incorrectly with <code>Duration</code> objects with
  317        * very large values in its fields. See the {@link #addTo(Calendar)}
  318        * method for details.
  319        * 
  320        * @param startInstant
  321        *      The length of a month/year varies. The <code>startInstant</code> is
  322        *      used to disambiguate this variance. Specifically, this method
  323        *      returns the difference between <code>startInstant</code> and
  324        *      <code>startInstant+duration</code>
  325        * 
  326        * @return milliseconds between <code>startInstant</code> and
  327        *   <code>startInstant</code> plus this <code>Duration</code>
  328        *
  329        * @throws NullPointerException if <code>startInstant</code> parameter 
  330        * is null.
  331        * 
  332        */
  333       public long getTimeInMillis(final Calendar startInstant) {
  334           Calendar cal = (Calendar) startInstant.clone();
  335           addTo(cal);
  336           return getCalendarTimeInMillis(cal)
  337           - getCalendarTimeInMillis(startInstant);
  338       }
  339   
  340       /**
  341        * <p>Returns the length of the duration in milliseconds.</p>
  342        * 
  343        * <p>If the seconds field carries more digits than millisecond order,
  344        * those will be simply discarded (or in other words, rounded to zero.)
  345        * For example, for any <code>Date</code> value <code>x</code>,</p>   
  346        * <pre>
  347        * <code>new Duration("PT10.00099S").getTimeInMills(x) == 10000</code>.
  348        * <code>new Duration("-PT10.00099S").getTimeInMills(x) == -10000</code>.
  349        * </pre>
  350        * 
  351        * <p>
  352        * Note that this method uses the {@link #addTo(Date)} method,
  353        * which may work incorrectly with <code>Duration</code> objects with
  354        * very large values in its fields. See the {@link #addTo(Date)}
  355        * method for details.
  356        * 
  357        * @param startInstant
  358        *      The length of a month/year varies. The <code>startInstant</code> is
  359        *      used to disambiguate this variance. Specifically, this method
  360        *      returns the difference between <code>startInstant</code> and
  361        *      <code>startInstant+duration</code>.
  362        * 
  363        * @throws NullPointerException
  364        *      If the startInstant parameter is null.
  365        * 
  366        * @return milliseconds between <code>startInstant</code> and
  367        *   <code>startInstant</code> plus this <code>Duration</code>
  368        *
  369        * @see #getTimeInMillis(Calendar)
  370        */
  371       public long getTimeInMillis(final Date startInstant) {
  372           Calendar cal = new GregorianCalendar();
  373           cal.setTime(startInstant);
  374           this.addTo(cal);
  375           return getCalendarTimeInMillis(cal) - startInstant.getTime();
  376       }
  377   
  378       /**
  379        * Gets the value of a field. 
  380        * 
  381        * Fields of a duration object may contain arbitrary large value.
  382        * Therefore this method is designed to return a {@link Number} object.
  383        * 
  384        * In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned
  385        * number will be a non-negative integer. In case of seconds,
  386        * the returned number may be a non-negative decimal value.
  387        * 
  388        * @param field
  389        *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
  390        *      MINUTES, or SECONDS.)
  391        * @return
  392        *      If the specified field is present, this method returns
  393        *      a non-null non-negative {@link Number} object that
  394        *      represents its value. If it is not present, return null.
  395        *      For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method
  396        *      returns a {@link java.math.BigInteger} object. For SECONDS, this
  397        *      method returns a {@link java.math.BigDecimal}. 
  398        * 
  399        * @throws NullPointerException If the <code>field</code> is <code>null</code>.
  400        */
  401       public abstract Number getField(final DatatypeConstants.Field field);
  402       
  403       /**
  404        * Gets the value of a field as an <code>int</code>.
  405        * 
  406        * @param field 
  407        *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
  408        *      MINUTES, or SECONDS.)
  409        * @return 
  410        *      If the field is present, return its value as an <code>int</code>, 
  411        *      else return <code>0</code>.
  412        */
  413       private int getFieldValueAsInt(final DatatypeConstants.Field field) {
  414           Number n = getField(field);
  415           if (n != null) {
  416               return n.intValue();
  417           }
  418           return 0;
  419       }
  420   
  421       /**
  422        * Checks if a field is set.
  423        * 
  424        * A field of a duration object may or may not be present.
  425        * This method can be used to test if a field is present.
  426        * 
  427        * @param field
  428        *      one of the six Field constants (YEARS,MONTHS,DAYS,HOURS,
  429        *      MINUTES, or SECONDS.)
  430        * @return
  431        *      true if the field is present. false if not.
  432        * 
  433        * @throws NullPointerException
  434        *      If the field parameter is null.
  435        */
  436       public abstract boolean isSet(final DatatypeConstants.Field field);
  437   
  438       /**
  439        * <p>Computes a new duration whose value is <code>this+rhs</code>.</p>
  440        * 
  441        * <p>For example,</p>
  442        * <pre>
  443        * "1 day" + "-3 days" = "-2 days"
  444        * "1 year" + "1 day" = "1 year and 1 day"
  445        * "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"
  446        * "15 hours" + "-3 days" = "-(2 days,9 hours)"
  447        * "1 year" + "-1 day" = IllegalStateException
  448        * </pre>
  449        * 
  450        * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
  451        * there are cases where the operation fails in
  452        * {@link IllegalStateException}.</p> 
  453        * 
  454        * <p>
  455        * Formally, the computation is defined as follows.</p>
  456        * <p>
  457        * Firstly, we can assume that two <code>Duration</code>s to be added
  458        * are both positive without losing generality (i.e.,
  459        * <code>(-X)+Y=Y-X</code>, <code>X+(-Y)=X-Y</code>,
  460        * <code>(-X)+(-Y)=-(X+Y)</code>)
  461        * 
  462        * <p>
  463        * Addition of two positive <code>Duration</code>s are simply defined as  
  464        * field by field addition where missing fields are treated as 0.
  465        * <p>
  466        * A field of the resulting <code>Duration</code> will be unset if and
  467        * only if respective fields of two input <code>Duration</code>s are unset. 
  468        * <p>
  469        * Note that <code>lhs.add(rhs)</code> will be always successful if
  470        * <code>lhs.signum()*rhs.signum()!=-1</code> or both of them are
  471        * normalized.</p>
  472        * 
  473        * @param rhs <code>Duration</code> to add to this <code>Duration</code>
  474        * 
  475        * @return
  476        *      non-null valid Duration object.
  477        * 
  478        * @throws NullPointerException
  479        *      If the rhs parameter is null.
  480        * @throws IllegalStateException
  481        *      If two durations cannot be meaningfully added. For
  482        *      example, adding negative one day to one month causes
  483        *      this exception.
  484        * 
  485        * 
  486        * @see #subtract(Duration)
  487        */
  488       public abstract Duration add(final Duration rhs);
  489   
  490       /**
  491        * Adds this duration to a {@link Calendar} object.
  492        * 
  493        * <p>
  494        * Calls {@link java.util.Calendar#add(int,int)} in the
  495        * order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS
  496        * if those fields are present. Because the {@link Calendar} class
  497        * uses int to hold values, there are cases where this method
  498        * won't work correctly (for example if values of fields
  499        * exceed the range of int.) 
  500        * </p>
  501        * 
  502        * <p>
  503        * Also, since this duration class is a Gregorian duration, this
  504        * method will not work correctly if the given {@link Calendar}
  505        * object is based on some other calendar systems. 
  506        * </p>
  507        * 
  508        * <p>
  509        * Any fractional parts of this <code>Duration</code> object
  510        * beyond milliseconds will be simply ignored. For example, if
  511        * this duration is "P1.23456S", then 1 is added to SECONDS,
  512        * 234 is added to MILLISECONDS, and the rest will be unused. 
  513        * </p>
  514        * 
  515        * <p>
  516        * Note that because {@link Calendar#add(int, int)} is using
  517        * <tt>int</tt>, <code>Duration</code> with values beyond the
  518        * range of <tt>int</tt> in its fields
  519        * will cause overflow/underflow to the given {@link Calendar}.
  520        * {@link XMLGregorianCalendar#add(Duration)} provides the same
  521        * basic operation as this method while avoiding
  522        * the overflow/underflow issues.
  523        * 
  524        * @param calendar
  525        *      A calendar object whose value will be modified.
  526        * @throws NullPointerException
  527        *      if the calendar parameter is null.
  528        */
  529       public abstract void addTo(Calendar calendar);
  530   
  531       /**
  532        * Adds this duration to a {@link Date} object.
  533        * 
  534        * <p>
  535        * The given date is first converted into
  536        * a {@link java.util.GregorianCalendar}, then the duration
  537        * is added exactly like the {@link #addTo(Calendar)} method.
  538        * 
  539        * <p>
  540        * The updated time instant is then converted back into a
  541        * {@link Date} object and used to update the given {@link Date} object.
  542        * 
  543        * <p>
  544        * This somewhat redundant computation is necessary to unambiguously
  545        * determine the duration of months and years.
  546        * 
  547        * @param date
  548        *      A date object whose value will be modified.
  549        * @throws NullPointerException
  550        *      if the date parameter is null.
  551        */
  552       public void addTo(Date date) {
  553   
  554           // check data parameter
  555           if (date == null) {
  556               throw new NullPointerException(
  557                       "Cannot call "
  558                       + this.getClass().getName()
  559                       + "#addTo(Date date) with date == null."
  560               );
  561           }
  562   
  563           Calendar cal = new GregorianCalendar();
  564           cal.setTime(date); 
  565           this.addTo(cal);
  566           date.setTime(getCalendarTimeInMillis(cal));
  567       }
  568   
  569       /**
  570        * <p>Computes a new duration whose value is <code>this-rhs</code>.</p>
  571        * 
  572        * <p>For example:</p>
  573        * <pre>
  574        * "1 day" - "-3 days" = "4 days"
  575        * "1 year" - "1 day" = IllegalStateException
  576        * "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
  577        * "15 hours" - "-3 days" = "3 days and 15 hours"
  578        * "1 year" - "-1 day" = "1 year and 1 day"
  579        * </pre>
  580        * 
  581        * <p>Since there's no way to meaningfully subtract 1 day from 1 month,
  582        * there are cases where the operation fails in {@link IllegalStateException}.</p> 
  583        * 
  584        * <p>Formally the computation is defined as follows.
  585        * First, we can assume that two <code>Duration</code>s are both positive
  586        * without losing generality.  (i.e.,
  587        * <code>(-X)-Y=-(X+Y)</code>, <code>X-(-Y)=X+Y</code>,
  588        * <code>(-X)-(-Y)=-(X-Y)</code>)</p>
  589        *  
  590        * <p>Then two durations are subtracted field by field.
  591        * If the sign of any non-zero field <tt>F</tt> is different from
  592        * the sign of the most significant field,
  593        * 1 (if <tt>F</tt> is negative) or -1 (otherwise)
  594        * will be borrowed from the next bigger unit of <tt>F</tt>.</p>
  595        * 
  596        * <p>This process is repeated until all the non-zero fields have
  597        * the same sign.</p> 
  598        * 
  599        * <p>If a borrow occurs in the days field (in other words, if
  600        * the computation needs to borrow 1 or -1 month to compensate
  601        * days), then the computation fails by throwing an
  602        * {@link IllegalStateException}.</p>
  603        * 
  604        * @param rhs <code>Duration</code> to subtract from this <code>Duration</code>.
  605        *  
  606        * @return New <code>Duration</code> created from subtracting <code>rhs</code> from this <code>Duration</code>.
  607        * 
  608        * @throws IllegalStateException
  609        *      If two durations cannot be meaningfully subtracted. For
  610        *      example, subtracting one day from one month causes
  611        *      this exception.
  612        * 
  613        * @throws NullPointerException
  614        *      If the rhs parameter is null.
  615        * 
  616        * @see #add(Duration)
  617        */
  618       public Duration subtract(final Duration rhs) {
  619           return add(rhs.negate());
  620       }
  621   
  622       /**
  623        * <p>Computes a new duration whose value is <code>factor</code> times
  624        * longer than the value of this duration.</p>
  625        * 
  626        * <p>This method is provided for the convenience.
  627        * It is functionally equivalent to the following code:</p>
  628        * <pre>
  629        * multiply(new BigDecimal(String.valueOf(factor)))
  630        * </pre>
  631        * 
  632        * @param factor Factor times longer of new <code>Duration</code> to create.
  633        * 
  634        * @return New <code>Duration</code> that is <code>factor</code>times longer than this <code>Duration</code>.
  635        * 
  636        * @see #multiply(BigDecimal)
  637        */
  638       public Duration multiply(int factor) {
  639           return multiply(BigDecimal.valueOf(factor));
  640       }
  641   
  642       /**
  643        * Computes a new duration whose value is <code>factor</code> times
  644        * longer than the value of this duration.
  645        * 
  646        * <p>
  647        * For example,
  648        * <pre>
  649        * "P1M" (1 month) * "12" = "P12M" (12 months)
  650        * "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
  651        * "P1M" (1 month) * "1.5" = IllegalStateException
  652        * </pre>
  653        *  
  654        * <p>
  655        * Since the <code>Duration</code> class is immutable, this method
  656        * doesn't change the value of this object. It simply computes
  657        * a new Duration object and returns it.
  658        * 
  659        * <p>
  660        * The operation will be performed field by field with the precision
  661        * of {@link BigDecimal}. Since all the fields except seconds are
  662        * restricted to hold integers,
  663        * any fraction produced by the computation will be
  664        * carried down toward the next lower unit. For example,
  665        * if you multiply "P1D" (1 day) with "0.5", then it will be 0.5 day,
  666        * which will be carried down to "PT12H" (12 hours).
  667        * When fractions of month cannot be meaningfully carried down
  668        * to days, or year to months, this will cause an
  669        * {@link IllegalStateException} to be thrown. 
  670        * For example if you multiple one month by 0.5.</p>
  671        * 
  672        * <p>
  673        * To avoid {@link IllegalStateException}, use
  674        * the {@link #normalizeWith(Calendar)} method to remove the years
  675        * and months fields.
  676        * 
  677        * @param factor to multiply by
  678        * 
  679        * @return
  680        *      returns a non-null valid <code>Duration</code> object
  681        *
  682        * @throws IllegalStateException if operation produces fraction in 
  683        * the months field.
  684        *
  685        * @throws NullPointerException if the <code>factor</code> parameter is 
  686        * <code>null</code>.
  687        *
  688        */
  689       public abstract Duration multiply(final BigDecimal factor);
  690   
  691       /**
  692        * Returns a new <code>Duration</code> object whose
  693        * value is <code>-this</code>.
  694        * 
  695        * <p>
  696        * Since the <code>Duration</code> class is immutable, this method
  697        * doesn't change the value of this object. It simply computes
  698        * a new Duration object and returns it.
  699        * 
  700        * @return
  701        *      always return a non-null valid <code>Duration</code> object.
  702        */
  703       public abstract Duration negate();	
  704   
  705       /**
  706        * <p>Converts the years and months fields into the days field
  707        * by using a specific time instant as the reference point.</p>
  708        * 
  709        * <p>For example, duration of one month normalizes to 31 days
  710        * given the start time instance "July 8th 2003, 17:40:32".</p>
  711        * 
  712        * <p>Formally, the computation is done as follows:</p>
  713        * <ol>
  714        *  <li>the given Calendar object is cloned</li>
  715        *  <li>the years, months and days fields will be added to the {@link Calendar} object
  716        *      by using the {@link Calendar#add(int,int)} method</li> 
  717        *  <li>the difference between the two Calendars in computed in milliseconds and converted to days,
  718        *     if a remainder occurs due to Daylight Savings Time, it is discarded</li>
  719        *  <li>the computed days, along with the hours, minutes and seconds
  720        *      fields of this duration object is used to construct a new
  721        *      Duration object.</li>
  722        * </ol>
  723        * 
  724        * <p>Note that since the Calendar class uses <code>int</code> to
  725        * hold the value of year and month, this method may produce
  726        * an unexpected result if this duration object holds
  727        * a very large value in the years or months fields.</p>
  728        *
  729        * @param startTimeInstant <code>Calendar</code> reference point.
  730        *  
  731        * @return <code>Duration</code> of years and months of this <code>Duration</code> as days.
  732        * 
  733        * @throws NullPointerException If the startTimeInstant parameter is null.
  734        */
  735       public abstract Duration normalizeWith(final Calendar startTimeInstant);
  736   
  737       /**
  738        * <p>Partial order relation comparison with this <code>Duration</code> instance.</p>
  739        * 
  740        * <p>Comparison result must be in accordance with
  741        * <a href="http://www.w3.org/TR/xmlschema-2/#duration-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2,
  742        * <i>Order relation on duration</i></a>.</p>
  743        * 
  744        * <p>Return:</p>
  745        * <ul>
  746        *   <li>{@link DatatypeConstants#LESSER} if this <code>Duration</code> is shorter than <code>duration</code> parameter</li>
  747        *   <li>{@link DatatypeConstants#EQUAL} if this <code>Duration</code> is equal to <code>duration</code> parameter</li>
  748        *   <li>{@link DatatypeConstants#GREATER} if this <code>Duration</code> is longer than <code>duration</code> parameter</li>
  749        *   <li>{@link DatatypeConstants#INDETERMINATE} if a conclusive partial order relation cannot be determined</li>
  750        * </ul>
  751        *
  752        * @param duration to compare
  753        * 
  754        * @return the relationship between <code>this</code> <code>Duration</code>and <code>duration</code> parameter as
  755        *   {@link DatatypeConstants#LESSER}, {@link DatatypeConstants#EQUAL}, {@link DatatypeConstants#GREATER}
  756        *   or {@link DatatypeConstants#INDETERMINATE}.
  757        * 
  758        * @throws UnsupportedOperationException If the underlying implementation
  759        *   cannot reasonably process the request, e.g. W3C XML Schema allows for
  760        *   arbitrarily large/small/precise values, the request may be beyond the
  761        *   implementations capability.
  762        * @throws NullPointerException if <code>duration</code> is <code>null</code>. 
  763        *
  764        * @see #isShorterThan(Duration)
  765        * @see #isLongerThan(Duration)
  766        */
  767       public abstract int compare(final Duration duration);
  768   
  769       /**
  770        * <p>Checks if this duration object is strictly longer than
  771        * another <code>Duration</code> object.</p>
  772        * 
  773        * <p>Duration X is "longer" than Y if and only if X>Y 
  774        * as defined in the section 3.2.6.2 of the XML Schema 1.0
  775        * specification.</p>
  776        * 
  777        * <p>For example, "P1D" (one day) > "PT12H" (12 hours) and
  778        * "P2Y" (two years) > "P23M" (23 months).</p> 
  779        * 
  780        * @param duration <code>Duration</code> to test this <code>Duration</code> against.
  781        * 
  782        * @throws UnsupportedOperationException If the underlying implementation
  783        *   cannot reasonably process the request, e.g. W3C XML Schema allows for
  784        *   arbitrarily large/small/precise values, the request may be beyond the
  785        *   implementations capability.
  786        * @throws NullPointerException If <code>duration</code> is null.
  787        * 
  788        * @return
  789        *      true if the duration represented by this object
  790        *      is longer than the given duration. false otherwise.
  791        * 
  792        * @see #isShorterThan(Duration)
  793        * @see #compare(Duration duration)
  794        */
  795       public boolean isLongerThan(final Duration duration) {
  796           return compare(duration) == DatatypeConstants.GREATER;
  797       }
  798   
  799       /**
  800        * <p>Checks if this duration object is strictly shorter than
  801        * another <code>Duration</code> object.</p>
  802        * 
  803        * @param duration <code>Duration</code> to test this <code>Duration</code> against.
  804        * 
  805        * @return <code>true</code> if <code>duration</code> parameter is shorter than this <code>Duration</code>,
  806        *   else <code>false</code>. 
  807        * 
  808        * @throws UnsupportedOperationException If the underlying implementation
  809        *   cannot reasonably process the request, e.g. W3C XML Schema allows for
  810        *   arbitrarily large/small/precise values, the request may be beyond the
  811        *   implementations capability.
  812        * @throws NullPointerException if <code>duration</code> is null.
  813        *
  814        * @see #isLongerThan(Duration duration)
  815        * @see #compare(Duration duration)
  816        */
  817       public boolean isShorterThan(final Duration duration) {
  818           return compare(duration) == DatatypeConstants.LESSER;
  819       }
  820   
  821       /**
  822        * <p>Checks if this duration object has the same duration
  823        * as another <code>Duration</code> object.</p>
  824        * 
  825        * <p>For example, "P1D" (1 day) is equal to "PT24H" (24 hours).</p>
  826        * 
  827        * <p>Duration X is equal to Y if and only if time instant
  828        * t+X and t+Y are the same for all the test time instants
  829        * specified in the section 3.2.6.2 of the XML Schema 1.0 
  830        * specification.</p>
  831        * 
  832        * <p>Note that there are cases where two <code>Duration</code>s are
  833        * "incomparable" to each other, like one month and 30 days.
  834        * For example,</p>
  835        * <pre>
  836        * !new Duration("P1M").isShorterThan(new Duration("P30D"))
  837        * !new Duration("P1M").isLongerThan(new Duration("P30D"))
  838        * !new Duration("P1M").equals(new Duration("P30D"))
  839        * </pre>
  840        * 
  841        * @param duration
  842        *      A non-null valid <code>Duration</code> object.
  843        * 
  844        * @return
  845        *      <code>true</code> if this duration is the same length as
  846        *         <code>duration</code>.
  847        *      <code>false</code> if <code>duration</code> is not a
  848        *         <code>Duration</code> object, is <code>null</code>,
  849        *         or its length is different from this duration.
  850        * 
  851        * @throws UnsupportedOperationException If the underlying implementation
  852        *   cannot reasonably process the request, e.g. W3C XML Schema allows for
  853        *   arbitrarily large/small/precise values, the request may be beyond the
  854        *   implementations capability.
  855        *
  856        * @see #compare(Duration duration)
  857        */
  858       public boolean equals(final Object duration) {
  859           if (duration == this) {
  860               return true;
  861           }
  862           if (duration instanceof Duration) {
  863               return compare((Duration) duration) == DatatypeConstants.EQUAL;
  864           }
  865           return false;
  866       }
  867   
  868       /**
  869        * Returns a hash code consistent with the definition of the equals method.
  870        * 
  871        * @see Object#hashCode() 
  872        */
  873       public abstract int hashCode();
  874   
  875       /**
  876        * <p>Returns a <code>String</code> representation of this <code>Duration</code> <code>Object</code>.</p>
  877        * 
  878        * <p>The result is formatted according to the XML Schema 1.0 specification and can be always parsed back later into the
  879        * equivalent <code>Duration</code> <code>Object</code> by {@link DatatypeFactory#newDuration(String  lexicalRepresentation)}.</p>
  880        * 
  881        * <p>Formally, the following holds for any <code>Duration</code>
  882        * <code>Object</code> x:</p> 
  883        * <pre>
  884        * new Duration(x.toString()).equals(x)
  885        * </pre>
  886        * 
  887        * @return A non-<code>null</code> valid <code>String</code> representation of this <code>Duration</code>.
  888        */
  889       public String toString() {
  890   
  891           StringBuffer buf = new StringBuffer();
  892   
  893           if (getSign() < 0) {
  894               buf.append('-');
  895           }
  896           buf.append('P');
  897   
  898           BigInteger years = (BigInteger) getField(DatatypeConstants.YEARS);
  899           if (years != null) {
  900               buf.append(years).append('Y');
  901           }
  902   
  903           BigInteger months = (BigInteger) getField(DatatypeConstants.MONTHS);
  904           if (months != null) {
  905               buf.append(months).append('M');
  906           }
  907   
  908           BigInteger days = (BigInteger) getField(DatatypeConstants.DAYS);
  909           if (days != null) {
  910               buf.append(days).append('D');
  911           }
  912   
  913           BigInteger hours = (BigInteger) getField(DatatypeConstants.HOURS);
  914           BigInteger minutes = (BigInteger) getField(DatatypeConstants.MINUTES);
  915           BigDecimal seconds = (BigDecimal) getField(DatatypeConstants.SECONDS);
  916           if (hours != null || minutes != null || seconds != null) {
  917               buf.append('T');
  918               if (hours != null) {
  919                   buf.append(hours).append('H');
  920               }
  921               if (minutes != null) {
  922                   buf.append(minutes).append('M');
  923               }
  924               if (seconds != null) {
  925                   buf.append(toString(seconds)).append('S');
  926               }
  927           }
  928   
  929           return buf.toString();
  930       }
  931   
  932       /**
  933        * <p>Turns {@link BigDecimal} to a string representation.</p>
  934        * 
  935        * <p>Due to a behavior change in the {@link BigDecimal#toString()}
  936        * method in JDK1.5, this had to be implemented here.</p>
  937        * 
  938        * @param bd <code>BigDecimal</code> to format as a <code>String</code>
  939        * 
  940        * @return  <code>String</code> representation of <code>BigDecimal</code> 
  941        */
  942       private String toString(BigDecimal bd) {
  943           String intString = bd.unscaledValue().toString();
  944           int scale = bd.scale();
  945   
  946           if (scale == 0) {
  947               return intString;
  948           }
  949   
  950           /* Insert decimal point */
  951           StringBuffer buf;
  952           int insertionPoint = intString.length() - scale;
  953           if (insertionPoint == 0) { /* Point goes right before intVal */
  954               return "0." + intString;
  955           } 
  956           else if (insertionPoint > 0) { /* Point goes inside intVal */
  957               buf = new StringBuffer(intString);
  958               buf.insert(insertionPoint, '.');
  959           } 
  960           else { /* We must insert zeros between point and intVal */
  961               buf = new StringBuffer(3 - insertionPoint + intString.length());
  962               buf.append("0.");
  963               for (int i = 0; i < -insertionPoint; i++) {
  964                   buf.append('0');
  965               }
  966               buf.append(intString);
  967           }
  968           return buf.toString();
  969       }
  970   
  971   
  972       /**
  973        * <p>Calls the {@link Calendar#getTimeInMillis} method.
  974        * Prior to JDK1.4, this method was protected and therefore
  975        * cannot be invoked directly.</p>
  976        * 
  977        * <p>TODO: In future, this should be replaced by <code>cal.getTimeInMillis()</code>.</p>
  978        * 
  979        * @param cal <code>Calendar</code> to get time in milliseconds.
  980        * 
  981        * @return Milliseconds of <code>cal</code>.
  982        */
  983       private static long getCalendarTimeInMillis(final Calendar cal) {
  984           return cal.getTime().getTime();
  985       }
  986   }
  987   

Home » xml-commons-external-1.4.01-src » javax » xml » datatype » [javadoc | source]