36 * Specifically, these date/time datatypes are
37 * {@link DatatypeConstants#DATETIME},
38 * {@link DatatypeConstants#TIME},
39 * {@link DatatypeConstants#DATE},
40 * {@link DatatypeConstants#GYEARMONTH},
41 * {@link DatatypeConstants#GMONTHDAY},
42 * {@link DatatypeConstants#GYEAR},
43 * {@link DatatypeConstants#GMONTH}, and
44 * {@link DatatypeConstants#GDAY}
45 * defined in the XML Namespace
46 * {@code "http://www.w3.org/2001/XMLSchema"}.
47 * These datatypes are normatively defined in
48 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.
49 *
50 * <p>The table below defines the mapping between XML Schema 1.0
51 * date/time datatype fields and this class' fields. It also summarizes
52 * the value constraints for the date and time fields defined in
53 * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
54 * <i>ISO 8601 Date and Time Formats</i></a>.
55 *
56 * <a name="datetimefieldmapping"></a>
57 * <table border="2" rules="all" cellpadding="2">
58 * <thead>
59 * <tr>
60 * <th align="center" colspan="3">
61 * Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation
62 * </th>
63 * </tr>
64 * </thead>
65 * <tbody>
66 * <tr>
67 * <th>XML Schema 1.0<br>
68 * datatype<br>
69 * field</th>
70 * <th>Related<br>XMLGregorianCalendar<br>Accessor(s)</th>
71 * <th>Value Range</th>
72 * </tr>
73 * <tr>
74 * <td><a name="datetimefield-year">year</a></td>
75 * <td> {@link #getYear()} + {@link #getEon()} or<br>
76 * {@link #getEonAndYear}
77 * </td>
78 * <td> {@code getYear()} is a value between -(10^9-1) to (10^9)-1
79 * or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
80 * {@link #getEon()} is high order year value in billion of years.<br>
81 * {@code getEon()} has values greater than or equal to (10^9) or less than or equal to -(10^9).
82 * A value of null indicates field is undefined.<br>
83 * 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
84 * will be a valid lexical value in a future version of XML Schema,
85 * this class allows the year field to be set to zero. Otherwise,
86 * the year field value is handled exactly as described
87 * in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0
88 * validation does not allow for the year field to have a value of zero.
89 * </td>
90 * </tr>
91 * <tr>
92 * <td><a name="datetimefield-month">month</a></td>
93 * <td> {@link #getMonth()} </td>
94 * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
95 * </tr>
96 * <tr>
97 * <td><a name="datetimefield-day">day</a></td>
98 * <td> {@link #getDay()} </td>
99 * <td> Independent of month, max range is 1 to 31 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
100 * The normative value constraint stated relative to month
101 * 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>.
102 * </td>
103 * </tr>
104 * <tr>
105 * <td><a name="datetimefield-hour">hour</a></td>
106 * <td>{@link #getHour()}</td>
107 * <td>
108 * 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}.
109 * An hour value of 24 is allowed to be set in the lexical space provided the minute and second
110 * field values are zero. However, an hour value of 24 is not allowed in value space and will be
111 * transformed to represent the value of the first instance of the following day as per
112 * <a href="http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes">
113 * XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes</a>.
114 * </td>
115 * </tr>
116 * <tr>
117 * <td><a name="datetimefield-minute">minute</a></td>
118 * <td> {@link #getMinute()} </td>
119 * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
120 * </tr>
121 * <tr>
122 * <td><a name="datetimefield-second">second</a></td>
123 * <td>
124 * {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br>
125 * {@link #getSecond()} + {@link #getFractionalSecond()}
126 * </td>
127 * <td>
128 * {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
129 * <i>(Note: 60 only allowable for leap second.)</i><br>
130 * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when
131 * the {@link #getSecond()} is defined.<br>
132 * {@code FractionalSecond} is optional and has a value of {@code null} when it is undefined.<br>
133 * {@link #getMillisecond()} is the convenience
134 * millisecond precision of value of {@link #getFractionalSecond()}.
135 * </td>
136 * </tr>
137 * <tr>
138 * <td><a name="datetimefield-timezone">timezone</a></td>
139 * <td> {@link #getTimezone()} </td>
140 * <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
141 * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
142 * </td>
143 * </tr>
144 * </tbody>
145 * </table>
146 *
147 * <p>All maximum value space constraints listed for the fields in the table
148 * above are checked by factory methods, {@link DatatypeFactory},
149 * setter methods and parse methods of
150 * this class. {@code IllegalArgumentException} is thrown when a
151 * parameter's value is outside the value constraint for the field or
152 * if the composite
153 * values constitute an invalid XMLGregorianCalendar instance (for example, if
154 * the 31st of June is specified).
155 *
156 * <p>The following operations are defined for this class:
157 * <ul>
158 * <li>accessors/mutators for independent date/time fields</li>
731 /**
732 * Return the lexical representation of {@code this} instance.
733 * The format is specified in
734 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
735 * <i>Lexical Representation</i>".</a>
736 *
737 * <p>Specific target lexical representation format is determined by
738 * {@link #getXMLSchemaType()}.
739 *
740 * @return XML, as {@code String}, representation of this {@code XMLGregorianCalendar}
741 *
742 * @throws IllegalStateException if the combination of set fields
743 * does not match one of the eight defined XML Schema builtin date/time datatypes.
744 */
745 public abstract String toXMLFormat();
746
747 /**
748 * Return the name of the XML Schema date/time type that this instance
749 * maps to. Type is computed based on fields that are set.
750 *
751 * <table border="2" rules="all" cellpadding="2">
752 * <thead>
753 * <tr>
754 * <th align="center" colspan="7">
755 * Required fields for XML Schema 1.0 Date/Time Datatypes.<br>
756 * <i>(timezone is optional for all date/time datatypes)</i>
757 * </th>
758 * </tr>
759 * </thead>
760 * <tbody>
761 * <tr>
762 * <td>Datatype</td>
763 * <td>year</td>
764 * <td>month</td>
765 * <td>day</td>
766 * <td>hour</td>
767 * <td>minute</td>
768 * <td>second</td>
769 * </tr>
770 * <tr>
771 * <td>{@link DatatypeConstants#DATETIME}</td>
772 * <td>X</td>
773 * <td>X</td>
774 * <td>X</td>
775 * <td>X</td>
776 * <td>X</td>
777 * <td>X</td>
778 * </tr>
779 * <tr>
780 * <td>{@link DatatypeConstants#DATE}</td>
781 * <td>X</td>
782 * <td>X</td>
783 * <td>X</td>
784 * <td></td>
785 * <td></td>
786 * <td></td>
787 * </tr>
788 * <tr>
789 * <td>{@link DatatypeConstants#TIME}</td>
790 * <td></td>
894 * @param duration Duration to add to this {@code XMLGregorianCalendar}.
895 *
896 * @throws NullPointerException when {@code duration} parameter is {@code null}.
897 */
898 public abstract void add(Duration duration);
899
900 /**
901 * Convert this {@code XMLGregorianCalendar} to a {@link GregorianCalendar}.
902 *
903 * <p>When {@code this} instance has an undefined field, this
904 * conversion relies on the {@code java.util.GregorianCalendar} default
905 * for its corresponding field. A notable difference between
906 * XML Schema 1.0 date/time datatypes and {@code java.util.GregorianCalendar}
907 * is that Timezone value is optional for date/time datatypes and it is
908 * a required field for {@code java.util.GregorianCalendar}. See javadoc
909 * for {@code java.util.TimeZone.getDefault()} on how the default
910 * is determined. To explicitly specify the {@code TimeZone}
911 * instance, see
912 * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.
913 *
914 * <table border="2" rules="all" cellpadding="2">
915 * <thead>
916 * <tr>
917 * <th align="center" colspan="2">
918 * Field by Field Conversion from this class to
919 * {@code java.util.GregorianCalendar}
920 * </th>
921 * </tr>
922 * </thead>
923 * <tbody>
924 * <tr>
925 * <td>{@code java.util.GregorianCalendar} field</td>
926 * <td>{@code javax.xml.datatype.XMLGregorianCalendar} field</td>
927 * </tr>
928 * <tr>
929 * <td>{@code ERA}</td>
930 * <td>{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD}</td>
931 * </tr>
932 * <tr>
933 * <td>{@code YEAR}</td>
934 * <td>{@link #getEonAndYear()}{@code .abs().intValue()}<i>*</i></td>
935 * </tr>
936 * <tr>
937 * <td>{@code MONTH}</td>
938 * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td>
939 * </tr>
940 * <tr>
941 * <td>{@code DAY_OF_MONTH}</td>
942 * <td>{@link #getDay()}</td>
943 * </tr>
944 * <tr>
945 * <td>{@code HOUR_OF_DAY}</td>
946 * <td>{@link #getHour()}</td>
947 * </tr>
|
36 * Specifically, these date/time datatypes are
37 * {@link DatatypeConstants#DATETIME},
38 * {@link DatatypeConstants#TIME},
39 * {@link DatatypeConstants#DATE},
40 * {@link DatatypeConstants#GYEARMONTH},
41 * {@link DatatypeConstants#GMONTHDAY},
42 * {@link DatatypeConstants#GYEAR},
43 * {@link DatatypeConstants#GMONTH}, and
44 * {@link DatatypeConstants#GDAY}
45 * defined in the XML Namespace
46 * {@code "http://www.w3.org/2001/XMLSchema"}.
47 * These datatypes are normatively defined in
48 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">W3C XML Schema 1.0 Part 2, Section 3.2.7-14</a>.
49 *
50 * <p>The table below defines the mapping between XML Schema 1.0
51 * date/time datatype fields and this class' fields. It also summarizes
52 * the value constraints for the date and time fields defined in
53 * <a href="http://www.w3.org/TR/xmlschema-2/#isoformats">W3C XML Schema 1.0 Part 2, Appendix D,
54 * <i>ISO 8601 Date and Time Formats</i></a>.
55 *
56 * <a id="datetimefieldmapping"></a>
57 * <table class="striped">
58 * <caption>Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</caption>
59 * <thead>
60 * <tr>
61 * <th>XML Schema 1.0<br>
62 * datatype<br>
63 * field</th>
64 * <th>Related<br>XMLGregorianCalendar<br>Accessor(s)</th>
65 * <th>Value Range</th>
66 * </tr>
67 * </thead>
68 * <tbody>
69 * <tr>
70 * <td><a id="datetimefield-year">year</a></td>
71 * <td> {@link #getYear()} + {@link #getEon()} or<br>
72 * {@link #getEonAndYear}
73 * </td>
74 * <td> {@code getYear()} is a value between -(10^9-1) to (10^9)-1
75 * or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
76 * {@link #getEon()} is high order year value in billion of years.<br>
77 * {@code getEon()} has values greater than or equal to (10^9) or less than or equal to -(10^9).
78 * A value of null indicates field is undefined.<br>
79 * 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
80 * will be a valid lexical value in a future version of XML Schema,
81 * this class allows the year field to be set to zero. Otherwise,
82 * the year field value is handled exactly as described
83 * in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0
84 * validation does not allow for the year field to have a value of zero.
85 * </td>
86 * </tr>
87 * <tr>
88 * <td><a id="datetimefield-month">month</a></td>
89 * <td> {@link #getMonth()} </td>
90 * <td> 1 to 12 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
91 * </tr>
92 * <tr>
93 * <td><a id="datetimefield-day">day</a></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>
101 * <td><a id="datetimefield-hour">hour</a></td>
102 * <td>{@link #getHour()}</td>
103 * <td>
104 * 0 to 23 or {@link DatatypeConstants#FIELD_UNDEFINED}.
105 * An hour value of 24 is allowed to be set in the lexical space provided the minute and second
106 * field values are zero. However, an hour value of 24 is not allowed in value space and will be
107 * transformed to represent the value of the first instance of the following day as per
108 * <a href="http://www.w3.org/TR/xmlschema-2/#built-in-primitive-datatypes">
109 * XML Schema Part 2: Datatypes Second Edition, 3.2 Primitive datatypes</a>.
110 * </td>
111 * </tr>
112 * <tr>
113 * <td><a id="datetimefield-minute">minute</a></td>
114 * <td> {@link #getMinute()} </td>
115 * <td> 0 to 59 or {@link DatatypeConstants#FIELD_UNDEFINED} </td>
116 * </tr>
117 * <tr>
118 * <td><a id="datetimefield-second">second</a></td>
119 * <td>
120 * {@link #getSecond()} + {@link #getMillisecond()}/1000 or<br>
121 * {@link #getSecond()} + {@link #getFractionalSecond()}
122 * </td>
123 * <td>
124 * {@link #getSecond()} from 0 to 60 or {@link DatatypeConstants#FIELD_UNDEFINED}.<br>
125 * <i>(Note: 60 only allowable for leap second.)</i><br>
126 * {@link #getFractionalSecond()} allows for infinite precision over the range from 0.0 to 1.0 when
127 * the {@link #getSecond()} is defined.<br>
128 * {@code FractionalSecond} is optional and has a value of {@code null} when it is undefined.<br>
129 * {@link #getMillisecond()} is the convenience
130 * millisecond precision of value of {@link #getFractionalSecond()}.
131 * </td>
132 * </tr>
133 * <tr>
134 * <td><a id="datetimefield-timezone">timezone</a></td>
135 * <td> {@link #getTimezone()} </td>
136 * <td> Number of minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.
137 * Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).
138 * </td>
139 * </tr>
140 * </tbody>
141 * </table>
142 *
143 * <p>All maximum value space constraints listed for the fields in the table
144 * above are checked by factory methods, {@link DatatypeFactory},
145 * setter methods and parse methods of
146 * this class. {@code IllegalArgumentException} is thrown when a
147 * parameter's value is outside the value constraint for the field or
148 * if the composite
149 * values constitute an invalid XMLGregorianCalendar instance (for example, if
150 * the 31st of June is specified).
151 *
152 * <p>The following operations are defined for this class:
153 * <ul>
154 * <li>accessors/mutators for independent date/time fields</li>
727 /**
728 * Return the lexical representation of {@code this} instance.
729 * The format is specified in
730 * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
731 * <i>Lexical Representation</i>".</a>
732 *
733 * <p>Specific target lexical representation format is determined by
734 * {@link #getXMLSchemaType()}.
735 *
736 * @return XML, as {@code String}, representation of this {@code XMLGregorianCalendar}
737 *
738 * @throws IllegalStateException if the combination of set fields
739 * does not match one of the eight defined XML Schema builtin date/time datatypes.
740 */
741 public abstract String toXMLFormat();
742
743 /**
744 * Return the name of the XML Schema date/time type that this instance
745 * maps to. Type is computed based on fields that are set.
746 *
747 * <table class="striped">
748 * <caption>Required fields for XML Schema 1.0 Date/Time Datatypes.<br>
749 * <i>(timezone is optional for all date/time datatypes)</i></caption>
750 * <thead>
751 * <tr>
752 * <th>Datatype</th>
753 * <th>year</th>
754 * <th>month</th>
755 * <th>day</th>
756 * <th>hour</th>
757 * <th>minute</th>
758 * <th>second</th>
759 * </tr>
760 * </thead>
761 * <tbody>
762 * <tr>
763 * <td>{@link DatatypeConstants#DATETIME}</td>
764 * <td>X</td>
765 * <td>X</td>
766 * <td>X</td>
767 * <td>X</td>
768 * <td>X</td>
769 * <td>X</td>
770 * </tr>
771 * <tr>
772 * <td>{@link DatatypeConstants#DATE}</td>
773 * <td>X</td>
774 * <td>X</td>
775 * <td>X</td>
776 * <td></td>
777 * <td></td>
778 * <td></td>
779 * </tr>
780 * <tr>
781 * <td>{@link DatatypeConstants#TIME}</td>
782 * <td></td>
886 * @param duration Duration to add to this {@code XMLGregorianCalendar}.
887 *
888 * @throws NullPointerException when {@code duration} parameter is {@code null}.
889 */
890 public abstract void add(Duration duration);
891
892 /**
893 * Convert this {@code XMLGregorianCalendar} to a {@link GregorianCalendar}.
894 *
895 * <p>When {@code this} instance has an undefined field, this
896 * conversion relies on the {@code java.util.GregorianCalendar} default
897 * for its corresponding field. A notable difference between
898 * XML Schema 1.0 date/time datatypes and {@code java.util.GregorianCalendar}
899 * is that Timezone value is optional for date/time datatypes and it is
900 * a required field for {@code java.util.GregorianCalendar}. See javadoc
901 * for {@code java.util.TimeZone.getDefault()} on how the default
902 * is determined. To explicitly specify the {@code TimeZone}
903 * instance, see
904 * {@link #toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar)}.
905 *
906 * <table class="striped">
907 * <caption>Field by Field Conversion from this class to
908 * {@code java.util.GregorianCalendar}</caption>
909 * <thead>
910 * <tr>
911 * <th>{@code java.util.GregorianCalendar} field</th>
912 * <th>{@code javax.xml.datatype.XMLGregorianCalendar} field</th>
913 * </tr>
914 * </thead>
915 * <tbody>
916 * <tr>
917 * <td>{@code ERA}</td>
918 * <td>{@link #getEonAndYear()}{@code .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD}</td>
919 * </tr>
920 * <tr>
921 * <td>{@code YEAR}</td>
922 * <td>{@link #getEonAndYear()}{@code .abs().intValue()}<i>*</i></td>
923 * </tr>
924 * <tr>
925 * <td>{@code MONTH}</td>
926 * <td>{@link #getMonth()} - {@link DatatypeConstants#JANUARY} + {@link GregorianCalendar#JANUARY}</td>
927 * </tr>
928 * <tr>
929 * <td>{@code DAY_OF_MONTH}</td>
930 * <td>{@link #getDay()}</td>
931 * </tr>
932 * <tr>
933 * <td>{@code HOUR_OF_DAY}</td>
934 * <td>{@link #getHour()}</td>
935 * </tr>
|