2
* Copyright 2003-2004 The Apache Software Foundation.
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
17
// $Id: DatatypeFactory.java 226183 2005-04-08 10:39:14Z neeraj $
19
package javax.xml.datatype;
21
import java.math.BigInteger;
22
import java.math.BigDecimal;
23
import java.util.GregorianCalendar;
26
* <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>
28
* <p id="DatatypeFactory.newInstance">{@link #newInstance()} is used to create a new <code>DatatypeFactory</code>.
29
* The following implementation resolution mechanisms are used in the following order:</p>
32
* If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>",
33
* exists, a class with the name of the property's value is instantiated.
34
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
37
* If the file ${JAVA_HOME}/lib/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>.
38
* The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step
39
* and processed as documented in the prior step.
42
* The services resolution mechanism is used, e.g. <code>META-INF/services/java.xml.datatype.DatatypeFactory</code>.
43
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
46
* The final mechanism is to attempt to instantiate the <code>Class</code> specified by
47
* {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}, "<code>javax.xml.datatype.DatatypeFactoryImpl</code>".
48
* Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
52
* @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
53
* @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
54
* @version $Revision: 226183 $, $Date: 2005-04-08 06:39:14 -0400 (Fri, 08 Apr 2005) $
57
public abstract class DatatypeFactory {
60
* <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
62
* <p>Default value is <code>javax.xml.datatype.DatatypeFactory</code>.</p>
64
public static final String DATATYPEFACTORY_PROPERTY = "javax.xml.datatype.DatatypeFactory";
67
* <p>Default implementation class name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
69
* <p>Default value is <code>org.apache.xerces.jaxp.datatype.DatatypeFactoryImpl</code>.</p>
71
public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS = "org.apache.xerces.jaxp.datatype.DatatypeFactoryImpl";
74
* <p>Protected constructor to prevent instaniation outside of package.</p>
76
* <p>Use {@link #newInstance()} to create a <code>DatatypeFactory</code>.</p>
78
protected DatatypeFactory() {
82
* <p>Obtain a new instance of a <code>DatatypeFactory</code>.</p>
84
* <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
85
* <code>Class</code>'s documentation.</p>
87
* @return New instance of a <code>DocumentBuilderFactory</code>
89
* @throws DatatypeConfigurationException If the implementation is not
90
* available or cannot be instantiated.
92
public static DatatypeFactory newInstance()
93
throws DatatypeConfigurationException {
96
return (DatatypeFactory) FactoryFinder.find(
97
/* The default property name according to the JAXP spec */
98
DATATYPEFACTORY_PROPERTY,
99
/* The fallback implementation class name */
100
DATATYPEFACTORY_IMPLEMENTATION_CLASS);
101
} catch (FactoryFinder.ConfigurationError e) {
102
throw new DatatypeConfigurationException(e.getMessage(), e.getException());
107
* <p>Obtain a new instance of a <code>Duration</code>
108
* specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS",
109
* as defined in XML Schema 1.0 section 3.2.6.1.</p>
111
* <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
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.
119
* <p>All six values are set and availabe from the created {@link Duration}</p>
121
* <p>The XML Schema specification states that values can be of an arbitrary size.
122
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
123
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
124
* if implementation capacities are exceeded.</p>
126
* @param lexicalRepresentation <code>String</code> representation of a <code>Duration</code>.
128
* @return New <code>Duration</code> created from parsing the <code>lexicalRepresentation</code>.
130
* @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code>.
131
* @throws UnsupportedOperationException If implementation cannot support requested values.
132
* @throws NullPointerException if <code>lexicalRepresentation</code> is <code>null</code>.
134
public abstract Duration newDuration(final String lexicalRepresentation);
137
* <p>Obtain a new instance of a <code>Duration</code>
138
* specifying the <code>Duration</code> as milliseconds.</p>
140
* <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
142
* duration represents a duration of time.
143
* The value space of duration is a six-dimensional space where the coordinates designate the
144
* Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
145
* These components are ordered in their significance by their order of appearance i.e. as
146
* year, month, day, hour, minute, and second.
148
* <p>All six values are set by computing their values from the specified milliseconds
149
* and are availabe using the <code>get</code> methods of the created {@link Duration}.
150
* The values conform to and are defined by:</p>
152
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
153
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
154
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
156
* <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
159
* <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
160
* {@link java.util.Calendar#YEAR} = 1970,
161
* {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
162
* {@link java.util.Calendar#DATE} = 1, etc.
163
* This is important as there are variations in the Gregorian Calendar,
164
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
165
* so the result of {@link Duration#getMonths()} and {@link Duration#getDays()} can be influenced.</p>
167
* @param durationInMilliSeconds Duration in milliseconds to create.
169
* @return New <code>Duration</code> representing <code>durationInMilliSeconds</code>.
171
public abstract Duration newDuration(final long durationInMilliSeconds);
174
* <p>Obtain a new instance of a <code>Duration</code>
175
* specifying the <code>Duration</code> as isPositive, years, months, days, hours, minutes, seconds.</p>
177
* <p>The XML Schema specification states that values can be of an arbitrary size.
178
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
179
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
180
* if implementation capacities are exceeded.</p>
182
* <p>A <code>null</code> value indicates that field isnot set.</p>
184
* @param isPositive Set to <code>false</code> to create a negative duration. When the length
185
* of the duration is zero, this parameter will be ignored.
186
* @param years of this <code>Duration</code>
187
* @param months of this <code>Duration</code>
188
* @param days of this <code>Duration</code>
189
* @param hours of this <code>Duration</code>
190
* @param minutes of this <code>Duration</code>
191
* @param seconds of this <code>Duration</code>
193
* @return New <code>Duration</code> created from the specified values.
195
* @throws IllegalArgumentException If values are not a valid representation of a <code>Duration</code>.
196
* @throws UnsupportedOperationException If implementation cannot support requested values.
198
public abstract Duration newDuration(
199
final boolean isPositive,
200
final BigInteger years,
201
final BigInteger months,
202
final BigInteger days,
203
final BigInteger hours,
204
final BigInteger minutes,
205
final BigDecimal seconds);
208
* <p>Obtain a new instance of a <code>Duration</code>
209
* specifying the <code>Duration</code> as isPositive, years, months, days, hours, minutes, seconds.</p>
211
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
213
* @param isPositive Set to <code>false</code> to create a negative duration. When the length
214
* of the duration is zero, this parameter will be ignored.
215
* @param years of this <code>Duration</code>
216
* @param months of this <code>Duration</code>
217
* @param days of this <code>Duration</code>
218
* @param hours of this <code>Duration</code>
219
* @param minutes of this <code>Duration</code>
220
* @param seconds of this <code>Duration</code>
222
* @return New <code>Duration</code> created from the specified values.
224
* @throws IllegalArgumentException If values are not a valid representation of a <code>Duration</code>.
227
* boolean isPositive,
232
* BigInteger minutes,
233
* BigDecimal seconds)
235
public Duration newDuration(
236
final boolean isPositive,
244
// years may not be set
245
BigInteger realYears = (years != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) years) : null;
247
// months may not be set
248
BigInteger realMonths = (months != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) months) : null;
250
// days may not be set
251
BigInteger realDays = (days != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) days) : null;
253
// hours may not be set
254
BigInteger realHours = (hours != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) hours) : null;
256
// minutes may not be set
257
BigInteger realMinutes = (minutes != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) minutes) : null;
259
// seconds may not be set
260
BigDecimal realSeconds = (seconds != DatatypeConstants.FIELD_UNDEFINED) ? BigDecimal.valueOf((long) seconds) : null;
274
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> by parsing its <code>String</code> representation,
275
* "<em>PnDTnHnMnS</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">
276
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
278
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
279
* whose lexical representation contains only day, hour, minute, and second components.
280
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
282
* <p>All four values are set and availabe from the created {@link Duration}</p>
284
* <p>The XML Schema specification states that values can be of an arbitrary size.
285
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
286
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
287
* if implementation capacities are exceeded.</p>
289
* @param lexicalRepresentation Lexical representation of a duration.
291
* @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>.
293
* @throws IllegalArgumentException If the given string does not conform to the aforementioned specification.
294
* @throws UnsupportedOperationException If implementation cannot support requested values.
295
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
297
public Duration newDurationDayTime(final String lexicalRepresentation) {
299
return newDuration(lexicalRepresentation);
303
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified milliseconds as defined in
304
* <a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">
305
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
307
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
308
* whose lexical representation contains only day, hour, minute, and second components.
309
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
311
* <p>All four values are set by computing their values from the specified milliseconds
312
* and are availabe using the <code>get</code> methods of the created {@link Duration}.
313
* The values conform to and are defined by:</p>
315
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
316
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
317
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
319
* <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
322
* <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
323
* {@link java.util.Calendar#YEAR} = 1970,
324
* {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
325
* {@link java.util.Calendar#DATE} = 1, etc.
326
* This is important as there are variations in the Gregorian Calendar,
327
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
328
* so the result of {@link Duration#getDays()} can be influenced.</p>
330
* <p>Any remaining milliseconds after determining the day, hour, minute and second are discarded.</p>
332
* @param durationInMilliseconds Milliseconds of <code>Duration</code> to create.
334
* @return New <code>Duration</code> created with the specified <code>durationInMilliseconds</code>.
336
* @see <a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">
337
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>
339
public Duration newDurationDayTime(final long durationInMilliseconds) {
341
return newDuration(durationInMilliseconds);
345
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified
346
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in
347
* <a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">
348
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
350
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
351
* whose lexical representation contains only day, hour, minute, and second components.
352
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
354
* <p>The XML Schema specification states that values can be of an arbitrary size.
355
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
356
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
357
* if implementation capacities are exceeded.</p>
359
* <p>A <code>null</code> value indicates that field isnot set.</p>
361
* @param isPositive Set to <code>false</code> to create a negative duration. When the length
362
* of the duration is zero, this parameter will be ignored.
363
* @param day Day of <code>Duration</code>.
364
* @param hour Hour of <code>Duration</code>.
365
* @param minute Minute of <code>Duration</code>.
366
* @param second Second of <code>Duration</code>.
368
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code>
369
* and <code>second</code>.
371
* @throws IllegalArgumentException If any values would create an invalid <code>Duration</code>.
372
* @throws UnsupportedOperationException If implementation cannot support requested values.
374
public Duration newDurationDayTime(
375
final boolean isPositive,
376
final BigInteger day,
377
final BigInteger hour,
378
final BigInteger minute,
379
final BigInteger second) {
388
(second != null)? new BigDecimal(second):null
393
* <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified
394
* <code>day</code>, <code>hour</code>, <code>minute</code> and <code>second</code> as defined in
395
* <a href="http://www.w3.org/TR/xpath-datamodel#dt-dayTimeDuration">
396
* XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
398
* <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
399
* whose lexical representation contains only day, hour, minute, and second components.
400
* This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
402
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
404
* @param isPositive Set to <code>false</code> to create a negative duration. When the length
405
* of the duration is zero, this parameter will be ignored.
406
* @param day Day of <code>Duration</code>.
407
* @param hour Hour of <code>Duration</code>.
408
* @param minute Minute of <code>Duration</code>.
409
* @param second Second of <code>Duration</code>.
411
* @return New <code>Duration</code> created with the specified <code>day</code>, <code>hour</code>, <code>minute</code>
412
* and <code>second</code>.
414
* @throws IllegalArgumentException If any values would create an invalid <code>Duration</code>.
416
public Duration newDurationDayTime(
417
final boolean isPositive,
423
return newDurationDayTime(
425
BigInteger.valueOf((long) day),
426
BigInteger.valueOf((long) hour),
427
BigInteger.valueOf((long) minute),
428
BigInteger.valueOf((long) second)
433
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> by parsing its <code>String</code> representation,
434
* "<em>PnYnM</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration">
435
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
437
* <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code>
438
* whose lexical representation contains only year and month components.
439
* This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p>
441
* <p>Both values are set and availabe from the created {@link Duration}</p>
443
* <p>The XML Schema specification states that values can be of an arbitrary size.
444
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
445
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
446
* if implementation capacities are exceeded.</p>
448
* @param lexicalRepresentation Lexical representation of a duration.
450
* @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>.
452
* @throws IllegalArgumentException If the <code>lexicalRepresentation</code> does not conform to the specification.
453
* @throws UnsupportedOperationException If implementation cannot support requested values.
454
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
456
public Duration newDurationYearMonth(final String lexicalRepresentation) {
458
return newDuration(lexicalRepresentation);
462
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified milliseconds as defined in
463
* <a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthDuration">
464
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
466
* <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code>
467
* whose lexical representation contains only year and month components.
468
* This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p>
470
* <p>Both values are set by computing their values from the specified milliseconds
471
* and are availabe using the <code>get</code> methods of the created {@link Duration}.
472
* The values conform to and are defined by:</p>
474
* <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
475
* <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
476
* W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
478
* <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
481
* <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
482
* {@link java.util.Calendar#YEAR} = 1970,
483
* {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
484
* {@link java.util.Calendar#DATE} = 1, etc.
485
* This is important as there are variations in the Gregorian Calendar,
486
* e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
487
* so the result of {@link Duration#getMonths()} can be influenced.</p>
489
* <p>Any remaining milliseconds after determining the year and month are discarded.</p>
491
* @param durationInMilliseconds Milliseconds of <code>Duration</code> to create.
493
* @return New <code>Duration</code> created using the specified <code>durationInMilliseconds</code>.
495
public Duration newDurationYearMonth(final long durationInMilliseconds) {
497
return newDuration(durationInMilliseconds);
501
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified
502
* <code>year</code> and <code>month</code> as defined in
503
* <a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthyDuration">
504
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
506
* <p>The XML Schema specification states that values can be of an arbitrary size.
507
* Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
508
* An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
509
* if implementation capacities are exceeded.</p>
511
* <p>A <code>null</code> value indicates that field isnot set.</p>
513
* @param isPositive Set to <code>false</code> to create a negative duration. When the length
514
* of the duration is zero, this parameter will be ignored.
515
* @param year Year of <code>Duration</code>.
516
* @param month Month of <code>Duration</code>.
518
* @return New <code>Duration</code> created using the specified <code>year</code> and <code>month</code>.
520
* @throws IllegalArgumentException If any values would create an invalid <code>Duration</code>.
521
* @throws UnsupportedOperationException If implementation cannot support requested values.
523
public Duration newDurationYearMonth(
524
final boolean isPositive,
525
final BigInteger year,
526
final BigInteger month) {
540
* <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified
541
* <code>year</code> and <code>month</code> as defined in
542
* <a href="http://www.w3.org/TR/xpath-datamodel#dt-yearMonthyDuration">
543
* XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
545
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
547
* @param isPositive Set to <code>false</code> to create a negative duration. When the length
548
* of the duration is zero, this parameter will be ignored.
549
* @param year Year of <code>Duration</code>.
550
* @param month Month of <code>Duration</code>.
552
* @return New <code>Duration</code> created using the specified <code>year</code> and <code>month</code>.
554
* @throws IllegalArgumentException If any values would create an invalid <code>Duration</code>.
556
public Duration newDurationYearMonth(
557
final boolean isPositive,
561
return newDurationYearMonth(
563
BigInteger.valueOf((long) year),
564
BigInteger.valueOf((long) month));
568
* <p>Create a new instance of an <code>XMLGregorianCalendar</code>.</p>
570
* <p>All date/time datatype fields set to {@link DatatypeConstants#FIELD_UNDEFINED} or null.</p>
572
* @return New <code>XMLGregorianCalendar</code> with all date/time datatype fields set to
573
* {@link DatatypeConstants#FIELD_UNDEFINED} or null.
575
public abstract XMLGregorianCalendar newXMLGregorianCalendar();
578
* <p>Create a new XMLGregorianCalendar by parsing the String as a lexical representation.</p>
580
* <p>Parsing the lexical string representation is defined in
581
* <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-order">XML Schema 1.0 Part 2, Section 3.2.[7-14].1,
582
* <em>Lexical Representation</em>.</a></p>
584
* <p>The string representation may not have any leading and trailing whitespaces.</p>
586
* <p>The parsing is done field by field so that
587
* the following holds for any lexically correct String x:</p>
589
* newXMLGregorianCalendar(x).toXMLFormat().equals(x)
591
* <p>Except for the noted lexical/canonical representation mismatches
592
* listed in <a href="http://www.w3.org/2001/05/xmlschema-errata#e2-45">
593
* XML Schema 1.0 errata, Section 3.2.7.2</a>.</p>
595
* @param lexicalRepresentation Lexical representation of one the eight XML Schema date/time datatypes.
597
* @return <code>XMLGregorianCalendar</code> created from the <code>lexicalRepresentation</code>.
599
* @throws IllegalArgumentException If the <code>lexicalRepresentation</code> is not a valid <code>XMLGregorianCalendar</code>.
600
* @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
602
public abstract XMLGregorianCalendar newXMLGregorianCalendar(final String lexicalRepresentation);
605
* <p>Create an <code>XMLGregorianCalendar</code> from a {@link GregorianCalendar}.</p>
607
* <table border="2" rules="all" cellpadding="2">
610
* <th align="center" colspan="2">
611
* Field by Field Conversion from
612
* {@link GregorianCalendar} to an {@link XMLGregorianCalendar}
616
* <th><code>java.util.GregorianCalendar</code> field</th>
617
* <th><code>javax.xml.datatype.XMLGregorianCalendar</code> field</th>
622
* <td><code>ERA == GregorianCalendar.BC ? -YEAR : YEAR</code></td>
623
* <td>{@link XMLGregorianCalendar#setYear(int year)}</td>
626
* <td><code>MONTH + 1</code></td>
627
* <td>{@link XMLGregorianCalendar#setMonth(int month)}</td>
630
* <td><code>DAY_OF_MONTH</code></td>
631
* <td>{@link XMLGregorianCalendar#setDay(int day)}</td>
634
* <td><code>HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND</code></td>
635
* <td>{@link XMLGregorianCalendar#setTime(int hour, int minute, int second, BigDecimal fractional)}</td>
639
* <code>(ZONE_OFFSET + DST_OFFSET) / (60*1000)</code><br/>
640
* <em>(in minutes)</em>
642
* <td>{@link XMLGregorianCalendar#setTimezone(int offset)}<sup><em>*</em></sup>
647
* <p><em>*</em>conversion loss of information. It is not possible to represent
648
* a <code>java.util.GregorianCalendar</code> daylight savings timezone id in the
649
* XML Schema 1.0 date/time datatype representation.</p>
651
* <p>To compute the return value's <code>TimeZone</code> field,
653
* <li>when <code>this.getTimezone() != FIELD_UNDEFINED</code>,
654
* create a <code>java.util.TimeZone</code> with a custom timezone id
655
* using the <code>this.getTimezone()</code>.</li>
656
* <li>else use the <code>GregorianCalendar</code> default timezone value
657
* for the host is defined as specified by
658
* <code>java.util.TimeZone.getDefault()</code>.</li></p>
660
* @param cal <code>java.util.GregorianCalendar</code> used to create <code>XMLGregorianCalendar</code>
662
* @return <code>XMLGregorianCalendar</code> created from <code>java.util.GregorianCalendar</code>
664
* @throws NullPointerException If <code>cal</code> is <code>null</code>.
666
public abstract XMLGregorianCalendar newXMLGregorianCalendar(final GregorianCalendar cal);
669
* <p>Constructor allowing for complete value spaces allowed by
670
* W3C XML Schema 1.0 recommendation for xsd:dateTime and related
671
* builtin datatypes. Note that <code>year</code> parameter supports
672
* arbitrarily large numbers and fractionalSecond has infinite
675
* <p>A <code>null</code> value indicates that field isnot set.</p>
677
* @param year of <code>XMLGregorianCalendar</code> to be created.
678
* @param month of <code>XMLGregorianCalendar</code> to be created.
679
* @param day of <code>XMLGregorianCalendar</code> to be created.
680
* @param hour of <code>XMLGregorianCalendar</code> to be created.
681
* @param minute of <code>XMLGregorianCalendar</code> to be created.
682
* @param second of <code>XMLGregorianCalendar</code> to be created.
683
* @param fractionalSecond of <code>XMLGregorianCalendar</code> to be created.
684
* @param timezone of <code>XMLGregorianCalendar</code> to be created.
686
* @return <code>XMLGregorianCalendar</code> created from specified values.
688
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
689
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
690
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance
691
* as determined by {@link XMLGregorianCalendar#isValid()}.
693
public abstract XMLGregorianCalendar newXMLGregorianCalendar(
694
final BigInteger year,
700
final BigDecimal fractionalSecond,
704
* <p>Constructor of value spaces that a
705
* <code>java.util.GregorianCalendar</code> instance would need to convert to an
706
* <code>XMLGregorianCalendar</code> instance.</p>
708
* <p><code>XMLGregorianCalendar eon</code> and
709
* <code>fractionalSecond</code> are set to <code>null</code></p>
711
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
713
* @param year of <code>XMLGregorianCalendar</code> to be created.
714
* @param month of <code>XMLGregorianCalendar</code> to be created.
715
* @param day of <code>XMLGregorianCalendar</code> to be created.
716
* @param hour of <code>XMLGregorianCalendar</code> to be created.
717
* @param minute of <code>XMLGregorianCalendar</code> to be created.
718
* @param second of <code>XMLGregorianCalendar</code> to be created.
719
* @param millisecond of <code>XMLGregorianCalendar</code> to be created.
720
* @param timezone of <code>XMLGregorianCalendar</code> to be created.
722
* @return <code>XMLGregorianCalendar</code> created from specified values.
724
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
725
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
726
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance
727
* as determined by {@link XMLGregorianCalendar#isValid()}.
729
public XMLGregorianCalendar newXMLGregorianCalendar(
736
final int millisecond,
737
final int timezone) {
739
// year may be undefined
740
BigInteger realYear = (year != DatatypeConstants.FIELD_UNDEFINED) ? BigInteger.valueOf((long) year) : null;
742
// millisecond may be undefined
743
// millisecond must be >= 0 millisecond <= 1000
744
BigDecimal realMillisecond = null; // undefined value
745
if (millisecond != DatatypeConstants.FIELD_UNDEFINED) {
746
if (millisecond < 0 || millisecond > 1000) {
747
throw new IllegalArgumentException(
748
"javax.xml.datatype.DatatypeFactory#newXMLGregorianCalendar("
749
+ "int year, int month, int day, int hour, int minute, int second, int millisecond, int timezone)"
750
+ "with invalid millisecond: " + millisecond
754
realMillisecond = BigDecimal.valueOf((long) millisecond).movePointLeft(3);
757
return newXMLGregorianCalendar(
770
* <p>Create a Java representation of XML Schema builtin datatype <code>date</code> or <code>g*</code>.</p>
772
* <p>For example, an instance of <code>gYear</code> can be created invoking this factory
773
* with <code>month</code> and <code>day</code> parameters set to
774
* {@link DatatypeConstants#FIELD_UNDEFINED}.</p>
776
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
778
* @param year of <code>XMLGregorianCalendar</code> to be created.
779
* @param month of <code>XMLGregorianCalendar</code> to be created.
780
* @param day of <code>XMLGregorianCalendar</code> to be created.
781
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
783
* @return <code>XMLGregorianCalendar</code> created from parameter values.
785
* @see DatatypeConstants#FIELD_UNDEFINED
787
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
788
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
789
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance
790
* as determined by {@link XMLGregorianCalendar#isValid()}.
792
public XMLGregorianCalendar newXMLGregorianCalendarDate(
796
final int timezone) {
798
return newXMLGregorianCalendar(
802
DatatypeConstants.FIELD_UNDEFINED, // hour
803
DatatypeConstants.FIELD_UNDEFINED, // minute
804
DatatypeConstants.FIELD_UNDEFINED, // second
805
DatatypeConstants.FIELD_UNDEFINED, // millisecond
810
* <p>Create a Java instance of XML Schema builtin datatype <code>time</code>.</p>
812
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
814
* @param hours number of hours
815
* @param minutes number of minutes
816
* @param seconds number of seconds
817
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
819
* @return <code>XMLGregorianCalendar</code> created from parameter values.
821
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
822
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
823
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance
824
* as determined by {@link XMLGregorianCalendar#isValid()}.
826
* @see DatatypeConstants#FIELD_UNDEFINED
828
public XMLGregorianCalendar newXMLGregorianCalendarTime(
832
final int timezone) {
834
return newXMLGregorianCalendar(
835
DatatypeConstants.FIELD_UNDEFINED, // Year
836
DatatypeConstants.FIELD_UNDEFINED, // Month
837
DatatypeConstants.FIELD_UNDEFINED, // Day
841
DatatypeConstants.FIELD_UNDEFINED, //Millisecond
846
* <p>Create a Java instance of XML Schema builtin datatype time.</p>
848
* <p>A <code>null</code> value indicates that field isnot set.</p>
849
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
851
* @param hours number of hours
852
* @param minutes number of minutes
853
* @param seconds number of seconds
854
* @param fractionalSecond value of <code>null</code> indicates that this optional field is not set.
855
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
857
* @return <code>XMLGregorianCalendar</code> created from parameter values.
859
* @see DatatypeConstants#FIELD_UNDEFINED
861
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
862
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
863
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance
864
* as determined by {@link XMLGregorianCalendar#isValid()}.
866
public XMLGregorianCalendar newXMLGregorianCalendarTime(
870
final BigDecimal fractionalSecond,
871
final int timezone) {
873
return newXMLGregorianCalendar(
875
DatatypeConstants.FIELD_UNDEFINED, // month
876
DatatypeConstants.FIELD_UNDEFINED, // day
885
* <p>Create a Java instance of XML Schema builtin datatype time.</p>
887
* <p>A {@link DatatypeConstants#FIELD_UNDEFINED} value indicates that field isnot set.</p>
889
* @param hours number of hours
890
* @param minutes number of minutes
891
* @param seconds number of seconds
892
* @param milliseconds number of milliseconds
893
* @param timezone offset in minutes. {@link DatatypeConstants#FIELD_UNDEFINED} indicates optional field is not set.
895
* @return <code>XMLGregorianCalendar</code> created from parameter values.
897
* @see DatatypeConstants#FIELD_UNDEFINED
899
* @throws IllegalArgumentException If any individual parameter's value is outside the maximum value constraint for the field
900
* as determined by the Date/Time Data Mapping table in {@link XMLGregorianCalendar}
901
* or if the composite values constitute an invalid <code>XMLGregorianCalendar</code> instance
902
* as determined by {@link XMLGregorianCalendar#isValid()}.
904
public XMLGregorianCalendar newXMLGregorianCalendarTime(
908
final int milliseconds,
909
final int timezone) {
911
// millisecond may be undefined
912
// millisecond must be >= 0 millisecond <= 1000
913
BigDecimal realMilliseconds = null; // undefined value
914
if (milliseconds != DatatypeConstants.FIELD_UNDEFINED) {
915
if (milliseconds < 0 || milliseconds > 1000) {
916
throw new IllegalArgumentException(
917
"javax.xml.datatype.DatatypeFactory#newXMLGregorianCalendarTime("
918
+ "int hours, int minutes, int seconds, int milliseconds, int timezone)"
919
+ "with invalid milliseconds: " + milliseconds
923
realMilliseconds = BigDecimal.valueOf((long) milliseconds).movePointLeft(3);
926
return newXMLGregorianCalendarTime(
added
removed
javax/xml/datatype/DatatypeFactory.java
