Save This Page
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: XMLGregorianCalendar.java 759822 2009-03-30 01:15:11Z mrglavas $
   19   
   20   package javax.xml.datatype;
   21   
   22   import javax.xml.namespace.QName;
   23   import java.math.BigDecimal;
   24   import java.math.BigInteger;
   25   import java.util.TimeZone;
   26   import java.util.GregorianCalendar;
   27   
   28   /** 
   29    * <p>Representation for W3C XML Schema 1.0 date/time datatypes.
   30    * Specifically, these date/time datatypes are 
   31    * <a href="#DATETIME"><code>dateTime</code></a>,
   32    * <a href="#TIME"><code>time</code></a>,
   33    * <a href="#DATE"><code>date</code></a>,
   34    * <a href="#GYEARMONTH"><code>gYearMonth</code></a>,
   35    * <a href="#GMONTHDAY"><code>gMonthDay</code></a>,
   36    * <a href="#GYEAR"><code>gYear</code></a>
   37    * <a href="#GMONTH"><code>gMonth</code></a> and
   38    * <a href="#GDAY"><code>gDay</code></a> defined in the XML Namespace
   39    * <code>"http://www.w3.org/2001/XMLSchema"</code>.
   40    * These datatypes are normatively defined in 
   41    * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.</p>
   42    *
   43    * <p>The table below defines the mapping between XML Schema 1.0
   44    * date/time datatype fields and this class' fields. It also summarizes
   45    * the value constraints for the date and time fields defined in
   46    * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
   47    * <i>ISO 8601 Date and Time Formats</i></a>.</p>
   48    * 
   49    * <a name="datetimefieldsmapping"/>
   50    * <table border="2" rules="all" cellpadding="2">
   51    *   <thead>
   52    *     <tr>
   53    *       <th align="center" colspan="3">
   54    *         Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation
   55    *       </th>
   56    *     </tr>
   57    *   </thead>
   58    *   <tbody>
   59    *     <tr>
   60    *       <th>XML Schema 1.0<br/>
   61    *           datatype<br/> 
   62    *            field</th>
   63    *       <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th>
   64    *       <th>Value Range</th>
   65    *     </tr>
   66    *     <a name="datetimefield-year"/>
   67    *     <tr>
   68    *       <td> year </td>
   69    *       <td> {@link #getYear()} + {@link #getEon()} or<br/>
   70    *            {@link #getEonAndYear}
   71    *       </td>
   72    *       <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1 
   73    *            or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
   74    *            {@link #getEon()} is high order year value in billion of years.<br/>
   75    *            <code>getEon()</code> has values greater than or equal to (10^9) or less than or equal to -(10^9).
   76    *            A value of null indicates field is undefined.</br>
   77    *            Given that <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-63">XML Schema 1.0 errata</a> states that the year zero
   78    *            will be a valid lexical value in a future version of XML Schema, 
   79    *            this class allows the year field to be set to zero. Otherwise,
   80    *            the year field value is handled exactly as described
   81    *            in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0
   82    *            validation does not allow for the year field to have a value of zero.
   83    *            </td>
   84    *     </tr>
   85    *     <a name="datetimefield-month"/>
   86    *     <tr>
   87    *       <td> month </td>
   88    *       <td> {@link #getMonth()} </td>
   89    *       <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
   90    *     </tr>
   91    *     <a name="datetimefield-day"/>
   92    *     <tr>
   93    *       <td> day </td>
   94    *       <td> {@link #getDay()} </td>
   95    *       <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
   96    *            The normative value constraint stated relative to month 
   97    *            field's value is in <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D</a>.
   98    *       </td> 
   99    *     </tr>
  100    *     <tr id="datetimefield-hour">
  101    *       <td>hour</td>
  102    *       <td>{@link #getHour()}</td>
  103    *       <td>
  104    *         0 to 24 or {@link DatatypeConstants#FIELD_UNDEFINED}.
  105    *         For a value of 24, the minute and second field must be zero per
  106    *         <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">XML Schema Errata</a>.
  107    *       </td>
  108    *     </tr>
  109    *     <a name="datetimefield-minute"/>
  110    *     <tr>
  111    *       <td> minute </td>
  112    *       <td> {@link #getMinute()} </td>
  113    *       <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
  114    *     </tr>
  115    *     <a name="datetimefield-second"/>
  116    *     <tr>
  117    *       <td>second</td>
  118    *       <td>
  119    *         {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/>
  120    *         {@link #getSecond()} + {@link #getFractionalSecond()}
  121    *       </td>
  122    *       <td>
  123    *         {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
  124    *         <i>(Note: 60 only allowable for leap second.)</i><br/>
  125    *         {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when 
  126    *         the {@link #getSecond()} is defined.<br/>
  127    *         <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br />
  128    *            {@link #getMillisecond()} is the convenience 
  129    *            millisecond precision of value of {@link #getFractionalSecond()}.
  130    *       </td>
  131    *     </tr>
  132    *     <tr id="datetimefield-timezone">
  133    *       <td> timezone </td>
  134    *       <td> {@link #getTimezone()} </td>
  135    *       <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
  136    *         Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
  137    *       </td>
  138    *     </tr>
  139    *   </tbody>
  140    *  </table>
  141    *
  142    * <p>All maximum value space constraints listed for the fields in the table 
  143    * above are checked by factory methods, @{link DatatypeFactory},
  144    * setter methods and parse methods of
  145    * this class. <code>IllegalArgumentException</code> is thrown when a
  146    * parameter's value is outside the value constraint for the field or
  147    * if the composite
  148    * values constitute an invalid XMLGregorianCalendar instance (for example, if
  149    * the 31st of June is specified).
  150    * </p>
  151    * 
  152    * <p>The following operations are defined for this class:
  153    * <ul>
  154    *   <li>accessors/mutators for independent date/time fields</li>
  155    *   <li>conversion between this class and W3C XML Schema 1.0 lexical representation,
  156    *     {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}</li>
  157    *   <li>conversion between this class and {@link GregorianCalendar},
  158    *     {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)},
  159    *     {@link DatatypeFactory}</li>
  160    *   <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}</li>
  161    *   <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.</li>
  162    *   <li>addition operation with {@link Duration} 
  163    *      instance as defined in <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">
  164    *      W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>.
  165    *   </li>
  166    * </ul>
  167    * </p>
  168    * 
  169    * @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a>
  170    * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
  171    * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
  172    * @version $Revision: 759822 $, $Date: 2009-03-29 21:15:11 -0400 (Sun, 29 Mar 2009) $    
  173    * @see Duration
  174    * @see DatatypeFactory
  175    * @since 1.5
  176    */
  177   
  178   public abstract class XMLGregorianCalendar
  179   	implements Cloneable {
  180   
  181   	/**
  182   	 * <p>Unset all fields to undefined.</p>
  183   	 *
  184   	 * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields 
  185   	 * to null.</p>
  186   	 */
  187   	public abstract void clear();
  188   
  189   	/**
  190   	 * <p>Reset this <code>XMLGregorianCalendar</code> to its original values.</p>
  191   	 * 
  192   	 * <p><code>XMLGregorianCalendar</code> is reset to the same values as when it was created with
  193   	 * {@link DatatypeFactory#newXMLGregorianCalendar()},
  194   	 * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)},
  195   	 * {@link DatatypeFactory#newXMLGregorianCalendar(
  196   	 *   BigInteger year,
  197   	 *   int month,
  198   	 *   int day,
  199   	 *   int hour,
  200   	 *   int minute,
  201   	 *   int second,
  202   	 *   BigDecimal fractionalSecond,
  203   	 *   int timezone)},
  204   	 * {@link DatatypeFactory#newXMLGregorianCalendar(
  205   	 *   int year,
  206   	 *   int month,
  207   	 *   int day,
  208   	 *   int hour,
  209   	 *   int minute,
  210   	 *   int second,
  211   	 *   int millisecond,
  212   	 *   int timezone)},
  213   	 * {@link DatatypeFactory#newXMLGregorianCalendar(GregorianCalendar cal)},
  214   	 * {@link DatatypeFactory#newXMLGregorianCalendarDate(
  215   	 *   int year,
  216   	 *   int month,
  217   	 *   int day,
  218   	 *   int timezone)},
  219   	 * {@link DatatypeFactory#newXMLGregorianCalendarTime(
  220   	 *   int hours,
  221   	 *   int minutes,
  222   	 *   int seconds,
  223   	 *   int timezone)},
  224   	 * {@link DatatypeFactory#newXMLGregorianCalendarTime(
  225   	 *   int hours,
  226   	 *   int minutes,
  227   	 *   int seconds,
  228   	 *   BigDecimal fractionalSecond,
  229   	 *   int timezone)} or
  230   	 * {@link DatatypeFactory#newXMLGregorianCalendarTime(
  231   	 *   int hours,
  232   	 *   int minutes,
  233   	 *   int seconds,
  234   	 *   int milliseconds,
  235   	 *   int timezone)}.
  236   	 * </p>
  237   	 * 
  238   	 * <p><code>reset()</code> is designed to allow the reuse of existing <code>XMLGregorianCalendar</code>s
  239   	 * thus saving resources associated with the creation of new <code>XMLGregorianCalendar</code>s.</p>
  240   	 */
  241   	public abstract void reset();
  242   	
  243       /**
  244        * <p>Set low and high order component of XSD <code>dateTime</code> year field.</p>
  245        * 
  246        * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p>
  247        *
  248        * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.     
  249        *
  250        * @throws IllegalArgumentException if <code>year</code> parameter is 
  251        * outside value constraints for the field as specified in 
  252        * <a href="#datetimefieldmapping">date/time field mapping table</a>.
  253        */
  254       public abstract void setYear(BigInteger year);
  255   
  256       /**
  257        * <p>Set year of XSD <code>dateTime</code> year field.</p>
  258        *
  259        * <p>Unset this field by invoking the setter with a parameter value of 
  260        * {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  261        *
  262        * <p>Note: if the absolute value of the <code>year</code> parameter 
  263        * is less than 10^9, the eon component of the XSD year field is set to 
  264        * <code>null</code> by this method.</p>
  265        *
  266        * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
  267        *   If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to <code>null</code>.
  268        */
  269       public abstract void setYear(int year); 
  270   
  271       /**
  272        * <p>Set month.</p>
  273        *
  274        * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  275        *
  276        * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>.
  277        *
  278        * @throws IllegalArgumentException if <code>month</code> parameter is 
  279        * outside value constraints for the field as specified in 
  280        * <a href="#datetimefieldmapping">date/time field mapping table</a>.
  281        */
  282       public abstract void setMonth(int month); 
  283   
  284       /**
  285        * <p>Set days in month.</p>
  286        *
  287        * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  288        *
  289        * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>.
  290        *
  291        * @throws IllegalArgumentException if <code>day</code> parameter is 
  292        * outside value constraints for the field as specified in 
  293        * <a href="#datetimefieldmapping">date/time field mapping table</a>.
  294        */
  295       public abstract void setDay(int day);  
  296   
  297       /**
  298        * <p>Set the number of minutes in the timezone offset.</p>
  299        *
  300        * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  301        *
  302        * @param offset value constraints summarized in <a href="#datetimefield-timezone">
  303        *   timezone field of date/time field mapping table</a>.
  304        *
  305        * @throws IllegalArgumentException if <code>offset</code> parameter is 
  306        * outside value constraints for the field as specified in 
  307        * <a href="#datetimefieldmapping">date/time field mapping table</a>.
  308        */
  309       public abstract void setTimezone(int offset);
  310   
  311       /**
  312        * <p>Set time as one unit.</p>
  313        *
  314        * @param hour value constraints are summarized in 
  315        * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
  316        * @param minute value constraints are summarized in 
  317        * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
  318        * @param second value constraints are summarized in 
  319        * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
  320        *
  321        * @see #setTime(int, int, int, BigDecimal)
  322        *
  323        * @throws IllegalArgumentException if any parameter is 
  324        * outside value constraints for the field as specified in 
  325        * <a href="#datetimefieldmapping">date/time field mapping table</a>.
  326        */
  327       public void setTime(int hour, int minute, int second) {
  328       	
  329   		setTime(
  330   			hour,
  331   			minute,
  332   			second,
  333   			null // fractional
  334   		);
  335       }
  336   
  337   	/**
  338    	 * <p>Set hours.</p>
  339    	 *
  340    	 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  341    	 *
  342    	 * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
  343    	 *
  344    	 * @throws IllegalArgumentException if <code>hour</code> parameter is outside value constraints for the field as specified in 
  345    	 *   <a href="#datetimefieldmapping">date/time field mapping table</a>.
  346    	*/
  347   	public abstract void setHour(int hour);
  348   
  349   	/**
  350   	 * <p>Set minutes.</p>
  351   	 *
  352   	 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  353   	 *
  354   	 * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
  355   	 *
  356   	 * @throws IllegalArgumentException if <code>minute</code> parameter is outside value constraints for the field as specified in 
  357   	 *   <a href="#datetimefieldmapping">date/time field mapping table</a>.
  358   	*/
  359   	public abstract void setMinute(int minute);
  360   
  361   	/**
  362   	 * <p>Set seconds.</p>
  363   	 *
  364   	 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  365   	 *
  366   	 * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>.
  367   	 *
  368   	 * @throws IllegalArgumentException if <code>second</code> parameter is outside value constraints for the field as specified in 
  369   	 *   <a href="#datetimefieldmapping">date/time field mapping table</a>.
  370   	*/
  371   	public abstract void setSecond(int second);
  372   	
  373   	/**
  374   	 * <p>Set milliseconds.</p>
  375   	 *
  376   	 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  377   	 *
  378   	 * @param millisecond value constraints summarized in
  379   	 *   <a href="#datetimefield-millisecond">millisecond field of date/time field mapping table</a>.
  380   	 *
  381   	 * @throws IllegalArgumentException if <code>millisecond</code> parameter is outside value constraints for the field as specified
  382   	 *   in <a href="#datetimefieldmapping">date/time field mapping table</a>.
  383   	*/
  384   	public abstract void setMillisecond(int millisecond);
  385   
  386   	/**
  387   	 * <p>Set fractional seconds.</p>
  388   	 *
  389   	 * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p>
  390   	 *
  391   	 * @param fractional value constraints summarized in
  392   	 *   <a href="#datetimefield-fractional">fractional field of date/time field mapping table</a>.
  393   	 *
  394   	 * @throws IllegalArgumentException if <code>fractional</code> parameter is outside value constraints for the field as specified
  395   	 *   in <a href="#datetimefieldmapping">date/time field mapping table</a>.
  396   	*/
  397   	public abstract void setFractionalSecond(BigDecimal fractional);
  398   
  399       /**
  400        * <p>Set time as one unit, including the optional infinite precision 
  401        * fractional seconds.</p>
  402        *
  403        * @param hour value constraints are summarized in 
  404        * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
  405        * @param minute value constraints are summarized in 
  406        * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
  407        * @param second value constraints are summarized in 
  408        * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
  409        * @param fractional value of <code>null</code> indicates this optional 
  410        *   field is not set.
  411        *
  412        * @throws IllegalArgumentException if any parameter is 
  413        * outside value constraints for the field as specified in 
  414        * <a href="#datetimefieldmapping">date/time field mapping table</a>.
  415        */
  416       public void setTime(
  417           int hour,
  418           int minute,
  419           int second,
  420           BigDecimal fractional) {
  421           	
  422   		setHour(hour);
  423           setMinute(minute);
  424           setSecond(second);
  425           setFractionalSecond(fractional);
  426       }
  427   
  428       /**
  429        * <p>Set time as one unit, including optional milliseconds.</p>
  430        *
  431        * @param hour value constraints are summarized in 
  432        * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
  433        * @param minute value constraints are summarized in 
  434        * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
  435        * @param second value constraints are summarized in 
  436        * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
  437        * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this 
  438        *                    optional field is not set. 
  439        *
  440        * @throws IllegalArgumentException if any parameter is 
  441        * outside value constraints for the field as specified in 
  442        * <a href="#datetimefieldmapping">date/time field mapping table</a>.
  443        */
  444       public void setTime(int hour, int minute, int second, int millisecond) {
  445       	
  446           setHour(hour);
  447           setMinute(minute);
  448           setSecond(second);
  449           setMillisecond(millisecond);
  450       }
  451   
  452   	/** 
  453   	 * <p>Return high order component for XML Schema 1.0 dateTime datatype field for 
  454   	 * <code>year</code>.
  455   	 * <code>null</code> if this optional part of the year field is not defined.</p>
  456   	 * 
  457   	 * <p>Value constraints for this value are summarized in 
  458   	 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
  459   	 * @return eon of this <code>XMLGregorianCalendar</code>. The value 
  460   	 * returned is an integer multiple of 10^9.
  461   	 * 
  462   	 * @see #getYear()
  463   	 * @see #getEonAndYear()
  464   	 */
  465   	public abstract BigInteger getEon();
  466   
  467   	/** 
  468   	 * <p>Return low order component for XML Schema 1.0 dateTime datatype field for 
  469   	 * <code>year</code> or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  470   	 * 
  471   	 * <p>Value constraints for this value are summarized in 
  472   	 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
  473   	 * 
  474   	 * @return year  of this <code>XMLGregorianCalendar</code>.
  475   	 * 
  476   	 * @see #getEon()
  477   	 * @see #getEonAndYear()
  478   	 */
  479   	public abstract int getYear();
  480   
  481   	/** 
  482   	 * <p>Return XML Schema 1.0 dateTime datatype field for 
  483   	 * <code>year</code>.</p>
  484   	 * 
  485   	 * <p>Value constraints for this value are summarized in 
  486   	 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
  487   	 * 
  488   	 * @return sum of <code>eon</code> and <code>BigInteger.valueOf(year)</code>
  489   	 * when both fields are defined. When only <code>year</code> is defined, 
  490   	 * return it. When both <code>eon</code> and <code>year</code> are not 
  491   	 * defined, return <code>null</code>.
  492   	 * 
  493   	 * @see #getEon()
  494   	 * @see #getYear()
  495   	 */
  496   	public abstract BigInteger getEonAndYear();
  497   
  498   	/** 
  499   	 * <p>Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  500   	 * 
  501   	 * <p>Value constraints for this value are summarized in 
  502   	 * <a href="#datetimefield-month">month field of date/time field mapping table</a>.</p>
  503   	 * 
  504   	 * @return year  of this <code>XMLGregorianCalendar</code>.
  505   	 * 
  506   	 */
  507   	public abstract int getMonth();
  508   
  509   	/** 
  510   	 * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  511   	 *
  512   	 * <p>Value constraints for this value are summarized in 
  513   	 * <a href="#datetimefield-day">day field of date/time field mapping table</a>.</p>
  514   	 * 
  515   	 * @see #setDay(int)
  516   	 */
  517   	public abstract int getDay();
  518   
  519   	/** 
  520   	 * Return timezone offset in minutes or 
  521   	 * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
  522   	 *
  523   	 * <p>Value constraints for this value are summarized in 
  524   	 * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.</p>
  525   	 * 
  526   	 * @see #setTimezone(int)
  527   	 */
  528   	public abstract int getTimezone();
  529   
  530   	/** 
  531   	 * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}.
  532   	 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
  533   	 *
  534   	 * <p>Value constraints for this value are summarized in 
  535   	 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.</p>
  536   	 * @see #setTime(int, int, int)
  537   	 */
  538   	public abstract int getHour();
  539   
  540   	/**
  541   	 * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  542   	 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
  543   	 *
  544   	 * <p>Value constraints for this value are summarized in 
  545   	 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.</p>
  546   	 * @see #setTime(int, int, int)
  547   	 */
  548   	public abstract int getMinute();
  549   
  550   	/** 
  551   	 * <p>Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  552   	 * 
  553   	 * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
  554   	 * When this field is not defined, the optional xs:dateTime 
  555   	 * fractional seconds field, represented by 
  556   	 * {@link #getFractionalSecond()} and {@link #getMillisecond()},
  557   	 * must not be defined.</p>
  558   	 * 
  559   	 * <p>Value constraints for this value are summarized in 
  560   	 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
  561   	 * 
  562   	 * @return Second  of this <code>XMLGregorianCalendar</code>.
  563   	 * 
  564   	 * @see #getFractionalSecond()
  565   	 * @see #getMillisecond()
  566   	 * @see #setTime(int, int, int)
  567   	 */
  568   	public abstract int getSecond();
  569   
  570   	/** 
  571   	 * <p>Return millisecond precision of {@link #getFractionalSecond()}.</p>
  572   	 * 
  573   	 * <p>This method represents a convenience accessor to infinite
  574   	 * precision fractional second value returned by 
  575   	 * {@link #getFractionalSecond()}. The returned value is the rounded 
  576   	 * down to milliseconds value of 
  577   	 * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()} 
  578   	 * returns <code>null</code>, this method must return 
  579   	 * {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  580   	 *
  581   	 * <p>Value constraints for this value are summarized in 
  582   	 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
  583   	 * 
  584   	 * @return Millisecond  of this <code>XMLGregorianCalendar</code>.
  585   	 * 
  586   	 * @see #getFractionalSecond()
  587   	 * @see #setTime(int, int, int)
  588   	 */
  589   	public int getMillisecond() {
  590   		
  591   		BigDecimal fractionalSeconds = getFractionalSecond();
  592   		
  593   		// is field undefined?
  594   		if (fractionalSeconds == null) {
  595   			return DatatypeConstants.FIELD_UNDEFINED;
  596   		}
  597   		
  598   		return getFractionalSecond().movePointRight(3).intValue();
  599   	}
  600   
  601   	/** 
  602   	 * <p>Return fractional seconds.</p>
  603   	 * 
  604   	 * <p><code>null</code> is returned when this optional field is not defined.</p>
  605   	 * 
  606   	 * <p>Value constraints are detailed in
  607   	 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
  608   	 * 
  609   	 * <p>This optional field can only have a defined value when the
  610   	 * xs:dateTime second field, represented by {@link #getSecond()}, 
  611   	 * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
  612   	 *
  613   	 * @return fractional seconds  of this <code>XMLGregorianCalendar</code>.
  614   	 * 
  615   	 * @see #getSecond()
  616   	 * @see #setTime(int, int, int, BigDecimal)
  617   	 */
  618   	public abstract BigDecimal getFractionalSecond();
  619   
  620       // comparisons
  621       /**
  622        * <p>Compare two instances of W3C XML Schema 1.0 date/time datatypes 
  623        * according to partial order relation defined in 
  624        * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
  625        * <i>Order relation on dateTime</i></a>.</p>
  626        *
  627        * <p><code>xsd:dateTime</code> datatype field mapping to accessors of
  628        * this class are defined in
  629        * <a href="#datetimefieldmapping">date/time field mapping table</a>.</p>
  630        * 
  631        * @param xmlGregorianCalendar Instance of <code>XMLGregorianCalendar</code> to compare
  632        * 
  633        * @return The relationship between <code>this</code> <code>XMLGregorianCalendar</code> and
  634        *   the specified <code>xmlGregorianCalendar</code> as
  635        *   {@link DatatypeConstants#LESSER},
  636        *   {@link DatatypeConstants#EQUAL},
  637        *   {@link DatatypeConstants#GREATER} or
  638        *   {@link DatatypeConstants#INDETERMINATE}.
  639        *
  640        * @throws NullPointerException if <code>xmlGregorianCalendar</code> is null. 
  641        */
  642       public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar);
  643   
  644       /**
  645        * <p>Normalize this instance to UTC.</p>
  646        *
  647        * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z</p>
  648        * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</p>
  649        * 
  650        * @return <code>this</code> <code>XMLGregorianCalendar</code> normalized to UTC.
  651        */
  652       public abstract XMLGregorianCalendar normalize();
  653   
  654       /**
  655        * <p>Indicates whether parameter <code>obj</code> is "equal to" this one.</p>
  656        * 
  657        * @param obj to compare.
  658        *
  659        * @return <code>true</code> when <code>obj</code> is an instance of <code>XMLGregorianCalendar</code>
  660        *   and  {@link #compare(XMLGregorianCalendar obj)} returns {@link DatatypeConstants#EQUAL}, otherwise <code>false</code>.
  661        */
  662       public boolean equals(Object obj) {
  663           if (obj == this) {
  664               return true;
  665           }
  666           if (obj instanceof XMLGregorianCalendar) {
  667               return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
  668           }
  669           return false;
  670       }
  671   
  672       /**
  673        * <p>Returns a hash code consistent with the definition of the equals method.</p>
  674        * 
  675        * @return hash code of this object.
  676        */
  677       public int hashCode() {
  678   
  679           // Following two dates compare to EQUALS since in different timezones.
  680           // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00 	
  681           //
  682           // Must ensure both instances generate same hashcode by normalizing 
  683           // this to UTC timezone.
  684           int timezone = getTimezone();
  685           if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
  686               timezone = 0;
  687           }
  688           XMLGregorianCalendar gc = this;
  689           if (timezone != 0) {
  690               gc = this.normalize();
  691           }
  692           return gc.getYear()
  693           + gc.getMonth()
  694           + gc.getDay()
  695           + gc.getHour()
  696           + gc.getMinute()
  697           + gc.getSecond();
  698       }
  699       
  700       /**
  701        * <p>Return the lexical representation of <code>this</code> instance. 
  702        * The format is specified in 
  703        * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
  704        * <i>Lexical Representation</i>".</a></p>
  705        * 
  706        * <p>Specific target lexical representation format is determined by 
  707        * {@link #getXMLSchemaType()}.</p>
  708        * 
  709        * @return XML, as <code>String</code>, representation of this <code>XMLGregorianCalendar</code> 
  710        * 
  711        * @throws IllegalStateException if the combination of set fields
  712        *    does not match one of the eight defined XML Schema builtin date/time datatypes. 
  713        */
  714       public abstract String toXMLFormat();
  715   
  716       /**
  717        * <p>Return the name of the XML Schema date/time type that this instance 
  718        * maps to. Type is computed based on fields that are set.</p>
  719        *
  720        * <table border="2" rules="all" cellpadding="2">
  721        *   <thead>
  722        *     <tr>
  723        *       <th align="center" colspan="7">
  724        *         Required fields for XML Schema 1.0 Date/Time Datatypes.<br/>
  725        *         <i>(timezone is optional for all date/time datatypes)</i>
  726        *       </th>
  727        *     </tr>
  728        *   </thead>
  729        *   <tbody>
  730        *     <tr>
  731        *       <td>Datatype</td>
  732        *       <td>year</td>
  733        *       <td>month</td>
  734        *       <td>day</td>
  735        *       <td>hour</td>
  736        *       <td>minute</td>
  737        *       <td>second</td>
  738        *     </tr>
  739        *     <tr>
  740        *       <td>{@link DatatypeConstants#DATETIME}</td>
  741        *       <td>X</td>
  742        *       <td>X</td>
  743        *       <td>X</td>
  744        *       <td>X</td>
  745        *       <td>X</td>
  746        *       <td>X</td>
  747        *     </tr>
  748        *     <tr>
  749        *       <td>{@link DatatypeConstants#DATE}</td>
  750        *       <td>X</td>
  751        *       <td>X</td>
  752        *       <td>X</td>
  753        *       <td></td>
  754        *       <td></td>
  755        *       <td></td>
  756        *     </tr>
  757        *     <tr>
  758        *       <td>{@link DatatypeConstants#TIME}</td>
  759        *       <td></td>
  760        *       <td></td>
  761        *       <td></td>
  762        *       <td>X</td>
  763        *       <td>X</td>
  764        *       <td>X</td>
  765        *     </tr>
  766        *     <tr>
  767        *       <td>{@link DatatypeConstants#GYEARMONTH}</td>
  768        *       <td>X</td>
  769        *       <td>X</td>
  770        *       <td></td>
  771        *       <td></td>
  772        *       <td></td>
  773        *       <td></td>
  774        *     </tr>
  775        *     <tr>
  776        *       <td>{@link DatatypeConstants#GMONTHDAY}</td>
  777        *       <td></td>
  778        *       <td>X</td>
  779        *       <td>X</td>
  780        *       <td></td>
  781        *       <td></td>
  782        *       <td></td>
  783        *     </tr>
  784        *     <tr>
  785        *       <td>{@link DatatypeConstants#GYEAR}</td>
  786        *       <td>X</td>
  787        *       <td></td>
  788        *       <td></td>
  789        *       <td></td>
  790        *       <td></td>
  791        *       <td></td>
  792        *     </tr>
  793        *     <tr>
  794        *       <td>{@link DatatypeConstants#GMONTH}</td>
  795        *       <td></td>
  796        *       <td>X</td>
  797        *       <td></td>
  798        *       <td></td>
  799        *       <td></td>
  800        *       <td></td>
  801        *     </tr>
  802        *     <tr>
  803        *       <td>{@link DatatypeConstants#GDAY}</td>
  804        *       <td></td>
  805        *       <td></td>
  806        *       <td>X</td>
  807        *       <td></td>
  808        *       <td></td>
  809        *       <td></td>
  810        *     </tr>
  811        *   </tbody>
  812        * </table>
  813        * 
  814        * @throws java.lang.IllegalStateException if the combination of set fields
  815        *    does not match one of the eight defined XML Schema builtin 
  816        *    date/time datatypes.
  817        * @return One of the following class constants:
  818        *   {@link DatatypeConstants#DATETIME},
  819        *   {@link DatatypeConstants#TIME},
  820        *   {@link DatatypeConstants#DATE},
  821        *   {@link DatatypeConstants#GYEARMONTH},
  822        *   {@link DatatypeConstants#GMONTHDAY},
  823        *   {@link DatatypeConstants#GYEAR},
  824        *   {@link DatatypeConstants#GMONTH} or
  825        *   {@link DatatypeConstants#GDAY}.
  826        */
  827       public abstract QName getXMLSchemaType();
  828   
  829   	/**
  830   	 * <p>Returns a <code>String</code> representation of this <code>XMLGregorianCalendar</code> <code>Object</code>.</p>
  831   	 * 
  832   	 * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.</p>
  833   	 * 
  834   	 * @return A non-<code>null</code> valid <code>String</code> representation of this <code>XMLGregorianCalendar</code>.
  835   	 * 
  836        * @throws IllegalStateException if the combination of set fields
  837        *    does not match one of the eight defined XML Schema builtin date/time datatypes.
  838        * 
  839        * @see #toXMLFormat() 
  840   	 */
  841       public String toString() {
  842       	
  843       	return toXMLFormat();
  844       }
  845       
  846       /**
  847        * Validate instance by <code>getXMLSchemaType()</code> constraints.
  848        * @return true if data values are valid.
  849        */
  850       public abstract boolean isValid();
  851   
  852       /**
  853        * <p>Add <code>duration</code> to this instance.</p>
  854        * 
  855        * <p>The computation is specified in
  856        * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E,
  857        * <i>Adding durations to dateTimes</i>></a>.
  858        * <a href="#datetimefieldsmapping">date/time field mapping table</a>
  859        * defines the mapping from XML Schema 1.0 <code>dateTime</code> fields 
  860        * to this class' representation of those fields.</p>
  861        * 
  862        * @param duration Duration to add to this <code>XMLGregorianCalendar</code>.
  863        * 
  864        * @throws NullPointerException  when <code>duration</code> parameter is <code>null</code>.
  865        */
  866       public abstract void add(Duration duration);
  867   
  868       /**
  869        * <p>Convert this <code>XMLGregorianCalendar</code> to a {@link GregorianCalendar}.</p>
  870        * 
  871        * <p>When <code>this</code> instance has an undefined field, this
  872        * conversion relies on the <code>java.util.GregorianCalendar</code> default 
  873        * for its corresponding field. A notable difference between
  874        * XML Schema 1.0 date/time datatypes and <code>java.util.GregorianCalendar</code>
  875        * is that Timezone value is optional for date/time datatypes and it is
  876        * a required field for <code>java.util.GregorianCalendar</code>. See javadoc
  877        * for <code>java.util.TimeZone.getDefault()</code> on how the default
  878        * is determined. To explicitly specify the <code>TimeZone</code>
  879        * instance, see 
  880        * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.</p>
  881        * 
  882        * <table border="2" rules="all" cellpadding="2">
  883        *   <thead>
  884        *     <tr>
  885        *       <th align="center" colspan="2">
  886        *          Field by Field Conversion from this class to 
  887        *          <code>java.util.GregorianCalendar</code>
  888        *       </th>
  889        *     </tr>
  890        *   </thead>
  891        *   <tbody>
  892        *     <tr>
  893        *        <td><code>java.util.GregorianCalendar</code> field</td>
  894        *        <td><code>javax.xml.datatype.XMLGregorianCalendar</code> field</td>
  895        *     </tr>
  896        *     <tr>
  897        *       <td><code>ERA</code></td>
  898        *       <td>{@link #getEonAndYear()}<code>.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD</code></td>
  899        *     </tr>
  900        *     <tr>
  901        *       <td><code>YEAR</code></td>
  902        *       <td>{@link #getEonAndYear()}<code>.abs().intValue()</code><i>*</i></td>
  903        *     </tr>
  904        *     <tr>
  905        *       <td><code>MONTH</code></td>
  906        *       <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td>
  907        *     </tr>
  908        *     <tr>
  909        *       <td><code>DAY_OF_MONTH</code></td>
  910        *       <td>{@link #getDay()}</td>
  911        *     </tr>
  912        *     <tr>
  913        *       <td><code>HOUR_OF_DAY</code></td>
  914        *       <td>{@link #getHour()}</td>
  915        *     </tr>
  916        *     <tr>
  917        *       <td><code>MINUTE</code></td>
  918        *       <td>{@link #getMinute()}</td>
  919        *     </tr>
  920        *     <tr>
  921        *       <td><code>SECOND</code></td>
  922        *       <td>{@link #getSecond()}</td>
  923        *     </tr>
  924        *     <tr>
  925        *       <td><code>MILLISECOND</code></td>
  926        *       <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td>
  927        *     </tr>
  928        *     <tr>
  929        *       <td><code>GregorianCalendar.setTimeZone(TimeZone)</code></td>
  930        *       <td>{@link #getTimezone()} formatted into Custom timezone id</td>
  931        *     </tr>
  932        *   </tbody>
  933        * </table>
  934        * <i>*</i> designates possible loss of precision during the conversion due
  935        * to source datatype having higher precision than target datatype.
  936        * 
  937        * <p>To ensure consistency in conversion implementations, the new
  938        * <code>GregorianCalendar</code> should be instantiated in following
  939        * manner.
  940        * <ul>
  941        *   <li>Using <code>timeZone</code> value as defined above, create a new 
  942        * <code>java.util.GregorianCalendar(timeZone,Locale.getDefault())</code>.
  943        *   </li>
  944        *   <li>Initialize all GregorianCalendar fields by calling {(@link GegorianCalendar#clear()}.</li>
  945        *   <li>Obtain a pure Gregorian Calendar by invoking
  946        *   <code>GregorianCalendar.setGregorianChange(
  947        *   new Date(Long.MIN_VALUE))</code>.</li>
  948        *   <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, 
  949        *       MINUTE, SECOND and MILLISECOND are set using the method 
  950        *       <code>Calendar.set(int,int)</code></li>
  951        * </ul>
  952        * </p>
  953        * 
  954        * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
  955        */
  956       public abstract GregorianCalendar toGregorianCalendar();
  957   
  958       /**
  959        * <p>Convert this <code>XMLGregorianCalendar</code> along with provided parameters
  960        * to a {@link GregorianCalendar} instance.</p>
  961        * 
  962        * <p> Since XML Schema 1.0 date/time datetypes has no concept of
  963        * timezone ids or daylight savings timezone ids, this conversion operation
  964        * allows the user to explicitly specify one with
  965        * <code>timezone</code> parameter.</p>
  966        * 
  967        * <p>To compute the return value's <code>TimeZone</code> field,
  968        * <ul>
  969        * <li>when parameter <code>timeZone</code> is non-null, 
  970        * it is the timezone field.</li>
  971        * <li>else when <code>this.getTimezone() != FIELD_UNDEFINED</code>,
  972        * create a <code>java.util.TimeZone</code> with a custom timezone id 
  973        * using the <code>this.getTimezone()</code>.</li>
  974        * <li>else when <code>defaults.getTimezone() != FIELD_UNDEFINED</code>, 
  975        * create a <code>java.util.TimeZone</code> with a custom timezone id 
  976        * using <code>defaults.getTimezone()</code>.</li>
  977        * <li>else use the <code>GregorianCalendar</code> default timezone value 
  978        * for the host is defined as specified by 
  979        * <code>java.util.TimeZone.getDefault()</code>.</li></ul></p>
  980        * 
  981        * <p>To ensure consistency in conversion implementations, the new
  982        * <code>GregorianCalendar</code> should be instantiated in following
  983        * manner.
  984        * <ul>
  985        *   <li>Create a new <code>java.util.GregorianCalendar(TimeZone, 
  986        *       Locale)</code> with TimeZone set as specified above and the
  987        *       <code>Locale</code> parameter. 
  988        *   </li>
  989        *   <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li>
  990        *   <li>Obtain a pure Gregorian Calendar by invoking
  991        *   <code>GregorianCalendar.setGregorianChange(
  992        *   new Date(Long.MIN_VALUE))</code>.</li>
  993        *   <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, 
  994        *       MINUTE, SECOND and MILLISECOND are set using the method 
  995        *       <code>Calendar.set(int,int)</code></li>
  996        * </ul></p>
  997        * 
  998        * @param timezone provide Timezone. <code>null</code> is a legal value.
  999        * @param aLocale  provide explicit Locale. Use default GregorianCalendar locale if
 1000        *                 value is <code>null</code>.
 1001        * @param defaults provide default field values to use when corresponding
 1002        *                 field for this instance is FIELD_UNDEFINED or null. 
 1003        *                 If <code>defaults</code>is <code>null</code> or a field
 1004        *                 within the specified <code>defaults</code> is undefined,
 1005        *                 just use <code>java.util.GregorianCalendar</code> defaults.
 1006        * @return a java.util.GregorianCalendar conversion of this instance.
 1007        */
 1008       public abstract GregorianCalendar toGregorianCalendar(
 1009       	java.util.TimeZone timezone, 
 1010   		java.util.Locale aLocale,
 1011   		XMLGregorianCalendar defaults);
 1012   
 1013       /**
 1014        * <p>Returns a <code>java.util.TimeZone</code> for this class.</p>
 1015        * 
 1016        * <p>If timezone field is defined for this instance, 
 1017        * returns TimeZone initialized with custom timezone id
 1018        * of zoneoffset. If timezone field is undefined, 
 1019        * try the defaultZoneoffset that was passed in. 
 1020        * If defaultZoneoffset is FIELD_UNDEFINED, return
 1021        * default timezone for this host.
 1022        * (Same default as java.util.GregorianCalendar).</p>
 1023        *
 1024        * @param defaultZoneoffset default zoneoffset if this zoneoffset is 
 1025        * {@link DatatypeConstants#FIELD_UNDEFINED}.
 1026        *
 1027        * @return TimeZone for this.
 1028        */
 1029       public abstract TimeZone getTimeZone(int defaultZoneoffset);
 1030   
 1031       /**
 1032        * <p>Creates and returns a copy of this object.</p>
 1033        * 
 1034        * @return copy of this <code>Object</code>
 1035        */
 1036       public abstract Object clone();
 1037   }

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