1 /*
2 * Copyright (c) 2004, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.datatype;
27
28 import java.math.BigInteger;
29 import java.math.BigDecimal;
30 import java.util.GregorianCalendar;
31 import java.util.regex.Matcher;
32 import java.util.regex.Pattern;
33
34 /**
35 * <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>
36 *
37 * <p><a name="DatatypeFactory.newInstance"/>{@link #newInstance()} is used to create a new <code>DatatypeFactory</code>.
38 * The following implementation resolution mechanisms are used in the following order:</p>
39 * <ol>
40 * <li>
41 * If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>",
42 * exists, a class with the name of the property's value is instantiated.
43 * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
44 * </li>
45 * <li>
46 * If the file ${JAVA_HOME}/lib/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>.
47 * The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step
48 * and processed as documented in the prior step.
49 * </li>
50 * <li>
51 * The services resolution mechanism is used, e.g. <code>META-INF/services/java.xml.datatype.DatatypeFactory</code>.
52 * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
53 * </li>
54 * <li>
55 * The final mechanism is to attempt to instantiate the <code>Class</code> specified by
56 * {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}.
57 * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
58 * </li>
59 * </ol>
60 *
61 * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
62 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
63 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
64 *
65 * @version $Revision: 1.13 $, $Date: 2010/03/11 23:10:53 $
66 * @since 1.5
67 */
68 public abstract class DatatypeFactory {
69
70 /**
71 * <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
72 *
73 * <p>Default value is <code>javax.xml.datatype.DatatypeFactory</code>.</p>
74 */
75 public static final String DATATYPEFACTORY_PROPERTY = "javax.xml.datatype.DatatypeFactory";
76
77 /**
78 * <p>Default implementation class name as defined in
79 * <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.</p>
80 *
81 * <p>Implementers should specify the name of an appropriate class
82 * to be instantiated if no other implementation resolution mechanism
83 * succeeds.</p>
84 *
85 * <p>Users should not refer to this field; it is intended only to
86 * document a factory implementation detail.
87 * </p>
88 */
89 public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS = new String("com.sun.org.apache.xerces.internal.jaxp.datatype.DatatypeFactoryImpl");
90
91 /**
92 * http://www.w3.org/TR/xpath-datamodel/#xdtschema defines two regexps
93 * to constrain the value space of dayTimeDuration ([^YM]*[DT].*)
94 * and yearMonthDuration ([^DT]*). Note that these expressions rely on
95 * the fact that the value must be an xs:Duration, they simply exclude
96 * some Durations.
97 */
98 private static final Pattern XDTSCHEMA_YMD =
99 Pattern.compile("[^DT]*");
100
101 private static final Pattern XDTSCHEMA_DTD =
102 Pattern.compile("[^YM]*[DT].*");
103
104 /**
105 * <p>Protected constructor to prevent instaniation outside of package.</p>
106 *
107 * <p>Use {@link #newInstance()} to create a <code>DatatypeFactory</code>.</p>
108 */
109 protected DatatypeFactory() {
110 }
111
112 /**
113 * <p>Obtain a new instance of a <code>DatatypeFactory</code>.</p>
114 *
115 * <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
116 * <code>Class</code>'s documentation.</p>
117 *
118 * @return New instance of a <code>DatatypeFactory</code>
119 *
120 * @throws DatatypeConfigurationException If the implementation is not
121 * available or cannot be instantiated.
122 *
123 * @see #newInstance(String factoryClassName, ClassLoader classLoader)
124 */
125 public static DatatypeFactory newInstance()
126 throws DatatypeConfigurationException {
127
128 try {
129 return (DatatypeFactory) FactoryFinder.find(
130 /* The default property name according to the JAXP spec */
131 DATATYPEFACTORY_PROPERTY,
132 /* The fallback implementation class name */
133 DATATYPEFACTORY_IMPLEMENTATION_CLASS);
134 } catch (FactoryFinder.ConfigurationError e) {
135 throw new DatatypeConfigurationException(e.getMessage(), e.getException());
136 }
137 }
138
139 /**
140 * <p>Obtain a new instance of a <code>DatatypeFactory</code> from class name.
141 * This function is useful when there are multiple providers in the classpath.
142 * It gives more control to the application as it can specify which provider
143 * should be loaded.</p>
144 *
145 * <p>Once an application has obtained a reference to a <code>DatatypeFactory</code>
146 * it can use the factory to configure and obtain datatype instances.</P>
147 *
148 *
149 * <h2>Tip for Trouble-shooting</h2>
150 * <p>Setting the <code>jaxp.debug</code> system property will cause
151 * this method to print a lot of debug messages
152 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
153 *
154 * <p> If you have problems try:</p>
155 * <pre>
156 * java -Djaxp.debug=1 YourProgram ....
157 * </pre>
158 *
159 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.datatype.DatatypeFactory</code>.
160 *
161 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
162 * current <code>Thread</code>'s context classLoader is used to load the factory class.
163 *
164 * @return New instance of a <code>DatatypeFactory</code>
165 *
166 * @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or
167 * the factory class cannot be loaded, instantiated.
168 *
169 * @see #newInstance()
170 *
171 * @since 1.6
172 */
173 public static DatatypeFactory newInstance(String factoryClassName, ClassLoader classLoader)
174 throws DatatypeConfigurationException {
175 try {
176 return (DatatypeFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
177 } catch (FactoryFinder.ConfigurationError e) {
178 throw new DatatypeConfigurationException(e.getMessage(), e.getException());
179 }
180 }
181
182 /**
183 * <p>Obtain a new instance of a <code>Duration</code>
184 * specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS",
185 * as defined in XML Schema 1.0 section 3.2.6.1.</p>
186 *
187 * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
188 * <blockquote>
189 * duration represents a duration of time.
190 * The value space of duration is a six-dimensional space where the coordinates designate the
191 * Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
192 * These components are ordered in their significance by their order of appearance i.e. as
193 * year, month, day, hour, minute, and second.
194 * </blockquote>
195 * <p>All six values are set and availabe from the created {@link Duration}</p>
196 *
197 * <p>The XML Schema specification states that values can be of an arbitrary size.
198 * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
199 * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
200 * if implementation capacities are exceeded.</p>
201 *
202 * @param lexicalRepresentation <code>String</code> representation of a <code>Duration</code>.
203 *
204 * @return New <code>Duration</code> created from parsing the <code>lexicalRepresentation</code>.
205 *
206 * @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code>.
207 * @throws UnsupportedOperationException If implementation cannot support requested values.
208 * @throws NullPointerException if <code>lexicalRepresentation</code> is <code>null</code>.
209 */
210 public abstract Duration newDuration(final String lexicalRepresentation);
211
212 /**
213 * <p>Obtain a new instance of a <code>Duration</code>
214 * specifying the <code>Duration</code> as milliseconds.</p>
215 *
216 * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
217 * <blockquote>
218 * duration represents a duration of time.
219 * The value space of duration is a six-dimensional space where the coordinates designate the
220 * Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
221 * These components are ordered in their significance by their order of appearance i.e. as
222 * year, month, day, hour, minute, and second.
223 * </blockquote>
224 * <p>All six values are set by computing their values from the specified milliseconds
225 * and are availabe using the <code>get</code> methods of the created {@link Duration}.
226 * The values conform to and are defined by:</p>
227 * <ul>
228 * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
229 * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
230 * W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
231 * </li>
232 * <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
233 * </ul>
234 *
235 * <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
236 * {@link java.util.Calendar#YEAR} = 1970,
237 * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
238 * {@link java.util.Calendar#DATE} = 1, etc.
239 * This is important as there are variations in the Gregorian Calendar,
240 * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
241 * so the result of {@link Duration#getMonths()} and {@link Duration#getDays()} can be influenced.</p>
242 *
243 * @param durationInMilliSeconds Duration in milliseconds to create.
244 *
245 * @return New <code>Duration</code> representing <code>durationInMilliSeconds</code>.
341 return newDuration(
342 isPositive,
343 realYears,
344 realMonths,
345 realDays,
346 realHours,
347 realMinutes,
348 realSeconds
349 );
350 }
351
352 /**
353 * <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> by parsing its <code>String</code> representation,
354 * "<em>PnDTnHnMnS</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
355 * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
356 *
357 * <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
358 * whose lexical representation contains only day, hour, minute, and second components.
359 * This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
360 *
361 * <p>All four values are set and availabe from the created {@link Duration}</p>
362 *
363 * <p>The XML Schema specification states that values can be of an arbitrary size.
364 * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
365 * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
366 * if implementation capacities are exceeded.</p>
367 *
368 * @param lexicalRepresentation Lexical representation of a duration.
369 *
370 * @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>.
371 *
372 * @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of days and time.
373 * @throws UnsupportedOperationException If implementation cannot support requested values.
374 * @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
375 */
376 public Duration newDurationDayTime(final String lexicalRepresentation) {
377 // lexicalRepresentation must be non-null
378 if (lexicalRepresentation == null) {
379 throw new NullPointerException(
380 "Trying to create an xdt:dayTimeDuration with an invalid"
381 + " lexical representation of \"null\"");
386 if (!matcher.matches()) {
387 throw new IllegalArgumentException(
388 "Trying to create an xdt:dayTimeDuration with an invalid"
389 + " lexical representation of \"" + lexicalRepresentation
390 + "\", data model requires years and months only.");
391 }
392
393 return newDuration(lexicalRepresentation);
394 }
395
396 /**
397 * <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified milliseconds as defined in
398 * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
399 * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
400 *
401 * <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
402 * whose lexical representation contains only day, hour, minute, and second components.
403 * This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
404 *
405 * <p>All four values are set by computing their values from the specified milliseconds
406 * and are availabe using the <code>get</code> methods of the created {@link Duration}.
407 * The values conform to and are defined by:</p>
408 * <ul>
409 * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
410 * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
411 * W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
412 * </li>
413 * <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
414 * </ul>
415 *
416 * <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
417 * {@link java.util.Calendar#YEAR} = 1970,
418 * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
419 * {@link java.util.Calendar#DATE} = 1, etc.
420 * This is important as there are variations in the Gregorian Calendar,
421 * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
422 * so the result of {@link Duration#getDays()} can be influenced.</p>
423 *
424 * <p>Any remaining milliseconds after determining the day, hour, minute and second are discarded.</p>
425 *
426 * @param durationInMilliseconds Milliseconds of <code>Duration</code> to create.
518 final int second) {
519
520 return newDurationDayTime(
521 isPositive,
522 BigInteger.valueOf((long) day),
523 BigInteger.valueOf((long) hour),
524 BigInteger.valueOf((long) minute),
525 BigInteger.valueOf((long) second)
526 );
527 }
528
529 /**
530 * <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> by parsing its <code>String</code> representation,
531 * "<em>PnYnM</em>", <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
532 * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
533 *
534 * <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code>
535 * whose lexical representation contains only year and month components.
536 * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p>
537 *
538 * <p>Both values are set and availabe from the created {@link Duration}</p>
539 *
540 * <p>The XML Schema specification states that values can be of an arbitrary size.
541 * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
542 * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
543 * if implementation capacities are exceeded.</p>
544 *
545 * @param lexicalRepresentation Lexical representation of a duration.
546 *
547 * @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>.
548 *
549 * @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of years and months.
550 * @throws UnsupportedOperationException If implementation cannot support requested values.
551 * @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
552 */
553 public Duration newDurationYearMonth(
554 final String lexicalRepresentation) {
555
556 // lexicalRepresentation must be non-null
557 if (lexicalRepresentation == null) {
558 throw new NullPointerException(
565 if (!matcher.matches()) {
566 throw new IllegalArgumentException(
567 "Trying to create an xdt:yearMonthDuration with an invalid"
568 + " lexical representation of \"" + lexicalRepresentation
569 + "\", data model requires days and times only.");
570 }
571
572 return newDuration(lexicalRepresentation);
573 }
574
575 /**
576 * <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified milliseconds as defined in
577 * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
578 * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
579 *
580 * <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code>
581 * whose lexical representation contains only year and month components.
582 * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p>
583 *
584 * <p>Both values are set by computing their values from the specified milliseconds
585 * and are availabe using the <code>get</code> methods of the created {@link Duration}.
586 * The values conform to and are defined by:</p>
587 * <ul>
588 * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
589 * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
590 * W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
591 * </li>
592 * <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
593 * </ul>
594 *
595 * <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
596 * {@link java.util.Calendar#YEAR} = 1970,
597 * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
598 * {@link java.util.Calendar#DATE} = 1, etc.
599 * This is important as there are variations in the Gregorian Calendar,
600 * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
601 * so the result of {@link Duration#getMonths()} can be influenced.</p>
602 *
603 * <p>Any remaining milliseconds after determining the year and month are discarded.</p>
604 *
605 * @param durationInMilliseconds Milliseconds of <code>Duration</code> to create.
|
1 /*
2 * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.datatype;
27
28 import java.math.BigDecimal;
29 import java.math.BigInteger;
30 import java.util.GregorianCalendar;
31 import java.util.regex.Matcher;
32 import java.util.regex.Pattern;
33
34 /**
35 * <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>
36 *
37 * <p>A new instance of the <code>DatatypeFactory</code> is created through the {@link #newInstance()} method
38 * that uses the following implementation resolution mechanisms to determine an implementation:</p>
39 * <ol>
40 * <li>
41 * If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>",
42 * exists, a class with the name of the property value is instantiated.
43 * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
44 * </li>
45 * <li>
46 * If the file ${JAVA_HOME}/lib/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>.
47 * The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step
48 * and processed as documented in the prior step.
49 * </li>
50 * <li>
51 * Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
52 * to locate and load an implementation of the service.
53 * <br>
54 * In case of {@link java.util.ServiceConfigurationError service
55 * configuration error} a {@link javax.xml.datatype.DatatypeConfigurationException}
56 * will be thrown.
57 * </li>
58 * <li>
59 * The final mechanism is to attempt to instantiate the <code>Class</code> specified by
60 * {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}.
61 * Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
62 * </li>
63 * </ol>
64 *
65 * @author <a href="mailto:Joseph.Fialli@Sun.COM">Joseph Fialli</a>
66 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
67 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
68 *
69 * @version $Revision: 1.13 $, $Date: 2010/03/11 23:10:53 $
70 * @since 1.5
71 */
72 public abstract class DatatypeFactory {
73
74 /**
75 * <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
76 *
77 * <p>Default value is <code>javax.xml.datatype.DatatypeFactory</code>.</p>
78 */
79 public static final String DATATYPEFACTORY_PROPERTY =
80 // We use a String constant here, rather than calling
81 // DatatypeFactory.class.getName() - in order to make javadoc
82 // generate a See Also: Constant Field Value link.
83 "javax.xml.datatype.DatatypeFactory";
84
85 /**
86 * <p>Default implementation class name as defined in
87 * <em>JSR 206: Java(TM) API for XML Processing (JAXP) 1.3</em>.</p>
88 *
89 * <p>Implementers should specify the name of an appropriate class
90 * to be instantiated if no other implementation resolution mechanism
91 * succeeds.</p>
92 *
93 * <p>Users should not refer to this field; it is intended only to
94 * document a factory implementation detail.
95 * </p>
96 */
97 public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS =
98 // We use new String() here to prevent javadoc from generating
99 // a See Also: Constant Field Value link.
100 new String("com.sun.org.apache.xerces.internal.jaxp.datatype.DatatypeFactoryImpl");
101
102 /**
103 * http://www.w3.org/TR/xpath-datamodel/#xdtschema defines two regexps
104 * to constrain the value space of dayTimeDuration ([^YM]*[DT].*)
105 * and yearMonthDuration ([^DT]*). Note that these expressions rely on
106 * the fact that the value must be an xs:Duration, they simply exclude
107 * some Durations.
108 */
109 private static final Pattern XDTSCHEMA_YMD =
110 Pattern.compile("[^DT]*");
111
112 private static final Pattern XDTSCHEMA_DTD =
113 Pattern.compile("[^YM]*[DT].*");
114
115 /**
116 * <p>Protected constructor to prevent instaniation outside of package.</p>
117 *
118 * <p>Use {@link #newInstance()} to create a <code>DatatypeFactory</code>.</p>
119 */
120 protected DatatypeFactory() {
121 }
122
123 /**
124 * <p>Obtain a new instance of a <code>DatatypeFactory</code>.</p>
125 *
126 * <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
127 * <code>Class</code>'s documentation.</p>
128 *
129 * @return New instance of a <code>DatatypeFactory</code>
130 *
131 * @throws DatatypeConfigurationException If the implementation is not
132 * available or cannot be instantiated.
133 *
134 * @see #newInstance(String factoryClassName, ClassLoader classLoader)
135 */
136 public static DatatypeFactory newInstance()
137 throws DatatypeConfigurationException {
138
139 return FactoryFinder.find(
140 /* The default property name according to the JAXP spec */
141 DatatypeFactory.class,
142 /* The fallback implementation class name */
143 DATATYPEFACTORY_IMPLEMENTATION_CLASS);
144 }
145
146 /**
147 * <p>Obtain a new instance of a <code>DatatypeFactory</code> from class name.
148 * This function is useful when there are multiple providers in the classpath.
149 * It gives more control to the application as it can specify which provider
150 * should be loaded.</p>
151 *
152 * <p>Once an application has obtained a reference to a <code>DatatypeFactory</code>
153 * it can use the factory to configure and obtain datatype instances.</P>
154 *
155 *
156 * <h2>Tip for Trouble-shooting</h2>
157 * <p>Setting the <code>jaxp.debug</code> system property will cause
158 * this method to print a lot of debug messages
159 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
160 *
161 * <p> If you have problems try:</p>
162 * <pre>
163 * java -Djaxp.debug=1 YourProgram ....
164 * </pre>
165 *
166 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.datatype.DatatypeFactory</code>.
167 *
168 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
169 * current <code>Thread</code>'s context classLoader is used to load the factory class.
170 *
171 * @return New instance of a <code>DatatypeFactory</code>
172 *
173 * @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or
174 * the factory class cannot be loaded, instantiated.
175 *
176 * @see #newInstance()
177 *
178 * @since 1.6
179 */
180 public static DatatypeFactory newInstance(String factoryClassName, ClassLoader classLoader)
181 throws DatatypeConfigurationException {
182 return FactoryFinder.newInstance(DatatypeFactory.class,
183 factoryClassName, classLoader, false);
184 }
185
186 /**
187 * <p>Obtain a new instance of a <code>Duration</code>
188 * specifying the <code>Duration</code> as its string representation, "PnYnMnDTnHnMnS",
189 * as defined in XML Schema 1.0 section 3.2.6.1.</p>
190 *
191 * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
192 * <blockquote>
193 * duration represents a duration of time.
194 * The value space of duration is a six-dimensional space where the coordinates designate the
195 * Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
196 * These components are ordered in their significance by their order of appearance i.e. as
197 * year, month, day, hour, minute, and second.
198 * </blockquote>
199 * <p>All six values are set and available from the created {@link Duration}</p>
200 *
201 * <p>The XML Schema specification states that values can be of an arbitrary size.
202 * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
203 * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
204 * if implementation capacities are exceeded.</p>
205 *
206 * @param lexicalRepresentation <code>String</code> representation of a <code>Duration</code>.
207 *
208 * @return New <code>Duration</code> created from parsing the <code>lexicalRepresentation</code>.
209 *
210 * @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code>.
211 * @throws UnsupportedOperationException If implementation cannot support requested values.
212 * @throws NullPointerException if <code>lexicalRepresentation</code> is <code>null</code>.
213 */
214 public abstract Duration newDuration(final String lexicalRepresentation);
215
216 /**
217 * <p>Obtain a new instance of a <code>Duration</code>
218 * specifying the <code>Duration</code> as milliseconds.</p>
219 *
220 * <p>XML Schema Part 2: Datatypes, 3.2.6 duration, defines <code>duration</code> as:</p>
221 * <blockquote>
222 * duration represents a duration of time.
223 * The value space of duration is a six-dimensional space where the coordinates designate the
224 * Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively.
225 * These components are ordered in their significance by their order of appearance i.e. as
226 * year, month, day, hour, minute, and second.
227 * </blockquote>
228 * <p>All six values are set by computing their values from the specified milliseconds
229 * and are available using the <code>get</code> methods of the created {@link Duration}.
230 * The values conform to and are defined by:</p>
231 * <ul>
232 * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
233 * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
234 * W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
235 * </li>
236 * <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
237 * </ul>
238 *
239 * <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
240 * {@link java.util.Calendar#YEAR} = 1970,
241 * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
242 * {@link java.util.Calendar#DATE} = 1, etc.
243 * This is important as there are variations in the Gregorian Calendar,
244 * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
245 * so the result of {@link Duration#getMonths()} and {@link Duration#getDays()} can be influenced.</p>
246 *
247 * @param durationInMilliSeconds Duration in milliseconds to create.
248 *
249 * @return New <code>Duration</code> representing <code>durationInMilliSeconds</code>.
345 return newDuration(
346 isPositive,
347 realYears,
348 realMonths,
349 realDays,
350 realHours,
351 realMinutes,
352 realSeconds
353 );
354 }
355
356 /**
357 * <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> by parsing its <code>String</code> representation,
358 * "<em>PnDTnHnMnS</em>", <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
359 * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
360 *
361 * <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
362 * whose lexical representation contains only day, hour, minute, and second components.
363 * This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
364 *
365 * <p>All four values are set and available from the created {@link Duration}</p>
366 *
367 * <p>The XML Schema specification states that values can be of an arbitrary size.
368 * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
369 * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
370 * if implementation capacities are exceeded.</p>
371 *
372 * @param lexicalRepresentation Lexical representation of a duration.
373 *
374 * @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>.
375 *
376 * @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of days and time.
377 * @throws UnsupportedOperationException If implementation cannot support requested values.
378 * @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
379 */
380 public Duration newDurationDayTime(final String lexicalRepresentation) {
381 // lexicalRepresentation must be non-null
382 if (lexicalRepresentation == null) {
383 throw new NullPointerException(
384 "Trying to create an xdt:dayTimeDuration with an invalid"
385 + " lexical representation of \"null\"");
390 if (!matcher.matches()) {
391 throw new IllegalArgumentException(
392 "Trying to create an xdt:dayTimeDuration with an invalid"
393 + " lexical representation of \"" + lexicalRepresentation
394 + "\", data model requires years and months only.");
395 }
396
397 return newDuration(lexicalRepresentation);
398 }
399
400 /**
401 * <p>Create a <code>Duration</code> of type <code>xdt:dayTimeDuration</code> using the specified milliseconds as defined in
402 * <a href="http://www.w3.org/TR/xpath-datamodel#dayTimeDuration">
403 * XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration</a>.</p>
404 *
405 * <p>The datatype <code>xdt:dayTimeDuration</code> is a subtype of <code>xs:duration</code>
406 * whose lexical representation contains only day, hour, minute, and second components.
407 * This datatype resides in the namespace <code>http://www.w3.org/2003/11/xpath-datatypes</code>.</p>
408 *
409 * <p>All four values are set by computing their values from the specified milliseconds
410 * and are available using the <code>get</code> methods of the created {@link Duration}.
411 * The values conform to and are defined by:</p>
412 * <ul>
413 * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
414 * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
415 * W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
416 * </li>
417 * <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
418 * </ul>
419 *
420 * <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
421 * {@link java.util.Calendar#YEAR} = 1970,
422 * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
423 * {@link java.util.Calendar#DATE} = 1, etc.
424 * This is important as there are variations in the Gregorian Calendar,
425 * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
426 * so the result of {@link Duration#getDays()} can be influenced.</p>
427 *
428 * <p>Any remaining milliseconds after determining the day, hour, minute and second are discarded.</p>
429 *
430 * @param durationInMilliseconds Milliseconds of <code>Duration</code> to create.
522 final int second) {
523
524 return newDurationDayTime(
525 isPositive,
526 BigInteger.valueOf((long) day),
527 BigInteger.valueOf((long) hour),
528 BigInteger.valueOf((long) minute),
529 BigInteger.valueOf((long) second)
530 );
531 }
532
533 /**
534 * <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> by parsing its <code>String</code> representation,
535 * "<em>PnYnM</em>", <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
536 * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
537 *
538 * <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code>
539 * whose lexical representation contains only year and month components.
540 * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p>
541 *
542 * <p>Both values are set and available from the created {@link Duration}</p>
543 *
544 * <p>The XML Schema specification states that values can be of an arbitrary size.
545 * Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values.
546 * An {@link UnsupportedOperationException} will be thrown with a message indicating implementation limits
547 * if implementation capacities are exceeded.</p>
548 *
549 * @param lexicalRepresentation Lexical representation of a duration.
550 *
551 * @return New <code>Duration</code> created using the specified <code>lexicalRepresentation</code>.
552 *
553 * @throws IllegalArgumentException If <code>lexicalRepresentation</code> is not a valid representation of a <code>Duration</code> expressed only in terms of years and months.
554 * @throws UnsupportedOperationException If implementation cannot support requested values.
555 * @throws NullPointerException If <code>lexicalRepresentation</code> is <code>null</code>.
556 */
557 public Duration newDurationYearMonth(
558 final String lexicalRepresentation) {
559
560 // lexicalRepresentation must be non-null
561 if (lexicalRepresentation == null) {
562 throw new NullPointerException(
569 if (!matcher.matches()) {
570 throw new IllegalArgumentException(
571 "Trying to create an xdt:yearMonthDuration with an invalid"
572 + " lexical representation of \"" + lexicalRepresentation
573 + "\", data model requires days and times only.");
574 }
575
576 return newDuration(lexicalRepresentation);
577 }
578
579 /**
580 * <p>Create a <code>Duration</code> of type <code>xdt:yearMonthDuration</code> using the specified milliseconds as defined in
581 * <a href="http://www.w3.org/TR/xpath-datamodel#yearMonthDuration">
582 * XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration</a>.</p>
583 *
584 * <p>The datatype <code>xdt:yearMonthDuration</code> is a subtype of <code>xs:duration</code>
585 * whose lexical representation contains only year and month components.
586 * This datatype resides in the namespace {@link javax.xml.XMLConstants#W3C_XPATH_DATATYPE_NS_URI}.</p>
587 *
588 * <p>Both values are set by computing their values from the specified milliseconds
589 * and are available using the <code>get</code> methods of the created {@link Duration}.
590 * The values conform to and are defined by:</p>
591 * <ul>
592 * <li>ISO 8601:2000(E) Section 5.5.3.2 Alternative format</li>
593 * <li><a href="http://www.w3.org/TR/xmlschema-2/#isoformats">
594 * W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats</a>
595 * </li>
596 * <li>{@link XMLGregorianCalendar} Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation</li>
597 * </ul>
598 *
599 * <p>The default start instance is defined by {@link GregorianCalendar}'s use of the start of the epoch: i.e.,
600 * {@link java.util.Calendar#YEAR} = 1970,
601 * {@link java.util.Calendar#MONTH} = {@link java.util.Calendar#JANUARY},
602 * {@link java.util.Calendar#DATE} = 1, etc.
603 * This is important as there are variations in the Gregorian Calendar,
604 * e.g. leap years have different days in the month = {@link java.util.Calendar#FEBRUARY}
605 * so the result of {@link Duration#getMonths()} can be influenced.</p>
606 *
607 * <p>Any remaining milliseconds after determining the year and month are discarded.</p>
608 *
609 * @param durationInMilliseconds Milliseconds of <code>Duration</code> to create.
|