author | joehw |
Thu, 21 Dec 2017 17:08:05 -0800 | |
changeset 48412 | d4412e380f6b |
parent 47216 | 71c04702a3d5 |
permissions | -rw-r--r-- |
12005 | 1 |
/* |
2 |
* reserved comment block |
|
3 |
* DO NOT REMOVE OR ALTER! |
|
4 |
*/ |
|
5 |
/* |
|
44797
8b3b3b911b8a
8162572: Update License Header for all JAXP sources
joehw
parents:
27574
diff
changeset
|
6 |
* Licensed to the Apache Software Foundation (ASF) under one or more |
8b3b3b911b8a
8162572: Update License Header for all JAXP sources
joehw
parents:
27574
diff
changeset
|
7 |
* contributor license agreements. See the NOTICE file distributed with |
8b3b3b911b8a
8162572: Update License Header for all JAXP sources
joehw
parents:
27574
diff
changeset
|
8 |
* this work for additional information regarding copyright ownership. |
8b3b3b911b8a
8162572: Update License Header for all JAXP sources
joehw
parents:
27574
diff
changeset
|
9 |
* The ASF licenses this file to You under the Apache License, Version 2.0 |
8b3b3b911b8a
8162572: Update License Header for all JAXP sources
joehw
parents:
27574
diff
changeset
|
10 |
* (the "License"); you may not use this file except in compliance with |
8b3b3b911b8a
8162572: Update License Header for all JAXP sources
joehw
parents:
27574
diff
changeset
|
11 |
* the License. You may obtain a copy of the License at |
12005 | 12 |
* |
13 |
* http://www.apache.org/licenses/LICENSE-2.0 |
|
14 |
* |
|
15 |
* Unless required by applicable law or agreed to in writing, software |
|
16 |
* distributed under the License is distributed on an "AS IS" BASIS, |
|
17 |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
18 |
* See the License for the specific language governing permissions and |
|
19 |
* limitations under the License. |
|
20 |
*/ |
|
21 |
||
22 |
package com.sun.org.apache.xerces.internal.jaxp.datatype; |
|
23 |
||
24 |
import java.math.BigInteger; |
|
25 |
import java.math.BigDecimal; |
|
26 |
import java.util.GregorianCalendar; |
|
27 |
||
28 |
import javax.xml.datatype.DatatypeConstants; |
|
29 |
import javax.xml.datatype.DatatypeFactory; |
|
30 |
import javax.xml.datatype.Duration; |
|
31 |
import javax.xml.datatype.XMLGregorianCalendar; |
|
32 |
||
33 |
/** |
|
34 |
* <p>Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.</p> |
|
35 |
* |
|
36 |
* <p id="DatatypeFactory.newInstance">{@link #newInstance()} is used to create a new <code>DatatypeFactory</code>. |
|
37 |
* The following implementation resolution mechanisms are used in the following order:</p> |
|
38 |
* <ol> |
|
39 |
* <li> |
|
40 |
* If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>", |
|
41 |
* exists, a class with the name of the property's value is instantiated. |
|
42 |
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. |
|
43 |
* </li> |
|
44 |
* <li> |
|
27574 | 45 |
* If the file ${JAVA_HOME}/conf/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>. |
12005 | 46 |
* The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step |
47 |
* and processed as documented in the prior step. |
|
48 |
* </li> |
|
49 |
* <li> |
|
50 |
* The services resolution mechanism is used, e.g. <code>META-INF/services/java.xml.datatype.DatatypeFactory</code>. |
|
51 |
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. |
|
52 |
* </li> |
|
53 |
* <li> |
|
54 |
* The final mechanism is to attempt to instantiate the <code>Class</code> specified by |
|
55 |
* {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}, "<code>javax.xml.datatype.DatatypeFactoryImpl</code>". |
|
56 |
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}. |
|
57 |
* </li> |
|
58 |
* </ol> |
|
59 |
* |
|
48412 | 60 |
* @author Joseph Fialli |
61 |
* @author Jeff Suttor |
|
12005 | 62 |
*/ |
63 |
public class DatatypeFactoryImpl |
|
64 |
extends DatatypeFactory { |
|
65 |
||
66 |
/** |
|
67 |
* <p>Public constructor is empty..</p> |
|
68 |
* |
|
69 |
* <p>Use {@link DatatypeFactory#newInstance()} to create a <code>DatatypeFactory</code>.</p> |
|
70 |
*/ |
|
71 |
public DatatypeFactoryImpl() { |
|
72 |
} |
|
73 |
||
74 |
/** |
|
75 |
* <p>Obtain a new instance of a <code>Duration</code> |
|
76 |
* specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS", |
|
77 |
* as defined in XML Schema 1.0 section 3.2.6.1.</p> |
|
78 |
* |
|
79 |
* <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p> |
|
80 |
* <blockquote> |
|
81 |
* duration represents a duration of time. |
|
82 |
* The value space of duration is a six-dimensional space where the coordinates designate the |
|
83 |
* Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. |
|
84 |
* These components are ordered in their significance by their order of appearance i.e. as |
|
85 |
* year, month, day, hour, minute, and second. |
|
86 |
* </blockquote> |
|
87 |
* <p>All six values are set and availabe from the created {@link Duration}</p> |
|
88 |
* |
|
89 |
* <p>The XML Schema specification states that values can be of an arbitrary size. |
|
90 |
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. |
|
91 |
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits |
|
92 |
* if implementation capacities are exceeded.</p> |
|
93 |
* |
|
94 |
* @param lexicalRepresentation <code>String</code> representation of a <code>Duration</code>. |
|
95 |
* |
|
96 |
* @return New <code>Duration</code> created from parsing the <code>lexicalRepresentation</code>. |
|
97 |
* |
|
98 |
* @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code>. |
|
99 |
* @throws UnsupportedOperationException If implementation cannot support requested values. |
|
100 |
* @throws NullPointerException if <code>lexicalRepresentation</code> is <code>null</code>. |
|
101 |
*/ |
|
102 |
public Duration newDuration(final String lexicalRepresentation) { |
|
103 |
||
104 |
return new DurationImpl(lexicalRepresentation); |
|
105 |
} |
|
106 |
||
107 |
/** |
|
108 |
* <p>Obtain a new instance of a <code>Duration</code> |
|
109 |
* specifying the <code>Duration</code> as milliseconds.</p> |
|
110 |
* |
|
111 |
* <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p> |
|
112 |
* <blockquote> |
|
113 |
* duration represents a duration of time. |
|
114 |
* The value space of duration is a six-dimensional space where the coordinates designate the |
|
115 |
* Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. |
|
116 |
* These components are ordered in their significance by their order of appearance i.e. as |
|
117 |
* year, month, day, hour, minute, and second. |
|
118 |
* </blockquote> |
|
119 |
* <p>All six values are set by computing their values from the specified milliseconds |
|
120 |
* and are availabe using the <code>get</code> methods of the created {@link Duration}. |
|
121 |
* The values conform to and are defined by:</p> |
|
122 |
* <ul> |
|
123 |
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li> |
|
124 |
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats"> |
|
125 |
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a> |
|
126 |
* </li> |
|
127 |
* <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li> |
|
128 |
* </ul> |
|
129 |
* |
|
130 |
* <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e., |
|
131 |
* {@link java.util.Calendar#YEAR} = 1970, |
|
132 |
* {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY}, |
|
133 |
* {@link java.util.Calendar#DATE} = 1, etc. |
|
134 |
* This is important as there are variations in the Gregorian Calendar, |
|
135 |
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} |
|
136 |
* so the result of {@link Duration#getMonths()} and {@link Duration#getDays()} can be influenced.</p> |
|
137 |
* |
|
138 |
* @param durationInMilliseconds Duration in milliseconds to create. |
|
139 |
* |
|
140 |
* @return New <code>Duration</code> representing <code>durationInMilliseconds</code>. |
|
141 |
*/ |
|
142 |
public Duration newDuration(final long durationInMilliseconds) { |
|
143 |
||
144 |
return new DurationImpl(durationInMilliseconds); |
|
145 |
} |
|
146 |
||
147 |
/** |
|
148 |
* <p>Obtain a new instance of a <code>Duration</code> |
|
149 |
* specifying the <code>Duration</code> as isPositive, years, months, days, hours, minutes, seconds.</p> |
|
150 |
* |
|
151 |
* <p>The XML Schema specification states that values can be of an arbitrary size. |
|
152 |
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. |
|
153 |
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits |
|
154 |
* if implementation capacities are exceeded.</p> |
|
155 |
* |
|
156 |
* @param isPositive Set to <code>false</code> to create a negative duration. When the length |
|
157 |
* of the duration is zero, this parameter will be ignored. |
|
158 |
* @param years of this <code>Duration</code> |
|
159 |
* @param months of this <code>Duration</code> |
|
160 |
* @param days of this <code>Duration</code> |
|
161 |
* @param hours of this <code>Duration</code> |
|
162 |
* @param minutes of this <code>Duration</code> |
|
163 |
* @param seconds of this <code>Duration</code> |
|
164 |
* |
|
165 |
* @return New <code>Duration</code> created from the specified values. |
|
166 |
* |
|
167 |
* @throws IllegalArgumentException If values are not a valid representation of a <code>Duration</code>. |
|
168 |
* @throws UnsupportedOperationException If implementation cannot support requested values. |
|
169 |
* @throws NullPointerException If any values are <code>null</code>. |
|
170 |
* |
|
171 |
* @see #newDuration(boolean isPositive, BigInteger years, BigInteger months, BigInteger days, |
|
172 |
* BigInteger hours, BigInteger minutes, BigDecimal seconds) |
|
173 |
*/ |
|
174 |
public Duration newDuration( |
|
175 |
final boolean isPositive, |
|
176 |
final BigInteger years, |
|
177 |
final BigInteger months, |
|
178 |
final BigInteger days, |
|
179 |
final BigInteger hours, |
|
180 |
final BigInteger minutes, |
|
181 |
final BigDecimal seconds) { |
|
182 |
||
183 |
return new DurationImpl( |
|
184 |
isPositive, |
|
185 |
years, |
|
186 |
months, |
|
187 |
days, |
|
188 |
hours, |
|
189 |
minutes, |
|
190 |
seconds |
|
191 |
); |
|
192 |
} |
|
193 |
/** |
|
194 |
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified |
|
195 |
* <code>year</code> and <code>month</code> as defined in |
|
196 |
* <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> |
|
197 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> |
|
198 |
* |
|
199 |
* <p>The XML Schema specification states that values can be of an arbitrary size. |
|
200 |
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. |
|
201 |
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits |
|
202 |
* if implementation capacities are exceeded.</p> |
|
203 |
* |
|
204 |
* <p>A <code>null</code> value indicates that field is not set.</p> |
|
205 |
* |
|
206 |
* @param isPositive Set to <code>false</code> to create a negative duration. When the length |
|
207 |
* of the duration is zero, this parameter will be ignored. |
|
208 |
* @param year Year of <code>Duration</code>. |
|
209 |
* @param month Month of <code>Duration</code>. |
|
210 |
* |
|
211 |
* @return New <code>Duration</code> created using the specified <code>year</code> and <code>month</code>. |
|
212 |
* |
|
213 |
* @throws IllegalArgumentException If the values are not a valid representation of a |
|
214 |
* <code>Duration</code>: if all of the fields (year, month) are null or |
|
215 |
* if any of the fields is negative. |
|
216 |
* @throws UnsupportedOperationException If implementation cannot support requested values. |
|
217 |
*/ |
|
218 |
public Duration newDurationYearMonth( |
|
219 |
final boolean isPositive, |
|
220 |
final BigInteger year, |
|
221 |
final BigInteger month) { |
|
222 |
||
223 |
return new DurationYearMonthImpl( |
|
224 |
isPositive, |
|
225 |
year, |
|
226 |
month |
|
227 |
); |
|
228 |
||
229 |
} |
|
230 |
/** |
|
231 |
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified |
|
232 |
* <code>year</code> and <code>month</code> as defined in |
|
233 |
* <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> |
|
234 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> |
|
235 |
* |
|
236 |
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> |
|
237 |
* |
|
238 |
* @param isPositive Set to <code>false</code> to create a negative duration. When the length |
|
239 |
* of the duration is zero, this parameter will be ignored. |
|
240 |
* @param year Year of <code>Duration</code>. |
|
241 |
* @param month Month of <code>Duration</code>. |
|
242 |
* |
|
243 |
* @return New <code>Duration</code> created using the specified <code>year</code> and <code>month</code>. |
|
244 |
* |
|
245 |
* @throws IllegalArgumentException If the values are not a valid representation of a |
|
246 |
* <code>Duration</code>: if any of the fields (year, month) is negative. |
|
247 |
*/ |
|
248 |
@Override |
|
249 |
public Duration newDurationYearMonth( |
|
250 |
final boolean isPositive, |
|
251 |
final int year, |
|
252 |
final int month) { |
|
253 |
||
254 |
return new DurationYearMonthImpl( |
|
255 |
isPositive, |
|
256 |
year, |
|
257 |
month); |
|
258 |
} |
|
259 |
||
260 |
/** |
|
261 |
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> by parsing its <code>String</code> representation, |
|
262 |
* "<em>PnYnM</em>", <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> |
|
263 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> |
|
264 |
* |
|
265 |
* <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code> |
|
266 |
* whose lexical representation contains only year and month components. |
|
267 |
* This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p> |
|
268 |
* |
|
269 |
* <p>Both values are set and availabe from the created {@link Duration}</p> |
|
270 |
* |
|
271 |
* <p>The XML Schema specification states that values can be of an arbitrary size. |
|
272 |
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. |
|
273 |
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits |
|
274 |
* if implementation capacities are exceeded.</p> |
|
275 |
* |
|
276 |
* @param lexicalRepresentation Lexical representation of a duration. |
|
277 |
* |
|
278 |
* @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>. |
|
279 |
* |
|
280 |
* @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of years and months. |
|
281 |
* @throws UnsupportedOperationException If implementation cannot support requested values. |
|
282 |
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>. |
|
283 |
*/ |
|
284 |
public Duration newDurationYearMonth( |
|
285 |
final String lexicalRepresentation) { |
|
286 |
||
287 |
return new DurationYearMonthImpl(lexicalRepresentation); |
|
288 |
||
289 |
} |
|
290 |
/** |
|
291 |
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified milliseconds as defined in |
|
292 |
* <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration"> |
|
293 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p> |
|
294 |
* |
|
295 |
* <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code> |
|
296 |
* whose lexical representation contains only year and month components. |
|
297 |
* This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p> |
|
298 |
* |
|
299 |
* <p>Both values are set by computing their values from the specified milliseconds |
|
300 |
* and are availabe using the <code>get</code> methods of the created {@link Duration}. |
|
301 |
* The values conform to and are defined by:</p> |
|
302 |
* <ul> |
|
303 |
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li> |
|
304 |
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats"> |
|
305 |
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a> |
|
306 |
* </li> |
|
307 |
* <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li> |
|
308 |
* </ul> |
|
309 |
* |
|
310 |
* <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e., |
|
311 |
* {@link java.util.Calendar#YEAR} = 1970, |
|
312 |
* {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY}, |
|
313 |
* {@link java.util.Calendar#DATE} = 1, etc. |
|
314 |
* This is important as there are variations in the Gregorian Calendar, |
|
315 |
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} |
|
316 |
* so the result of {@link Duration#getMonths()} can be influenced.</p> |
|
317 |
* |
|
318 |
* <p>Any remaining milliseconds after determining the year and month are discarded.</p> |
|
319 |
* |
|
320 |
* @param durationInMilliseconds Milliseconds of <code>Duration</code> to create. |
|
321 |
* |
|
322 |
* @return New <code>Duration</code> created using the specified <code>durationInMilliseconds</code>. |
|
323 |
*/ |
|
324 |
public Duration newDurationYearMonth( |
|
325 |
final long durationInMilliseconds) { |
|
326 |
||
327 |
return new DurationYearMonthImpl(durationInMilliseconds); |
|
328 |
} |
|
329 |
||
330 |
/** |
|
331 |
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> by parsing its <code>String</code> representation, |
|
332 |
* "<em>PnDTnHnMnS</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> |
|
333 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> |
|
334 |
* |
|
335 |
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> |
|
336 |
* whose lexical representation contains only day, hour, minute, and second components. |
|
337 |
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> |
|
338 |
* |
|
339 |
* <p>All four values are set and availabe from the created {@link Duration}</p> |
|
340 |
* |
|
341 |
* <p>The XML Schema specification states that values can be of an arbitrary size. |
|
342 |
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. |
|
343 |
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits |
|
344 |
* if implementation capacities are exceeded.</p> |
|
345 |
* |
|
346 |
* @param lexicalRepresentation Lexical representation of a duration. |
|
347 |
* |
|
348 |
* @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>. |
|
349 |
* |
|
350 |
* @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of days and time. |
|
351 |
* @throws UnsupportedOperationException If implementation cannot support requested values. |
|
352 |
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>. |
|
353 |
*/ |
|
354 |
public Duration newDurationDayTime(final String lexicalRepresentation) { |
|
355 |
// lexicalRepresentation must be non-null |
|
356 |
if (lexicalRepresentation == null) { |
|
357 |
throw new NullPointerException( |
|
358 |
"Trying to create an xdt:dayTimeDuration with an invalid" |
|
359 |
+ " lexical representation of \"null\""); |
|
360 |
} |
|
361 |
||
362 |
return new DurationDayTimeImpl(lexicalRepresentation); |
|
363 |
} |
|
364 |
||
365 |
/** |
|
366 |
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified milliseconds as defined in |
|
367 |
* <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> |
|
368 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> |
|
369 |
* |
|
370 |
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> |
|
371 |
* whose lexical representation contains only day, hour, minute, and second components. |
|
372 |
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> |
|
373 |
* |
|
374 |
* <p>All four values are set by computing their values from the specified milliseconds |
|
375 |
* and are availabe using the <code>get</code> methods of the created {@link Duration}. |
|
376 |
* The values conform to and are defined by:</p> |
|
377 |
* <ul> |
|
378 |
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li> |
|
379 |
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats"> |
|
380 |
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a> |
|
381 |
* </li> |
|
382 |
* <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li> |
|
383 |
* </ul> |
|
384 |
* |
|
385 |
* <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e., |
|
386 |
* {@link java.util.Calendar#YEAR} = 1970, |
|
387 |
* {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY}, |
|
388 |
* {@link java.util.Calendar#DATE} = 1, etc. |
|
389 |
* This is important as there are variations in the Gregorian Calendar, |
|
390 |
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY} |
|
391 |
* so the result of {@link Duration#getDays()} can be influenced.</p> |
|
392 |
* |
|
393 |
* <p>Any remaining milliseconds after determining the day, hour, minute and second are discarded.</p> |
|
394 |
* |
|
395 |
* @param durationInMilliseconds Milliseconds of <code>Duration</code> to create. |
|
396 |
* |
|
397 |
* @return New <code>Duration</code> created with the specified <code>durationInMilliseconds</code>. |
|
398 |
* |
|
399 |
* @see <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> |
|
400 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a> |
|
401 |
*/ |
|
402 |
public Duration newDurationDayTime(final long durationInMilliseconds) { |
|
403 |
||
404 |
return new DurationDayTimeImpl(durationInMilliseconds); |
|
405 |
} |
|
406 |
||
407 |
/** |
|
408 |
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified |
|
409 |
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in |
|
410 |
* <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> |
|
411 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> |
|
412 |
* |
|
413 |
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> |
|
414 |
* whose lexical representation contains only day, hour, minute, and second components. |
|
415 |
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> |
|
416 |
* |
|
417 |
* <p>The XML Schema specification states that values can be of an arbitrary size. |
|
418 |
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. |
|
419 |
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits |
|
420 |
* if implementation capacities are exceeded.</p> |
|
421 |
* |
|
422 |
* <p>A <code>null</code> value indicates that field is not set.</p> |
|
423 |
* |
|
424 |
* @param isPositive Set to <code>false</code> to create a negative duration. When the length |
|
425 |
* of the duration is zero, this parameter will be ignored. |
|
426 |
* @param day Day of <code>Duration</code>. |
|
427 |
* @param hour Hour of <code>Duration</code>. |
|
428 |
* @param minute Minute of <code>Duration</code>. |
|
429 |
* @param second Second of <code>Duration</code>. |
|
430 |
* |
|
431 |
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code> |
|
432 |
* and <code>second</code>. |
|
433 |
* |
|
434 |
* @throws IllegalArgumentException If the values are not a valid representation of a |
|
435 |
* <code>Duration</code>: if all the fields (day, hour, ...) are null or |
|
436 |
* if any of the fields is negative. |
|
437 |
* @throws UnsupportedOperationException If implementation cannot support requested values. |
|
438 |
*/ |
|
439 |
public Duration newDurationDayTime( |
|
440 |
final boolean isPositive, |
|
441 |
final BigInteger day, |
|
442 |
final BigInteger hour, |
|
443 |
final BigInteger minute, |
|
444 |
final BigInteger second) { |
|
445 |
||
446 |
return new DurationDayTimeImpl( |
|
447 |
isPositive, |
|
448 |
day, |
|
449 |
hour, |
|
450 |
minute, |
|
451 |
(second != null)? new BigDecimal(second):null |
|
452 |
); |
|
453 |
} |
|
454 |
||
455 |
/** |
|
456 |
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified |
|
457 |
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in |
|
458 |
* <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration"> |
|
459 |
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p> |
|
460 |
* |
|
461 |
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code> |
|
462 |
* whose lexical representation contains only day, hour, minute, and second components. |
|
463 |
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p> |
|
464 |
* |
|
465 |
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field is not set.</p> |
|
466 |
* |
|
467 |
* @param isPositive Set to <code>false</code> to create a negative duration. When the length |
|
468 |
* of the duration is zero, this parameter will be ignored. |
|
469 |
* @param day Day of <code>Duration</code>. |
|
470 |
* @param hour Hour of <code>Duration</code>. |
|
471 |
* @param minute Minute of <code>Duration</code>. |
|
472 |
* @param second Second of <code>Duration</code>. |
|
473 |
* |
|
474 |
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code> |
|
475 |
* and <code>second</code>. |
|
476 |
* |
|
477 |
* @throws IllegalArgumentException If the values are not a valid representation of a |
|
478 |
* <code>Duration</code>: if any of the fields (day, hour, ...) is negative. |
|
479 |
*/ |
|
480 |
public Duration newDurationDayTime( |
|
481 |
final boolean isPositive, |
|
482 |
final int day, |
|
483 |
final int hour, |
|
484 |
final int minute, |
|
485 |
final int second) { |
|
486 |
||
487 |
return new DurationDayTimeImpl( |
|
488 |
isPositive, |
|
489 |
day, |
|
490 |
hour, |
|
491 |
minute, |
|
492 |
second |
|
493 |
); |
|
494 |
} |
|
495 |
||
496 |
/** |
|
497 |
* <p>Create a new instance of an <code>XMLGregorianCalendar</code>.</p> |
|
498 |
* |
|
499 |
* <p>All date/time datatype fields set to {@link DatatypeConstants#FIELD_UNDEFINED} or null.</p> |
|
500 |
* |
|
501 |
* @return New <code>XMLGregorianCalendar</code> with all date/time datatype fields set to |
|
502 |
* {@link DatatypeConstants#FIELD_UNDEFINED} or null. |
|
503 |
*/ |
|
504 |
public XMLGregorianCalendar newXMLGregorianCalendar() { |
|
505 |
||
506 |
return new XMLGregorianCalendarImpl(); |
|
507 |
} |
|
508 |
||
509 |
/** |
|
510 |
* <p>Create a new XMLGregorianCalendar by parsing the String as a lexical representation.</p> |
|
511 |
* |
|
512 |
* <p>Parsing the lexical string representation is defined in |
|
513 |
* <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1, |
|
514 |
* <em>Lexical Representation</em>.</a></p> |
|
515 |
* |
|
516 |
* <p>The string representation may not have any leading and trailing whitespaces.</p> |
|
517 |
* |
|
518 |
* <p>The parsing is done field by field so that |
|
519 |
* the following holds for any lexically correct String x:</p> |
|
520 |
* <pre> |
|
521 |
* newXMLGregorianCalendar(x).toXMLFormat().equals(x) |
|
522 |
* </pre> |
|
523 |
* <p>Except for the noted lexical/canonical representation mismatches |
|
524 |
* listed in <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45"> |
|
525 |
* XML Schema 1.0 errata, Section 3.2.7.2</a>.</p> |
|
526 |
* |
|
527 |
* @param lexicalRepresentation Lexical representation of one the eight XML Schema date/time datatypes. |
|
528 |
* |
|
529 |
* @return <code>XMLGregorianCalendar</code> created from the <code>lexicalRepresentation</code>. |
|
530 |
* |
|
531 |
* @throws IllegalArgumentException If the <code>lexicalRepresentation</code> is not a valid <code>XMLGregorianCalendar</code>. |
|
532 |
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>. |
|
533 |
*/ |
|
534 |
public XMLGregorianCalendar newXMLGregorianCalendar(final String lexicalRepresentation) { |
|
535 |
||
536 |
return new XMLGregorianCalendarImpl(lexicalRepresentation); |
|
537 |
} |
|
538 |
||
539 |
/** |
|
540 |
* <p>Create an <code>XMLGregorianCalendar</code> from a {@link GregorianCalendar}.</p> |
|
541 |
* |
|
542 |
* <table border="2" rules="all" cellpadding="2"> |
|
543 |
* <thead> |
|
544 |
* <tr> |
|
545 |
* <th align="center" colspan="2"> |
|
546 |
* Field by Field Conversion from |
|
547 |
* {@link GregorianCalendar} to an {@link XMLGregorianCalendar} |
|
548 |
* </th> |
|
549 |
* </tr> |
|
550 |
* <tr> |
|
551 |
* <th><code>java.util.GregorianCalendar</code> field</th> |
|
552 |
* <th><code>javax.xml.datatype.XMLGregorianCalendar</code> field</th> |
|
553 |
* </tr> |
|
554 |
* </thead> |
|
555 |
* <tbody> |
|
556 |
* <tr> |
|
557 |
* <td><code>ERA == GregorianCalendar.BC ? -YEAR : YEAR</code></td> |
|
558 |
* <td>{@link XMLGregorianCalendar#setYear(int year)}</td> |
|
559 |
* </tr> |
|
560 |
* <tr> |
|
561 |
* <td><code>MONTH + 1</code></td> |
|
562 |
* <td>{@link XMLGregorianCalendar#setMonth(int month)}</td> |
|
563 |
* </tr> |
|
564 |
* <tr> |
|
565 |
* <td><code>DAY_OF_MONTH</code></td> |
|
566 |
* <td>{@link XMLGregorianCalendar#setDay(int day)}</td> |
|
567 |
* </tr> |
|
568 |
* <tr> |
|
569 |
* <td><code>HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND</code></td> |
|
570 |
* <td>{@link XMLGregorianCalendar#setTime(int hour, int minute, int second, BigDecimal fractional)}</td> |
|
571 |
* </tr> |
|
572 |
* <tr> |
|
573 |
* <td> |
|
574 |
* <code>(ZONE_OFFSET + DST_OFFSET) / (60*1000)</code><br/> |
|
575 |
* <em>(in minutes)</em> |
|
576 |
* </td> |
|
577 |
* <td>{@link XMLGregorianCalendar#setTimezone(int offset)}<sup><em>*</em></sup> |
|
578 |
* </td> |
|
579 |
* </tr> |
|
580 |
* </tbody> |
|
581 |
* </table> |
|
582 |
* <p><em>*</em>conversion loss of information. It is not possible to represent |
|
583 |
* a <code>java.util.GregorianCalendar</code> daylight savings timezone id in the |
|
584 |
* XML Schema 1.0 date/time datatype representation.</p> |
|
585 |
* |
|
586 |
* <p>To compute the return value's <code>TimeZone</code> field, |
|
587 |
* <ul> |
|
588 |
* <li>when <code>this.getTimezone() != FIELD_UNDEFINED</code>, |
|
589 |
* create a <code>java.util.TimeZone</code> with a custom timezone id |
|
590 |
* using the <code>this.getTimezone()</code>.</li> |
|
591 |
* <li>else use the <code>GregorianCalendar</code> default timezone value |
|
592 |
* for the host is defined as specified by |
|
593 |
* <code>java.util.TimeZone.getDefault()</code>.</li></p> |
|
594 |
* |
|
595 |
* @param cal <code>java.util.GregorianCalendar</code> used to create <code>XMLGregorianCalendar</code> |
|
596 |
* |
|
597 |
* @return <code>XMLGregorianCalendar</code> created from <code>java.util.GregorianCalendar</code> |
|
598 |
* |
|
599 |
* @throws NullPointerException If <code>cal</code> is <code>null</code>. |
|
600 |
*/ |
|
601 |
public XMLGregorianCalendar newXMLGregorianCalendar(final GregorianCalendar cal) { |
|
602 |
||
603 |
return new XMLGregorianCalendarImpl(cal); |
|
604 |
} |
|
605 |
||
606 |
/** |
|
607 |
* <p>Constructor allowing for complete value spaces allowed by |
|
608 |
* W3C XML Schema 1.0 recommendation for xsd:dateTime and related |
|
609 |
* builtin datatypes. Note that <code>year</code> parameter supports |
|
610 |
* arbitrarily large numbers and fractionalSecond has infinite |
|
611 |
* precision.</p> |
|
612 |
* |
|
613 |
* @param year of <code>XMLGregorianCalendar</code> to be created. |
|
614 |
* @param month of <code>XMLGregorianCalendar</code> to be created. |
|
615 |
* @param day of <code>XMLGregorianCalendar</code> to be created. |
|
616 |
* @param hour of <code>XMLGregorianCalendar</code> to be created. |
|
617 |
* @param minute of <code>XMLGregorianCalendar</code> to be created. |
|
618 |
* @param second of <code>XMLGregorianCalendar</code> to be created. |
|
619 |
* @param fractionalSecond of <code>XMLGregorianCalendar</code> to be created. |
|
620 |
* @param timezone of <code>XMLGregorianCalendar</code> to be created. |
|
621 |
* |
|
622 |
* @return <code>XMLGregorianCalendar</code> created from specified values. |
|
623 |
* |
|
624 |
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field |
|
625 |
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar} |
|
626 |
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance |
|
627 |
* as determined by {@link XMLGregorianCalendar#isValid()}. |
|
628 |
* @throws NullPointerException If any parameters are <code>null</code>. |
|
629 |
* |
|
630 |
*/ |
|
631 |
public XMLGregorianCalendar newXMLGregorianCalendar( |
|
632 |
final BigInteger year, |
|
633 |
final int month, |
|
634 |
final int day, |
|
635 |
final int hour, |
|
636 |
final int minute, |
|
637 |
final int second, |
|
638 |
final BigDecimal fractionalSecond, |
|
639 |
final int timezone) { |
|
640 |
||
641 |
return new XMLGregorianCalendarImpl( |
|
642 |
year, |
|
643 |
month, |
|
644 |
day, |
|
645 |
hour, |
|
646 |
minute, |
|
647 |
second, |
|
648 |
fractionalSecond, |
|
649 |
timezone |
|
650 |
); |
|
651 |
} |
|
652 |
} |