1 /*
2 * Copyright (c) 2003, 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
28 import org.w3c.dom.Node;
29
30 import java.util.Collections;
31 import java.util.Map;
32 import java.util.Properties;
33 import java.io.IOException;
34 import java.io.InputStream;
35
36 /**
37 * <p>
38 * The <tt>JAXBContext</tt> class provides the client's entry point to the
39 * JAXB API. It provides an abstraction for managing the XML/Java binding
40 * information necessary to implement the JAXB binding framework operations:
41 * unmarshal, marshal and validate.
42 *
43 * <p>A client application normally obtains new instances of this class using
44 * one of these two styles for newInstance methods, although there are other
45 * specialized forms of the method available:
46 *
47 * <ul>
48 * <li>{@link #newInstance(String,ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br/>
49 * The JAXBContext instance is initialized from a list of colon
50 * separated Java package names. Each java package contains
51 * JAXB mapped classes, schema-derived classes and/or user annotated
52 * classes. Additionally, the java package may contain JAXB package annotations
53 * that must be processed. (see JLS, Section 7.4.1 "Named Packages").
54 * </li>
55 * <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br/>
56 * The JAXBContext instance is initialized with class(es)
57 * passed as parameter(s) and classes that are statically reachable from
58 * these class(es). See {@link #newInstance(Class...)} for details.
59 * </li>
60 * </ul>
61 *
62 * <p>
63 * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation
64 * class containing the following method signatures:</i>
65 *
66 * <pre>
67 * public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException
68 * public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException
69 * </pre>
70 *
71 * <p><i>
72 * The following JAXB 1.0 requirement is only required for schema to
73 * java interface/implementation binding. It does not apply to JAXB annotated
74 * classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in
75 * each package containing schema derived classes. The property file must
76 * contain a property named <tt>javax.xml.bind.context.factory</tt> whose
77 * value is the name of the class that implements the <tt>createContext</tt>
78 * APIs.</i>
79 *
80 * <p><i>
81 * The class supplied by the provider does not have to be assignable to
82 * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that
83 * implements the <tt>createContext</tt> APIs.</i>
84 *
85 * <p><i>
86 * In addition, the provider must call the
87 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
88 * DatatypeConverter.setDatatypeConverter} api prior to any client
239 * is assumed to be the provider factory class. This phase of the look up is for automatic discovery.
240 * It allows users to just put a JAXB implementation in a classpath and use it without any furhter configuration.
241 *
242 * <li>
243 * Finally, if all the steps above fail, then the rest of the look up is unspecified. That said,
244 * the recommended behavior is to simply look for some hard-coded platform default JAXB implementation.
245 * This phase of the look up is so that JavaSE can have its own JAXB implementation as the last resort.
246 * </ol>
247 *
248 * <p>
249 * Once the provider factory class is discovered, its
250 * <tt>public static JAXBContext createContext(String,ClassLoader,Map)</tt> method
251 * (see {@link #newInstance(String, ClassLoader, Map)} for the parameter semantics.)
252 * or <tt>public static JAXBContext createContet(Class[],Map)</tt> method
253 * (see {@link #newInstance(Class[], Map)} for the parameter semantics) are invoked
254 * to create a {@link JAXBContext}.
255 *
256 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
257 * @see Marshaller
258 * @see Unmarshaller
259 * @see S 7.4.1 "Named Packages" in Java Language Specification</a>
260 * @since 1.6, JAXB 1.0
261 */
262 public abstract class JAXBContext {
263
264 /**
265 * The name of the property that contains the name of the class capable
266 * of creating new <tt>JAXBContext</tt> objects.
267 */
268 public static final String JAXB_CONTEXT_FACTORY =
269 "javax.xml.bind.context.factory";
270
271
272 protected JAXBContext() {
273 }
274
275
276 /**
277 * <p>
278 * Obtain a new instance of a <tt>JAXBContext</tt> class.
279 *
335 * lines, are ignored. The comment character
336 * is '#' (0x23); on each line all characters following the first comment
337 * character are ignored. The file must be encoded in UTF-8. Classes that
338 * are reachable, as defined in {@link #newInstance(Class...)}, from the
339 * listed classes are also registered with JAXBContext.
340 * <p>
341 * Constraints on class name occuring in a <tt>jaxb.index</tt> file are:
342 * <ul>
343 * <li>Must not end with ".class".</li>
344 * <li>Class names are resolved relative to package containing
345 * <tt>jaxb.index</tt> file. Only classes occuring directly in package
346 * containing <tt>jaxb.index</tt> file are allowed.</li>
347 * <li>Fully qualified class names are not allowed.
348 * A qualified class name,relative to current package,
349 * is only allowed to specify a nested or inner class.</li>
350 * </ul>
351 *
352 * <p>
353 * To maintain compatibility with JAXB 1.0 schema to java
354 * interface/implementation binding, enabled by schema customization
355 * <tt><jaxb:globalBindings valueClass="false"></tt>,
356 * the JAXB provider will ensure that each package on the context path
357 * has a <tt>jaxb.properties</tt> file which contains a value for the
358 * <tt>javax.xml.bind.context.factory</tt> property and that all values
359 * resolve to the same provider. This requirement does not apply to
360 * JAXB annotated classes.
361 *
362 * <p>
363 * If there are any global XML element name collisions across the various
364 * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt>
365 * will be thrown.
366 *
367 * <p>
368 * Mixing generated interface/impl bindings from multiple JAXB Providers
369 * in the same context path may result in a <tt>JAXBException</tt>
370 * being thrown.
371 *
372 * <p>
373 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
374 *
375 * @param contextPath list of java package names that contain schema
|
1 /*
2 * Copyright (c) 2003, 2015, 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
28 import org.w3c.dom.Node;
29
30 import java.util.Collections;
31 import java.util.Map;
32 import java.util.Properties;
33 import java.io.IOException;
34 import java.io.InputStream;
35
36 /**
37 * <p>
38 * The <tt>JAXBContext</tt> class provides the client's entry point to the
39 * JAXB API. It provides an abstraction for managing the XML/Java binding
40 * information necessary to implement the JAXB binding framework operations:
41 * unmarshal, marshal and validate.
42 *
43 * <p>A client application normally obtains new instances of this class using
44 * one of these two styles for newInstance methods, although there are other
45 * specialized forms of the method available:
46 *
47 * <ul>
48 * <li>{@link #newInstance(String,ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br>
49 * The JAXBContext instance is initialized from a list of colon
50 * separated Java package names. Each java package contains
51 * JAXB mapped classes, schema-derived classes and/or user annotated
52 * classes. Additionally, the java package may contain JAXB package annotations
53 * that must be processed. (see JLS, Section 7.4.1 "Named Packages").
54 * </li>
55 * <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br>
56 * The JAXBContext instance is initialized with class(es)
57 * passed as parameter(s) and classes that are statically reachable from
58 * these class(es). See {@link #newInstance(Class...)} for details.
59 * </li>
60 * </ul>
61 *
62 * <p>
63 * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation
64 * class containing the following method signatures:</i>
65 *
66 * <pre>
67 * public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException
68 * public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException
69 * </pre>
70 *
71 * <p><i>
72 * The following JAXB 1.0 requirement is only required for schema to
73 * java interface/implementation binding. It does not apply to JAXB annotated
74 * classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in
75 * each package containing schema derived classes. The property file must
76 * contain a property named <tt>javax.xml.bind.context.factory</tt> whose
77 * value is the name of the class that implements the <tt>createContext</tt>
78 * APIs.</i>
79 *
80 * <p><i>
81 * The class supplied by the provider does not have to be assignable to
82 * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that
83 * implements the <tt>createContext</tt> APIs.</i>
84 *
85 * <p><i>
86 * In addition, the provider must call the
87 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
88 * DatatypeConverter.setDatatypeConverter} api prior to any client
239 * is assumed to be the provider factory class. This phase of the look up is for automatic discovery.
240 * It allows users to just put a JAXB implementation in a classpath and use it without any furhter configuration.
241 *
242 * <li>
243 * Finally, if all the steps above fail, then the rest of the look up is unspecified. That said,
244 * the recommended behavior is to simply look for some hard-coded platform default JAXB implementation.
245 * This phase of the look up is so that JavaSE can have its own JAXB implementation as the last resort.
246 * </ol>
247 *
248 * <p>
249 * Once the provider factory class is discovered, its
250 * <tt>public static JAXBContext createContext(String,ClassLoader,Map)</tt> method
251 * (see {@link #newInstance(String, ClassLoader, Map)} for the parameter semantics.)
252 * or <tt>public static JAXBContext createContet(Class[],Map)</tt> method
253 * (see {@link #newInstance(Class[], Map)} for the parameter semantics) are invoked
254 * to create a {@link JAXBContext}.
255 *
256 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
257 * @see Marshaller
258 * @see Unmarshaller
259 * @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1">S 7.4.1 "Named Packages" in Java Language Specification</a>
260 * @since 1.6, JAXB 1.0
261 */
262 public abstract class JAXBContext {
263
264 /**
265 * The name of the property that contains the name of the class capable
266 * of creating new <tt>JAXBContext</tt> objects.
267 */
268 public static final String JAXB_CONTEXT_FACTORY =
269 "javax.xml.bind.context.factory";
270
271
272 protected JAXBContext() {
273 }
274
275
276 /**
277 * <p>
278 * Obtain a new instance of a <tt>JAXBContext</tt> class.
279 *
335 * lines, are ignored. The comment character
336 * is '#' (0x23); on each line all characters following the first comment
337 * character are ignored. The file must be encoded in UTF-8. Classes that
338 * are reachable, as defined in {@link #newInstance(Class...)}, from the
339 * listed classes are also registered with JAXBContext.
340 * <p>
341 * Constraints on class name occuring in a <tt>jaxb.index</tt> file are:
342 * <ul>
343 * <li>Must not end with ".class".</li>
344 * <li>Class names are resolved relative to package containing
345 * <tt>jaxb.index</tt> file. Only classes occuring directly in package
346 * containing <tt>jaxb.index</tt> file are allowed.</li>
347 * <li>Fully qualified class names are not allowed.
348 * A qualified class name,relative to current package,
349 * is only allowed to specify a nested or inner class.</li>
350 * </ul>
351 *
352 * <p>
353 * To maintain compatibility with JAXB 1.0 schema to java
354 * interface/implementation binding, enabled by schema customization
355 * <tt><jaxb:globalBindings valueClass="false"></tt>,
356 * the JAXB provider will ensure that each package on the context path
357 * has a <tt>jaxb.properties</tt> file which contains a value for the
358 * <tt>javax.xml.bind.context.factory</tt> property and that all values
359 * resolve to the same provider. This requirement does not apply to
360 * JAXB annotated classes.
361 *
362 * <p>
363 * If there are any global XML element name collisions across the various
364 * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt>
365 * will be thrown.
366 *
367 * <p>
368 * Mixing generated interface/impl bindings from multiple JAXB Providers
369 * in the same context path may result in a <tt>JAXBException</tt>
370 * being thrown.
371 *
372 * <p>
373 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
374 *
375 * @param contextPath list of java package names that contain schema
|