0001 /*
0002 * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package javax.xml.datatype;
0027
0028 import javax.xml.namespace.QName;
0029 import java.math.BigDecimal;
0030 import java.math.BigInteger;
0031 import java.util.TimeZone;
0032 import java.util.GregorianCalendar;
0033
0034 /**
0035 * <p>Representation for W3C XML Schema 1.0 date/time datatypes.
0036 * Specifically, these date/time datatypes are
0037 * {@link DatatypeConstants#DATETIME},
0038 * {@link DatatypeConstants#TIME},
0039 * {@link DatatypeConstants#DATE},
0040 * {@link DatatypeConstants#GYEARMONTH},
0041 * {@link DatatypeConstants#GMONTHDAY},
0042 * {@link DatatypeConstants#GYEAR},
0043 * {@link DatatypeConstants#GMONTH}, and
0044 * {@link DatatypeConstants#GDAY}
0045 * defined in the XML Namespace
0046 * <code>"http://www.w3.org/2001/XMLSchema"</code>.
0047 * These datatypes are normatively defined in
0048 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.</p>
0049 *
0050 * <p>The table below defines the mapping between XML Schema 1.0
0051 * date/time datatype fields and this class' fields. It also summarizes
0052 * the value constraints for the date and time fields defined in
0053 * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
0054 * <i>ISO 8601 Date and Time Formats</i></a>.</p>
0055 *
0056 * <a name="datetimefieldmapping"/>
0057 * <table border="2" rules="all" cellpadding="2">
0058 * <thead>
0059 * <tr>
0060 * <th align="center" colspan="3">
0061 * Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation
0062 * </th>
0063 * </tr>
0064 * </thead>
0065 * <tbody>
0066 * <tr>
0067 * <th>XML Schema 1.0<br/>
0068 * datatype<br/>
0069 * field</th>
0070 * <th>Related<br/>XMLGregorianCalendar<br/>Accessor(s)</th>
0071 * <th>Value Range</th>
0072 * </tr>
0073 * <tr>
0074 * <td><a name="datetimefield-year"/>year</td>
0075 * <td> {@link #getYear()} + {@link #getEon()} or<br/>
0076 * {@link #getEonAndYear}
0077 * </td>
0078 * <td> <code>getYear()</code> is a value between -(10^9-1) to (10^9)-1
0079 * or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
0080 * {@link #getEon()} is high order year value in billion of years.<br/>
0081 * <code>getEon()</code> has values greater than or equal to (10^9) or less than or equal to -(10^9).
0082 * A value of null indicates field is undefined.</br>
0083 * 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
0084 * will be a valid lexical value in a future version of XML Schema,
0085 * this class allows the year field to be set to zero. Otherwise,
0086 * the year field value is handled exactly as described
0087 * in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0
0088 * validation does not allow for the year field to have a value of zero.
0089 * </td>
0090 * </tr>
0091 * <tr>
0092 * <td><a name="datetimefield-month"/>month</td>
0093 * <td> {@link #getMonth()} </td>
0094 * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
0095 * </tr>
0096 * <tr>
0097 * <td><a name="datetimefield-day"/>day</td>
0098 * <td> {@link #getDay()} </td>
0099 * <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
0100 * The normative value constraint stated relative to month
0101 * 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>.
0102 * </td>
0103 * </tr>
0104 * <tr>
0105 * <td><a name="datetimefield-hour"/>hour</td>
0106 * <td>{@link #getHour()}</td>
0107 * <td>
0108 * 0 to 24 or {@link DatatypeConstants#FIELD_UNDEFINED}.
0109 * For a value of 24, the minute and second field must be zero per
0110 * <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">XML Schema Errata</a>.
0111 * </td>
0112 * </tr>
0113 * <tr>
0114 * <td><a name="datetimefield-minute"/>minute</td>
0115 * <td> {@link #getMinute()} </td>
0116 * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
0117 * </tr>
0118 * <tr>
0119 * <td><a name="datetimefield-second"/>second</td>
0120 * <td>
0121 * {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br/>
0122 * {@link #getSecond()} + {@link #getFractionalSecond()}
0123 * </td>
0124 * <td>
0125 * {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br/>
0126 * <i>(Note: 60 only allowable for leap second.)</i><br/>
0127 * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when
0128 * the {@link #getSecond()} is defined.<br/>
0129 * <code>FractionalSecond</code> is optional and has a value of <code>null</code> when it is undefined.<br />
0130 * {@link #getMillisecond()} is the convenience
0131 * millisecond precision of value of {@link #getFractionalSecond()}.
0132 * </td>
0133 * </tr>
0134 * <tr>
0135 * <td><a name="datetimefield-timezone"/>timezone</td>
0136 * <td> {@link #getTimezone()} </td>
0137 * <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
0138 * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
0139 * </td>
0140 * </tr>
0141 * </tbody>
0142 * </table>
0143 *
0144 * <p>All maximum value space constraints listed for the fields in the table
0145 * above are checked by factory methods, @{link DatatypeFactory},
0146 * setter methods and parse methods of
0147 * this class. <code>IllegalArgumentException</code> is thrown when a
0148 * parameter's value is outside the value constraint for the field or
0149 * if the composite
0150 * values constitute an invalid XMLGregorianCalendar instance (for example, if
0151 * the 31st of June is specified).
0152 * </p>
0153 *
0154 * <p>The following operations are defined for this class:
0155 * <ul>
0156 * <li>accessors/mutators for independent date/time fields</li>
0157 * <li>conversion between this class and W3C XML Schema 1.0 lexical representation,
0158 * {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}</li>
0159 * <li>conversion between this class and {@link GregorianCalendar},
0160 * {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)},
0161 * {@link DatatypeFactory}</li>
0162 * <li>partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}</li>
0163 * <li>{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.</li>
0164 * <li>addition operation with {@link Duration}
0165 * instance as defined in <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">
0166 * W3C XML Schema 1.0 Part 2, Appendix E, <i>Adding durations to dateTimes</i></a>.
0167 * </li>
0168 * </ul>
0169 * </p>
0170 *
0171 * @author <a href="mailto:Joseph.Fialli@Sun.com">Joseph Fialli</a>
0172 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
0173 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
0174 * @author <a href="mailto:Sunitha.Reddy@Sun.com">Sunitha Reddy</a>
0175 * @version $Revision: 1.7 $, $Date: 2006/01/12 18:53:55 $
0176 * @see Duration
0177 * @see DatatypeFactory
0178 * @since 1.5
0179 */
0180
0181 public abstract class XMLGregorianCalendar implements Cloneable {
0182
0183 /**
0184 * Default no-arg constructor.
0185 *
0186 * <p>Note: Always use the {@link DatatypeFactory} to
0187 * construct an instance of <code>XMLGregorianCalendar</code>.
0188 * The constructor on this class cannot be guaranteed to
0189 * produce an object with a consistent state and may be
0190 * removed in the future.</p>
0191 */
0192 public XMLGregorianCalendar() {
0193 }
0194
0195 /**
0196 * <p>Unset all fields to undefined.</p>
0197 *
0198 * <p>Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields
0199 * to null.</p>
0200 */
0201 public abstract void clear();
0202
0203 /**
0204 * <p>Reset this <code>XMLGregorianCalendar</code> to its original values.</p>
0205 *
0206 * <p><code>XMLGregorianCalendar</code> is reset to the same values as when it was created with
0207 * {@link DatatypeFactory#newXMLGregorianCalendar()},
0208 * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)},
0209 * {@link DatatypeFactory#newXMLGregorianCalendar(
0210 * BigInteger year,
0211 * int month,
0212 * int day,
0213 * int hour,
0214 * int minute,
0215 * int second,
0216 * BigDecimal fractionalSecond,
0217 * int timezone)},
0218 * {@link DatatypeFactory#newXMLGregorianCalendar(
0219 * int year,
0220 * int month,
0221 * int day,
0222 * int hour,
0223 * int minute,
0224 * int second,
0225 * int millisecond,
0226 * int timezone)},
0227 * {@link DatatypeFactory#newXMLGregorianCalendar(GregorianCalendar cal)},
0228 * {@link DatatypeFactory#newXMLGregorianCalendarDate(
0229 * int year,
0230 * int month,
0231 * int day,
0232 * int timezone)},
0233 * {@link DatatypeFactory#newXMLGregorianCalendarTime(
0234 * int hours,
0235 * int minutes,
0236 * int seconds,
0237 * int timezone)},
0238 * {@link DatatypeFactory#newXMLGregorianCalendarTime(
0239 * int hours,
0240 * int minutes,
0241 * int seconds,
0242 * BigDecimal fractionalSecond,
0243 * int timezone)} or
0244 * {@link DatatypeFactory#newXMLGregorianCalendarTime(
0245 * int hours,
0246 * int minutes,
0247 * int seconds,
0248 * int milliseconds,
0249 * int timezone)}.
0250 * </p>
0251 *
0252 * <p><code>reset()</code> is designed to allow the reuse of existing <code>XMLGregorianCalendar</code>s
0253 * thus saving resources associated with the creation of new <code>XMLGregorianCalendar</code>s.</p>
0254 */
0255 public abstract void reset();
0256
0257 /**
0258 * <p>Set low and high order component of XSD <code>dateTime</code> year field.</p>
0259 *
0260 * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p>
0261 *
0262 * @param year value constraints summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
0263 *
0264 * @throws IllegalArgumentException if <code>year</code> parameter is
0265 * outside value constraints for the field as specified in
0266 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0267 */
0268 public abstract void setYear(BigInteger year);
0269
0270 /**
0271 * <p>Set year of XSD <code>dateTime</code> year field.</p>
0272 *
0273 * <p>Unset this field by invoking the setter with a parameter value of
0274 * {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0275 *
0276 * <p>Note: if the absolute value of the <code>year</code> parameter
0277 * is less than 10^9, the eon component of the XSD year field is set to
0278 * <code>null</code> by this method.</p>
0279 *
0280 * @param year value constraints are summarized in <a href="#datetimefield-year">year field of date/time field mapping table</a>.
0281 * If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to <code>null</code>.
0282 */
0283 public abstract void setYear(int year);
0284
0285 /**
0286 * <p>Set month.</p>
0287 *
0288 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0289 *
0290 * @param month value constraints summarized in <a href="#datetimefield-month">month field of date/time field mapping table</a>.
0291 *
0292 * @throws IllegalArgumentException if <code>month</code> parameter is
0293 * outside value constraints for the field as specified in
0294 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0295 */
0296 public abstract void setMonth(int month);
0297
0298 /**
0299 * <p>Set days in month.</p>
0300 *
0301 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0302 *
0303 * @param day value constraints summarized in <a href="#datetimefield-day">day field of date/time field mapping table</a>.
0304 *
0305 * @throws IllegalArgumentException if <code>day</code> parameter is
0306 * outside value constraints for the field as specified in
0307 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0308 */
0309 public abstract void setDay(int day);
0310
0311 /**
0312 * <p>Set the number of minutes in the timezone offset.</p>
0313 *
0314 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0315 *
0316 * @param offset value constraints summarized in <a href="#datetimefield-timezone">
0317 * timezone field of date/time field mapping table</a>.
0318 *
0319 * @throws IllegalArgumentException if <code>offset</code> parameter is
0320 * outside value constraints for the field as specified in
0321 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0322 */
0323 public abstract void setTimezone(int offset);
0324
0325 /**
0326 * <p>Set time as one unit.</p>
0327 *
0328 * @param hour value constraints are summarized in
0329 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
0330 * @param minute value constraints are summarized in
0331 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
0332 * @param second value constraints are summarized in
0333 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
0334 *
0335 * @see #setTime(int, int, int, BigDecimal)
0336 *
0337 * @throws IllegalArgumentException if any parameter is
0338 * outside value constraints for the field as specified in
0339 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0340 */
0341 public void setTime(int hour, int minute, int second) {
0342
0343 setTime(hour, minute, second, null // fractional
0344 );
0345 }
0346
0347 /**
0348 * <p>Set hours.</p>
0349 *
0350 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0351 *
0352 * @param hour value constraints summarized in <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
0353 *
0354 * @throws IllegalArgumentException if <code>hour</code> parameter is outside value constraints for the field as specified in
0355 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0356 */
0357 public abstract void setHour(int hour);
0358
0359 /**
0360 * <p>Set minutes.</p>
0361 *
0362 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0363 *
0364 * @param minute value constraints summarized in <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
0365 *
0366 * @throws IllegalArgumentException if <code>minute</code> parameter is outside value constraints for the field as specified in
0367 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0368 */
0369 public abstract void setMinute(int minute);
0370
0371 /**
0372 * <p>Set seconds.</p>
0373 *
0374 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0375 *
0376 * @param second value constraints summarized in <a href="#datetimefield-second">second field of date/time field mapping table</a>.
0377 *
0378 * @throws IllegalArgumentException if <code>second</code> parameter is outside value constraints for the field as specified in
0379 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0380 */
0381 public abstract void setSecond(int second);
0382
0383 /**
0384 * <p>Set milliseconds.</p>
0385 *
0386 * <p>Unset this field by invoking the setter with a parameter value of {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0387 *
0388 * @param millisecond value constraints summarized in
0389 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
0390 *
0391 * @throws IllegalArgumentException if <code>millisecond</code> parameter is outside value constraints for the field as specified
0392 * in <a href="#datetimefieldmapping">date/time field mapping table</a>.
0393 */
0394 public abstract void setMillisecond(int millisecond);
0395
0396 /**
0397 * <p>Set fractional seconds.</p>
0398 *
0399 * <p>Unset this field by invoking the setter with a parameter value of <code>null</code>.</p>
0400 *
0401 * @param fractional value constraints summarized in
0402 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
0403 *
0404 * @throws IllegalArgumentException if <code>fractional</code> parameter is outside value constraints for the field as specified
0405 * in <a href="#datetimefieldmapping">date/time field mapping table</a>.
0406 */
0407 public abstract void setFractionalSecond(BigDecimal fractional);
0408
0409 /**
0410 * <p>Set time as one unit, including the optional infinite precision
0411 * fractional seconds.</p>
0412 *
0413 * @param hour value constraints are summarized in
0414 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
0415 * @param minute value constraints are summarized in
0416 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
0417 * @param second value constraints are summarized in
0418 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
0419 * @param fractional value of <code>null</code> indicates this optional
0420 * field is not set.
0421 *
0422 * @throws IllegalArgumentException if any parameter is
0423 * outside value constraints for the field as specified in
0424 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0425 */
0426 public void setTime(int hour, int minute, int second,
0427 BigDecimal fractional) {
0428
0429 setHour(hour);
0430 setMinute(minute);
0431 setSecond(second);
0432 setFractionalSecond(fractional);
0433 }
0434
0435 /**
0436 * <p>Set time as one unit, including optional milliseconds.</p>
0437 *
0438 * @param hour value constraints are summarized in
0439 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.
0440 * @param minute value constraints are summarized in
0441 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.
0442 * @param second value constraints are summarized in
0443 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.
0444 * @param millisecond value of {@link DatatypeConstants#FIELD_UNDEFINED} indicates this
0445 * optional field is not set.
0446 *
0447 * @throws IllegalArgumentException if any parameter is
0448 * outside value constraints for the field as specified in
0449 * <a href="#datetimefieldmapping">date/time field mapping table</a>.
0450 */
0451 public void setTime(int hour, int minute, int second,
0452 int millisecond) {
0453
0454 setHour(hour);
0455 setMinute(minute);
0456 setSecond(second);
0457 setMillisecond(millisecond);
0458 }
0459
0460 /**
0461 * <p>Return high order component for XML Schema 1.0 dateTime datatype field for
0462 * <code>year</code>.
0463 * <code>null</code> if this optional part of the year field is not defined.</p>
0464 *
0465 * <p>Value constraints for this value are summarized in
0466 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
0467 * @return eon of this <code>XMLGregorianCalendar</code>. The value
0468 * returned is an integer multiple of 10^9.
0469 *
0470 * @see #getYear()
0471 * @see #getEonAndYear()
0472 */
0473 public abstract BigInteger getEon();
0474
0475 /**
0476 * <p>Return low order component for XML Schema 1.0 dateTime datatype field for
0477 * <code>year</code> or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0478 *
0479 * <p>Value constraints for this value are summarized in
0480 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
0481 *
0482 * @return year of this <code>XMLGregorianCalendar</code>.
0483 *
0484 * @see #getEon()
0485 * @see #getEonAndYear()
0486 */
0487 public abstract int getYear();
0488
0489 /**
0490 * <p>Return XML Schema 1.0 dateTime datatype field for
0491 * <code>year</code>.</p>
0492 *
0493 * <p>Value constraints for this value are summarized in
0494 * <a href="#datetimefield-year">year field of date/time field mapping table</a>.</p>
0495 *
0496 * @return sum of <code>eon</code> and <code>BigInteger.valueOf(year)</code>
0497 * when both fields are defined. When only <code>year</code> is defined,
0498 * return it. When both <code>eon</code> and <code>year</code> are not
0499 * defined, return <code>null</code>.
0500 *
0501 * @see #getEon()
0502 * @see #getYear()
0503 */
0504 public abstract BigInteger getEonAndYear();
0505
0506 /**
0507 * <p>Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0508 *
0509 * <p>Value constraints for this value are summarized in
0510 * <a href="#datetimefield-month">month field of date/time field mapping table</a>.</p>
0511 *
0512 * @return year of this <code>XMLGregorianCalendar</code>.
0513 *
0514 */
0515 public abstract int getMonth();
0516
0517 /**
0518 * Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0519 *
0520 * <p>Value constraints for this value are summarized in
0521 * <a href="#datetimefield-day">day field of date/time field mapping table</a>.</p>
0522 *
0523 * @see #setDay(int)
0524 */
0525 public abstract int getDay();
0526
0527 /**
0528 * Return timezone offset in minutes or
0529 * {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined.
0530 *
0531 * <p>Value constraints for this value are summarized in
0532 * <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>.</p>
0533 *
0534 * @see #setTimezone(int)
0535 */
0536 public abstract int getTimezone();
0537
0538 /**
0539 * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}.
0540 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
0541 *
0542 * <p>Value constraints for this value are summarized in
0543 * <a href="#datetimefield-hour">hour field of date/time field mapping table</a>.</p>
0544 * @see #setTime(int, int, int)
0545 */
0546 public abstract int getHour();
0547
0548 /**
0549 * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0550 * Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
0551 *
0552 * <p>Value constraints for this value are summarized in
0553 * <a href="#datetimefield-minute">minute field of date/time field mapping table</a>.</p>
0554 * @see #setTime(int, int, int)
0555 */
0556 public abstract int getMinute();
0557
0558 /**
0559 * <p>Return seconds or {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0560 *
0561 * <p>Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined.
0562 * When this field is not defined, the optional xs:dateTime
0563 * fractional seconds field, represented by
0564 * {@link #getFractionalSecond()} and {@link #getMillisecond()},
0565 * must not be defined.</p>
0566 *
0567 * <p>Value constraints for this value are summarized in
0568 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
0569 *
0570 * @return Second of this <code>XMLGregorianCalendar</code>.
0571 *
0572 * @see #getFractionalSecond()
0573 * @see #getMillisecond()
0574 * @see #setTime(int, int, int)
0575 */
0576 public abstract int getSecond();
0577
0578 /**
0579 * <p>Return millisecond precision of {@link #getFractionalSecond()}.</p>
0580 *
0581 * <p>This method represents a convenience accessor to infinite
0582 * precision fractional second value returned by
0583 * {@link #getFractionalSecond()}. The returned value is the rounded
0584 * down to milliseconds value of
0585 * {@link #getFractionalSecond()}. When {@link #getFractionalSecond()}
0586 * returns <code>null</code>, this method must return
0587 * {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0588 *
0589 * <p>Value constraints for this value are summarized in
0590 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
0591 *
0592 * @return Millisecond of this <code>XMLGregorianCalendar</code>.
0593 *
0594 * @see #getFractionalSecond()
0595 * @see #setTime(int, int, int)
0596 */
0597 public int getMillisecond() {
0598
0599 BigDecimal fractionalSeconds = getFractionalSecond();
0600
0601 // is field undefined?
0602 if (fractionalSeconds == null) {
0603 return DatatypeConstants.FIELD_UNDEFINED;
0604 }
0605
0606 return getFractionalSecond().movePointRight(3).intValue();
0607 }
0608
0609 /**
0610 * <p>Return fractional seconds.</p>
0611 *
0612 * <p><code>null</code> is returned when this optional field is not defined.</p>
0613 *
0614 * <p>Value constraints are detailed in
0615 * <a href="#datetimefield-second">second field of date/time field mapping table</a>.</p>
0616 *
0617 * <p>This optional field can only have a defined value when the
0618 * xs:dateTime second field, represented by {@link #getSecond()},
0619 * does not return {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
0620 *
0621 * @return fractional seconds of this <code>XMLGregorianCalendar</code>.
0622 *
0623 * @see #getSecond()
0624 * @see #setTime(int, int, int, BigDecimal)
0625 */
0626 public abstract BigDecimal getFractionalSecond();
0627
0628 // comparisons
0629 /**
0630 * <p>Compare two instances of W3C XML Schema 1.0 date/time datatypes
0631 * according to partial order relation defined in
0632 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">W3C XML Schema 1.0 Part 2, Section 3.2.7.3,
0633 * <i>Order relation on dateTime</i></a>.</p>
0634 *
0635 * <p><code>xsd:dateTime</code> datatype field mapping to accessors of
0636 * this class are defined in
0637 * <a href="#datetimefieldmapping">date/time field mapping table</a>.</p>
0638 *
0639 * @param xmlGregorianCalendar Instance of <code>XMLGregorianCalendar</code> to compare
0640 *
0641 * @return The relationship between <code>this</code> <code>XMLGregorianCalendar</code> and
0642 * the specified <code>xmlGregorianCalendar</code> as
0643 * {@link DatatypeConstants#LESSER},
0644 * {@link DatatypeConstants#EQUAL},
0645 * {@link DatatypeConstants#GREATER} or
0646 * {@link DatatypeConstants#INDETERMINATE}.
0647 *
0648 * @throws NullPointerException if <code>xmlGregorianCalendar</code> is null.
0649 */
0650 public abstract int compare(
0651 XMLGregorianCalendar xmlGregorianCalendar);
0652
0653 /**
0654 * <p>Normalize this instance to UTC.</p>
0655 *
0656 * <p>2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z</p>
0657 * <p>Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).</p>
0658 *
0659 * @return <code>this</code> <code>XMLGregorianCalendar</code> normalized to UTC.
0660 */
0661 public abstract XMLGregorianCalendar normalize();
0662
0663 /**
0664 * <p>Compares this calendar to the specified object. The result is
0665 * <code>true</code> if and only if the argument is not null and is an
0666 * <code>XMLGregorianCalendar</code> object that represents the same
0667 * instant in time as this object.</p>
0668 *
0669 * @param obj to compare.
0670 *
0671 * @return <code>true</code> when <code>obj</code> is an instance of
0672 * <code>XMLGregorianCalendar</code> and
0673 * {@link #compare(XMLGregorianCalendar obj)}
0674 * returns {@link DatatypeConstants#EQUAL},
0675 * otherwise <code>false</code>.
0676 */
0677 public boolean equals(Object obj) {
0678
0679 if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
0680 return false;
0681 }
0682 return compare((XMLGregorianCalendar) obj) == DatatypeConstants.EQUAL;
0683 }
0684
0685 /**
0686 * <p>Returns a hash code consistent with the definition of the equals method.</p>
0687 *
0688 * @return hash code of this object.
0689 */
0690 public int hashCode() {
0691
0692 // Following two dates compare to EQUALS since in different timezones.
0693 // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
0694 //
0695 // Must ensure both instances generate same hashcode by normalizing
0696 // this to UTC timezone.
0697 int timezone = getTimezone();
0698 if (timezone == DatatypeConstants.FIELD_UNDEFINED) {
0699 timezone = 0;
0700 }
0701 XMLGregorianCalendar gc = this ;
0702 if (timezone != 0) {
0703 gc = this .normalize();
0704 }
0705 return gc.getYear() + gc.getMonth() + gc.getDay()
0706 + gc.getHour() + gc.getMinute() + gc.getSecond();
0707 }
0708
0709 /**
0710 * <p>Return the lexical representation of <code>this</code> instance.
0711 * The format is specified in
0712 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
0713 * <i>Lexical Representation</i>".</a></p>
0714 *
0715 * <p>Specific target lexical representation format is determined by
0716 * {@link #getXMLSchemaType()}.</p>
0717 *
0718 * @return XML, as <code>String</code>, representation of this <code>XMLGregorianCalendar</code>
0719 *
0720 * @throws IllegalStateException if the combination of set fields
0721 * does not match one of the eight defined XML Schema builtin date/time datatypes.
0722 */
0723 public abstract String toXMLFormat();
0724
0725 /**
0726 * <p>Return the name of the XML Schema date/time type that this instance
0727 * maps to. Type is computed based on fields that are set.</p>
0728 *
0729 * <table border="2" rules="all" cellpadding="2">
0730 * <thead>
0731 * <tr>
0732 * <th align="center" colspan="7">
0733 * Required fields for XML Schema 1.0 Date/Time Datatypes.<br/>
0734 * <i>(timezone is optional for all date/time datatypes)</i>
0735 * </th>
0736 * </tr>
0737 * </thead>
0738 * <tbody>
0739 * <tr>
0740 * <td>Datatype</td>
0741 * <td>year</td>
0742 * <td>month</td>
0743 * <td>day</td>
0744 * <td>hour</td>
0745 * <td>minute</td>
0746 * <td>second</td>
0747 * </tr>
0748 * <tr>
0749 * <td>{@link DatatypeConstants#DATETIME}</td>
0750 * <td>X</td>
0751 * <td>X</td>
0752 * <td>X</td>
0753 * <td>X</td>
0754 * <td>X</td>
0755 * <td>X</td>
0756 * </tr>
0757 * <tr>
0758 * <td>{@link DatatypeConstants#DATE}</td>
0759 * <td>X</td>
0760 * <td>X</td>
0761 * <td>X</td>
0762 * <td></td>
0763 * <td></td>
0764 * <td></td>
0765 * </tr>
0766 * <tr>
0767 * <td>{@link DatatypeConstants#TIME}</td>
0768 * <td></td>
0769 * <td></td>
0770 * <td></td>
0771 * <td>X</td>
0772 * <td>X</td>
0773 * <td>X</td>
0774 * </tr>
0775 * <tr>
0776 * <td>{@link DatatypeConstants#GYEARMONTH}</td>
0777 * <td>X</td>
0778 * <td>X</td>
0779 * <td></td>
0780 * <td></td>
0781 * <td></td>
0782 * <td></td>
0783 * </tr>
0784 * <tr>
0785 * <td>{@link DatatypeConstants#GMONTHDAY}</td>
0786 * <td></td>
0787 * <td>X</td>
0788 * <td>X</td>
0789 * <td></td>
0790 * <td></td>
0791 * <td></td>
0792 * </tr>
0793 * <tr>
0794 * <td>{@link DatatypeConstants#GYEAR}</td>
0795 * <td>X</td>
0796 * <td></td>
0797 * <td></td>
0798 * <td></td>
0799 * <td></td>
0800 * <td></td>
0801 * </tr>
0802 * <tr>
0803 * <td>{@link DatatypeConstants#GMONTH}</td>
0804 * <td></td>
0805 * <td>X</td>
0806 * <td></td>
0807 * <td></td>
0808 * <td></td>
0809 * <td></td>
0810 * </tr>
0811 * <tr>
0812 * <td>{@link DatatypeConstants#GDAY}</td>
0813 * <td></td>
0814 * <td></td>
0815 * <td>X</td>
0816 * <td></td>
0817 * <td></td>
0818 * <td></td>
0819 * </tr>
0820 * </tbody>
0821 * </table>
0822 *
0823 * @throws java.lang.IllegalStateException if the combination of set fields
0824 * does not match one of the eight defined XML Schema builtin
0825 * date/time datatypes.
0826 * @return One of the following class constants:
0827 * {@link DatatypeConstants#DATETIME},
0828 * {@link DatatypeConstants#TIME},
0829 * {@link DatatypeConstants#DATE},
0830 * {@link DatatypeConstants#GYEARMONTH},
0831 * {@link DatatypeConstants#GMONTHDAY},
0832 * {@link DatatypeConstants#GYEAR},
0833 * {@link DatatypeConstants#GMONTH} or
0834 * {@link DatatypeConstants#GDAY}.
0835 */
0836 public abstract QName getXMLSchemaType();
0837
0838 /**
0839 * <p>Returns a <code>String</code> representation of this <code>XMLGregorianCalendar</code> <code>Object</code>.</p>
0840 *
0841 * <p>The result is a lexical representation generated by {@link #toXMLFormat()}.</p>
0842 *
0843 * @return A non-<code>null</code> valid <code>String</code> representation of this <code>XMLGregorianCalendar</code>.
0844 *
0845 * @throws IllegalStateException if the combination of set fields
0846 * does not match one of the eight defined XML Schema builtin date/time datatypes.
0847 *
0848 * @see #toXMLFormat()
0849 */
0850 public String toString() {
0851
0852 return toXMLFormat();
0853 }
0854
0855 /**
0856 * Validate instance by <code>getXMLSchemaType()</code> constraints.
0857 * @return true if data values are valid.
0858 */
0859 public abstract boolean isValid();
0860
0861 /**
0862 * <p>Add <code>duration</code> to this instance.</p>
0863 *
0864 * <p>The computation is specified in
0865 * <a href="http://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes">XML Schema 1.0 Part 2, Appendix E,
0866 * <i>Adding durations to dateTimes</i>></a>.
0867 * <a href="#datetimefieldmapping">date/time field mapping table</a>
0868 * defines the mapping from XML Schema 1.0 <code>dateTime</code> fields
0869 * to this class' representation of those fields.</p>
0870 *
0871 * @param duration Duration to add to this <code>XMLGregorianCalendar</code>.
0872 *
0873 * @throws NullPointerException when <code>duration</code> parameter is <code>null</code>.
0874 */
0875 public abstract void add(Duration duration);
0876
0877 /**
0878 * <p>Convert this <code>XMLGregorianCalendar</code> to a {@link GregorianCalendar}.</p>
0879 *
0880 * <p>When <code>this</code> instance has an undefined field, this
0881 * conversion relies on the <code>java.util.GregorianCalendar</code> default
0882 * for its corresponding field. A notable difference between
0883 * XML Schema 1.0 date/time datatypes and <code>java.util.GregorianCalendar</code>
0884 * is that Timezone value is optional for date/time datatypes and it is
0885 * a required field for <code>java.util.GregorianCalendar</code>. See javadoc
0886 * for <code>java.util.TimeZone.getDefault()</code> on how the default
0887 * is determined. To explicitly specify the <code>TimeZone</code>
0888 * instance, see
0889 * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.</p>
0890 *
0891 * <table border="2" rules="all" cellpadding="2">
0892 * <thead>
0893 * <tr>
0894 * <th align="center" colspan="2">
0895 * Field by Field Conversion from this class to
0896 * <code>java.util.GregorianCalendar</code>
0897 * </th>
0898 * </tr>
0899 * </thead>
0900 * <tbody>
0901 * <tr>
0902 * <td><code>java.util.GregorianCalendar</code> field</td>
0903 * <td><code>javax.xml.datatype.XMLGregorianCalendar</code> field</td>
0904 * </tr>
0905 * <tr>
0906 * <td><code>ERA</code></td>
0907 * <td>{@link #getEonAndYear()}<code>.signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD</code></td>
0908 * </tr>
0909 * <tr>
0910 * <td><code>YEAR</code></td>
0911 * <td>{@link #getEonAndYear()}<code>.abs().intValue()</code><i>*</i></td>
0912 * </tr>
0913 * <tr>
0914 * <td><code>MONTH</code></td>
0915 * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td>
0916 * </tr>
0917 * <tr>
0918 * <td><code>DAY_OF_MONTH</code></td>
0919 * <td>{@link #getDay()}</td>
0920 * </tr>
0921 * <tr>
0922 * <td><code>HOUR_OF_DAY</code></td>
0923 * <td>{@link #getHour()}</td>
0924 * </tr>
0925 * <tr>
0926 * <td><code>MINUTE</code></td>
0927 * <td>{@link #getMinute()}</td>
0928 * </tr>
0929 * <tr>
0930 * <td><code>SECOND</code></td>
0931 * <td>{@link #getSecond()}</td>
0932 * </tr>
0933 * <tr>
0934 * <td><code>MILLISECOND</code></td>
0935 * <td>get millisecond order from {@link #getFractionalSecond()}<i>*</i> </td>
0936 * </tr>
0937 * <tr>
0938 * <td><code>GregorianCalendar.setTimeZone(TimeZone)</code></td>
0939 * <td>{@link #getTimezone()} formatted into Custom timezone id</td>
0940 * </tr>
0941 * </tbody>
0942 * </table>
0943 * <i>*</i> designates possible loss of precision during the conversion due
0944 * to source datatype having higher precision than target datatype.
0945 *
0946 * <p>To ensure consistency in conversion implementations, the new
0947 * <code>GregorianCalendar</code> should be instantiated in following
0948 * manner.
0949 * <ul>
0950 * <li>Using <code>timeZone</code> value as defined above, create a new
0951 * <code>java.util.GregorianCalendar(timeZone,Locale.getDefault())</code>.
0952 * </li>
0953 * <li>Initialize all GregorianCalendar fields by calling {@link java.util.GregorianCalendar#clear()}.</li>
0954 * <li>Obtain a pure Gregorian Calendar by invoking
0955 * <code>GregorianCalendar.setGregorianChange(
0956 * new Date(Long.MIN_VALUE))</code>.</li>
0957 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
0958 * MINUTE, SECOND and MILLISECOND are set using the method
0959 * <code>Calendar.set(int,int)</code></li>
0960 * </ul>
0961 * </p>
0962 *
0963 * @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)
0964 */
0965 public abstract GregorianCalendar toGregorianCalendar();
0966
0967 /**
0968 * <p>Convert this <code>XMLGregorianCalendar</code> along with provided parameters
0969 * to a {@link GregorianCalendar} instance.</p>
0970 *
0971 * <p> Since XML Schema 1.0 date/time datetypes has no concept of
0972 * timezone ids or daylight savings timezone ids, this conversion operation
0973 * allows the user to explicitly specify one with
0974 * <code>timezone</code> parameter.</p>
0975 *
0976 * <p>To compute the return value's <code>TimeZone</code> field,
0977 * <ul>
0978 * <li>when parameter <code>timeZone</code> is non-null,
0979 * it is the timezone field.</li>
0980 * <li>else when <code>this.getTimezone() != FIELD_UNDEFINED</code>,
0981 * create a <code>java.util.TimeZone</code> with a custom timezone id
0982 * using the <code>this.getTimezone()</code>.</li>
0983 * <li>else when <code>defaults.getTimezone() != FIELD_UNDEFINED</code>,
0984 * create a <code>java.util.TimeZone</code> with a custom timezone id
0985 * using <code>defaults.getTimezone()</code>.</li>
0986 * <li>else use the <code>GregorianCalendar</code> default timezone value
0987 * for the host is defined as specified by
0988 * <code>java.util.TimeZone.getDefault()</code>.</li></p>
0989 *
0990 * <p>To ensure consistency in conversion implementations, the new
0991 * <code>GregorianCalendar</code> should be instantiated in following
0992 * manner.
0993 * <ul>
0994 * <li>Create a new <code>java.util.GregorianCalendar(TimeZone,
0995 * Locale)</code> with TimeZone set as specified above and the
0996 * <code>Locale</code> parameter.
0997 * </li>
0998 * <li>Initialize all GregorianCalendar fields by calling {@link GregorianCalendar#clear()}</li>
0999 * <li>Obtain a pure Gregorian Calendar by invoking
1000 * <code>GregorianCalendar.setGregorianChange(
1001 * new Date(Long.MIN_VALUE))</code>.</li>
1002 * <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
1003 * MINUTE, SECOND and MILLISECOND are set using the method
1004 * <code>Calendar.set(int,int)</code></li>
1005 * </ul>
1006 *
1007 * @param timezone provide Timezone. <code>null</code> is a legal value.
1008 * @param aLocale provide explicit Locale. Use default GregorianCalendar locale if
1009 * value is <code>null</code>.
1010 * @param defaults provide default field values to use when corresponding
1011 * field for this instance is FIELD_UNDEFINED or null.
1012 * If <code>defaults</code>is <code>null</code> or a field
1013 * within the specified <code>defaults</code> is undefined,
1014 * just use <code>java.util.GregorianCalendar</code> defaults.
1015 * @return a java.util.GregorianCalendar conversion of this instance.
1016 */
1017 public abstract GregorianCalendar toGregorianCalendar(
1018 java.util.TimeZone timezone, java.util.Locale aLocale,
1019 XMLGregorianCalendar defaults);
1020
1021 /**
1022 * <p>Returns a <code>java.util.TimeZone</code> for this class.</p>
1023 *
1024 * <p>If timezone field is defined for this instance,
1025 * returns TimeZone initialized with custom timezone id
1026 * of zoneoffset. If timezone field is undefined,
1027 * try the defaultZoneoffset that was passed in.
1028 * If defaultZoneoffset is FIELD_UNDEFINED, return
1029 * default timezone for this host.
1030 * (Same default as java.util.GregorianCalendar).</p>
1031 *
1032 * @param defaultZoneoffset default zoneoffset if this zoneoffset is
1033 * {@link DatatypeConstants#FIELD_UNDEFINED}.
1034 *
1035 * @return TimeZone for this.
1036 */
1037 public abstract TimeZone getTimeZone(int defaultZoneoffset);
1038
1039 /**
1040 * <p>Creates and returns a copy of this object.</p>
1041 *
1042 * @return copy of this <code>Object</code>
1043 */
1044 public abstract Object clone();
1045 }
|