/* * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. * * * * * * * * * * * * * * * * * * * * */ package javax.xml.datatype; import javax.xml.namespace.QName; import java.math.BigDecimal; import java.math.BigInteger; import java.util.TimeZone; import java.util.GregorianCalendar; /** *

Representation for W3C XML Schema 1.0 date/time datatypes. * Specifically, these date/time datatypes are * {@link DatatypeConstants#DATETIME}, * {@link DatatypeConstants#TIME}, * {@link DatatypeConstants#DATE}, * {@link DatatypeConstants#GYEARMONTH}, * {@link DatatypeConstants#GMONTHDAY}, * {@link DatatypeConstants#GYEAR}, * {@link DatatypeConstants#GMONTH}, and * {@link DatatypeConstants#GDAY} * defined in the XML Namespace * "http://www.w3.org/2001/XMLSchema". * These datatypes are normatively defined in * W3C XML Schema 1.0 Part 2, Section 3.2.7-14.

* *

The table below defines the mapping between XML Schema 1.0 * date/time datatype fields and this class' fields. It also summarizes * the value constraints for the date and time fields defined in * W3C XML Schema 1.0 Part 2, Appendix D, * ISO 8601 Date and Time Formats.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

* Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation *
XML Schema 1.0 * datatype * field	Related XMLGregorianCalendar Accessor(s)	Value Range
year	{@link #getYear()} + {@link #getEon()} or * {@link #getEonAndYear} *	`getYear()` is a value between -(10^9-1) to (10^9)-1 * or {@link DatatypeConstants#FIELD_UNDEFINED}. * {@link #getEon()} is high order year value in billion of years. * `getEon()` has values greater than or equal to (10^9) or less than or equal to -(10^9). * A value of null indicates field is undefined. * Given that XML Schema 1.0 errata states that the year zero * will be a valid lexical value in a future version of XML Schema, * this class allows the year field to be set to zero. Otherwise, * the year field value is handled exactly as described * in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0 * validation does not allow for the year field to have a value of zero. *
month	{@link #getMonth()}	1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED}
day	{@link #getDay()}	Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}. * The normative value constraint stated relative to month * field's value is in W3C XML Schema 1.0 Part 2, Appendix D. *
hour	{@link #getHour()}	* 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}. * An hour value of 24 is allowed to be set in the lexical space provided the minute and second * field values are zero. However, an hour value of 24 is not allowed in value space and will be * transformed to represent the value of the first instance of the following day as per * * XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes. *
minute	{@link #getMinute()}	0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED}
second	* {@link #getSecond()} + {@link #getMillisecond()}/1000 or * {@link #getSecond()} + {@link #getFractionalSecond()} *	* {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}. * (Note: 60 only allowable for leap second.) * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when * the {@link #getSecond()} is defined. * `FractionalSecond` is optional and has a value of `null` when it is undefined. * {@link #getMillisecond()} is the convenience * millisecond precision of value of {@link #getFractionalSecond()}. *
timezone	{@link #getTimezone()}	Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}. * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes). *

* *

All maximum value space constraints listed for the fields in the table * above are checked by factory methods, @{link DatatypeFactory}, * setter methods and parse methods of * this class. IllegalArgumentException is thrown when a * parameter's value is outside the value constraint for the field or * if the composite * values constitute an invalid XMLGregorianCalendar instance (for example, if * the 31st of June is specified). *

* *

The following operations are defined for this class: *

accessors/mutators for independent date/time fields

conversion between this class and W3C XML Schema 1.0 lexical representation, * {@link #toString()}, {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}

conversion between this class and {@link GregorianCalendar}, * {@link #toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults)}, * {@link DatatypeFactory}

partial order relation comparator method, {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}

{@link #equals(Object)} defined relative to {@link #compare(XMLGregorianCalendar xmlGregorianCalendar)}.

addition operation with {@link Duration} * instance as defined in * W3C XML Schema 1.0 Part 2, Appendix E, Adding durations to dateTimes. *

* * @author Joseph Fialli * @author Kohsuke Kawaguchi * @author Jeff Suttor * @author Sunitha Reddy * @see Duration * @see DatatypeFactory * @since 1.5 */ public abstract class XMLGregorianCalendar implements Cloneable { /** * Default no-arg constructor. * *

Note: Always use the {@link DatatypeFactory} to * construct an instance of XMLGregorianCalendar. * The constructor on this class cannot be guaranteed to * produce an object with a consistent state and may be * removed in the future.

*/ public XMLGregorianCalendar() { } /** *

Unset all fields to undefined.

* *

Set all int fields to {@link DatatypeConstants#FIELD_UNDEFINED} and reference fields * to null.

*/ public abstract void clear(); /** *

Reset this XMLGregorianCalendar to its original values.

* *

XMLGregorianCalendar is reset to the same values as when it was created with * {@link DatatypeFactory#newXMLGregorianCalendar()}, * {@link DatatypeFactory#newXMLGregorianCalendar(String lexicalRepresentation)}, * {@link DatatypeFactory#newXMLGregorianCalendar( * BigInteger year, * int month, * int day, * int hour, * int minute, * int second, * BigDecimal fractionalSecond, * int timezone)}, * {@link DatatypeFactory#newXMLGregorianCalendar( * int year, * int month, * int day, * int hour, * int minute, * int second, * int millisecond, * int timezone)}, * {@link DatatypeFactory#newXMLGregorianCalendar(GregorianCalendar cal)}, * {@link DatatypeFactory#newXMLGregorianCalendarDate( * int year, * int month, * int day, * int timezone)}, * {@link DatatypeFactory#newXMLGregorianCalendarTime( * int hours, * int minutes, * int seconds, * int timezone)}, * {@link DatatypeFactory#newXMLGregorianCalendarTime( * int hours, * int minutes, * int seconds, * BigDecimal fractionalSecond, * int timezone)} or * {@link DatatypeFactory#newXMLGregorianCalendarTime( * int hours, * int minutes, * int seconds, * int milliseconds, * int timezone)}. *

* *

reset() is designed to allow the reuse of existing XMLGregorianCalendars * thus saving resources associated with the creation of new XMLGregorianCalendars.

*/ public abstract void reset(); /** *

Set low and high order component of XSD dateTime year field.

* *

Unset this field by invoking the setter with a parameter value of null.

* * @param year value constraints summarized in year field of date/time field mapping table. * * @throws IllegalArgumentException if year parameter is * outside value constraints for the field as specified in * date/time field mapping table. */ public abstract void setYear(BigInteger year); /** *

Set year of XSD dateTime year field.

* *

Unset this field by invoking the setter with a parameter value of * {@link DatatypeConstants#FIELD_UNDEFINED}.

* *

Note: if the absolute value of the year parameter * is less than 10^9, the eon component of the XSD year field is set to * null by this method.

* * @param year value constraints are summarized in year field of date/time field mapping table. * If year is {@link DatatypeConstants#FIELD_UNDEFINED}, then eon is set to null. */ public abstract void setYear(int year); /** *

Set month.

* *