1 /*
2 * Copyright (c) 2003, 2017, 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.bind;
27
28 import org.w3c.dom.Node;
29
30 import java.io.IOException;
31 import java.io.InputStream;
32 import java.util.Collections;
33 import java.util.Map;
34 import java.util.Properties;
35
36 /**
37 * The {@code JAXBContext} class provides the client's entry point to the
38 * JAXB API. It provides an abstraction for managing the XML/Java binding
39 * information necessary to implement the JAXB binding framework operations:
40 * unmarshal, marshal and validate.
41 *
42 * <p>A client application normally obtains new instances of this class using
43 * one of these two styles for newInstance methods, although there are other
44 * specialized forms of the method available:
45 *
46 * <ul>
47 * <li>{@link #newInstance(String, ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br>
48 * The JAXBContext instance is initialized from a list of colon
49 * separated Java package names. Each java package contains
50 * JAXB mapped classes, schema-derived classes and/or user annotated
51 * classes. Additionally, the java package may contain JAXB package annotations
52 * that must be processed. (see JLS, Section 7.4.1 "Named Packages").
53 * </li>
54 * <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br>
55 * The JAXBContext instance is initialized with class(es)
56 * passed as parameter(s) and classes that are statically reachable from
57 * these class(es). See {@link #newInstance(Class...)} for details.
58 * </li>
59 * </ul>
60 *
61 * <p><i>
62 * The following JAXB 1.0 requirement is only required for schema to
63 * java interface/implementation binding. It does not apply to JAXB annotated
64 * classes. JAXB Providers must generate a {@code jaxb.properties} file in
65 * each package containing schema derived classes. The property file must
66 * contain a property named {@code javax.xml.bind.context.factory} whose
67 * value is the name of the class that implements the {@code createContext}
68 * APIs.</i>
69 *
70 * <p><i>
71 * The class supplied by the provider does not have to be assignable to
72 * {@code javax.xml.bind.JAXBContext}, it simply has to provide a class that
73 * implements the {@code createContext} APIs.</i>
74 *
75 * <p><i>
76 * In addition, the provider must call the
77 * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)
78 * DatatypeConverter.setDatatypeConverter} api prior to any client
79 * invocations of the marshal and unmarshal methods. This is necessary to
80 * configure the datatype converter that will be used during these operations.</i>
81 *
82 * <a name="Unmarshalling"></a>
83 * <h3>Unmarshalling</h3>
84 * <p>
85 * The {@link Unmarshaller} class provides the client application the ability
86 * to convert XML data into a tree of Java content objects.
87 * The unmarshal method allows for
88 * any global XML element declared in the schema to be unmarshalled as
89 * the root of an instance document.
90 * Additionally, the unmarshal method allows for an unrecognized root element that
91 * has an xsi:type attribute's value that references a type definition declared in
92 * the schema to be unmarshalled as the root of an instance document.
93 * The {@code JAXBContext} object
94 * allows the merging of global elements and type definitions across a set of schemas (listed
95 * in the {@code contextPath}). Since each schema in the schema set can belong
96 * to distinct namespaces, the unification of schemas to an unmarshalling
97 * context must be namespace independent. This means that a client
98 * application is able to unmarshal XML documents that are instances of
99 * any of the schemas listed in the {@code contextPath}. For example:
100 *
101 * <pre>
102 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
103 * Unmarshaller u = jc.createUnmarshaller();
104 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
105 * BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
106 * BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
107 * </pre>
108 *
109 * <p>
110 * The client application may also generate Java content trees explicitly rather
111 * than unmarshalling existing XML data. For all JAXB-annotated value classes,
112 * an application can create content using constructors.
113 * For schema-derived interface/implementation classes and for the
114 * creation of elements that are not bound to a JAXB-annotated
115 * class, an application needs to have access and knowledge about each of
116 * the schema derived {@code ObjectFactory} classes that exist in each of
117 * java packages contained in the {@code contextPath}. For each schema
118 * derived java class, there is a static factory method that produces objects
119 * of that type. For example,
120 * assume that after compiling a schema, you have a package {@code com.acme.foo}
121 * that contains a schema derived interface named {@code PurchaseOrder}. In
122 * order to create objects of that type, the client application would use the
123 * factory method like this:
124 *
125 * <pre>
126 * com.acme.foo.PurchaseOrder po =
127 * com.acme.foo.ObjectFactory.createPurchaseOrder();
128 * </pre>
129 *
130 * <p>
131 * Once the client application has an instance of the the schema derived object,
132 * it can use the mutator methods to set content on it.
133 *
134 * <p>
135 * For more information on the generated {@code ObjectFactory} classes, see
136 * Section 4.2 <i>Java Package</i> of the specification.
137 *
138 * <p>
139 * <i>The provider must generate a class in each
140 * package that contains all of the necessary object factory methods for that
141 * package named ObjectFactory as well as the static
142 * {@code newInstance( javaContentInterface )} method</i>
143 *
144 * <h3>Marshalling</h3>
145 * <p>
146 * The {@link Marshaller} class provides the client application the ability
147 * to convert a Java content tree back into XML data. There is no difference
148 * between marshalling a content tree that is created manually using the factory
149 * methods and marshalling a content tree that is the result an {@code unmarshal}
150 * operation. Clients can marshal a java content tree back to XML data
151 * to a {@code java.io.OutputStream} or a {@code java.io.Writer}. The
152 * marshalling process can alternatively produce SAX2 event streams to a
153 * registered {@code ContentHandler} or produce a DOM Node object.
154 * Client applications have control over the output encoding as well as
155 * whether or not to marshal the XML data as a complete document or
156 * as a fragment.
157 *
158 * <p>
159 * Here is a simple example that unmarshals an XML document and then marshals
160 * it back out:
161 *
162 * <pre>
163 * JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
164 *
165 * // unmarshal from foo.xml
166 * Unmarshaller u = jc.createUnmarshaller();
167 * FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );
168 *
169 * // marshal to System.out
170 * Marshaller m = jc.createMarshaller();
171 * m.marshal( fooObj, System.out );
172 * </pre>
173 *
174 *
175 * <h3>Validation</h3>
176 * <p>
177 * Validation has been changed significantly since JAXB 1.0. The {@link Validator}
178 * class has been deprecated and made optional. This means that you are advised
179 * not to use this class and, in fact, it may not even be available depending on
180 * your JAXB provider. JAXB 1.0 client applications that rely on {@code Validator}
181 * will still work properly when deployed with the JAXB 1.0 runtime system.
182 *
183 * In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose
184 * the JAXP 1.3 {@link javax.xml.validation} framework. Please refer to the
185 * {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more
186 * information.
187 *
188 *
189 * <h3>JAXB Runtime Binding Framework Compatibility</h3>
190 * <p>
191 * The following JAXB 1.0 restriction only applies to binding schema to
192 * interfaces/implementation classes.
193 * Since this binding does not require a common runtime system, a JAXB
194 * client application must not attempt to mix runtime objects ({@code JAXBContext,
195 * Marshaller}, etc. ) from different providers. This does not
196 * mean that the client application isn't portable, it simply means that a
197 * client has to use a runtime system provided by the same provider that was
198 * used to compile the schema.
199 *
200 *
201 * <h3>Discovery of JAXB implementation</h3>
202 * <p>
203 * To create an instance of {@link JAXBContext}, one of {@code JAXBContext.newInstance(...)} methods is invoked. After
204 * JAX-B implementation is discovered, call is delegated to appropriate provider's method {@code createContext(...)}
205 * passing parameters from the original call.
206 * <p>
207 * JAX-B implementation discovery happens each time {@code JAXBContext.newInstance} is invoked. If there is no user
208 * specific configuration provided, default JAX-B provider must be returned.
209 * <p>
210 * Implementation discovery consists of following steps:
211 *
212 * <ol>
213 *
214 * <li>
215 * Packages/classes explicitly passed in to the {@link #newInstance} method are processed in the order they are
216 * specified, until {@code jaxb.properties} file is looked up in its package, by using the associated classloader —
217 * this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package
218 * the specified {@link ClassLoader}.
219 *
220 * <p>
221 * If such a resource is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and
222 * the value of the {@link #JAXB_CONTEXT_FACTORY} key will be assumed to be the provider factory class. If no value
223 * found, {@code "javax.xml.bind.context.factory"} is used as a key for backwards compatibility reasons. This class is
224 * then loaded by the associated class loader discussed above.
225 *
226 * <p>
227 * This phase of the look up allows some packages to force the use of a certain JAXB implementation.
228 * (For example, perhaps the schema compiler has generated some vendor extension in the code.)
229 *
230 * <p>
231 * This configuration method is deprecated.
232 *
233 * <li>
234 * If the system property {@link #JAXB_CONTEXT_FACTORY} exists, then its value is assumed to be the provider
235 * factory class. If no such property exists, properties {@code "javax.xml.bind.context.factory"} and
236 * {@code "javax.xml.bind.JAXBContext"} are checked too (in this order), for backwards compatibility reasons. This phase
237 * of the look up enables per-JVM override of the JAXB implementation.
238 *
239 * <li>
240 * Provider of {@link javax.xml.bind.JAXBContextFactory} is loaded using the service-provider loading
241 * facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
242 * to locate and load an implementation of the service using the {@linkplain
243 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: the service-provider loading facility
244 * will use the {@linkplain java.lang.Thread#getContextClassLoader() current thread's context class loader}
245 * to attempt to load the context factory. If the context class loader is null, the
246 * {@linkplain ClassLoader#getSystemClassLoader() system class loader} will be used.
247 * <br>
248 * In case of {@link java.util.ServiceConfigurationError service
249 * configuration error} a {@link javax.xml.bind.JAXBException} will be thrown.
250 *
251 * <li>
252 * Look for resource {@code /META-INF/services/javax.xml.bind.JAXBContext} using provided class loader.
253 * Methods without class loader parameter use {@code Thread.currentThread().getContextClassLoader()}.
254 * If such a resource exists, its content is assumed to be the provider factory class.
255 *
256 * This configuration method is deprecated.
257 *
258 * <li>
259 * Finally, if all the steps above fail, then the rest of the look up is unspecified. That said,
260 * the recommended behavior is to simply look for some hard-coded platform default JAXB implementation.
261 * This phase of the look up is so that Java SE can have its own JAXB implementation as the last resort.
262 * </ol>
263 *
264 * <p>
265 * Once the provider factory class is discovered, context creation is delegated to one of its
266 * {@code createContext(...)} methods.
267 *
268 * For backward compatibility reasons, there are two ways how to implement provider factory class:
269 * <ol>
270 * <li>the class is implementation of {@link javax.xml.bind.JAXBContextFactory}. It must also implement no-arg
271 * constructor. If discovered in other step then 3, new instance using no-arg constructor is created first.
272 * After that, appropriate instance method is invoked on this instance.
273 * <li>the class is not implementation of interface above and then it is mandated to implement the following
274 * static method signatures:
275 * <pre>
276 *
277 * public static JAXBContext createContext(
278 * String contextPath,
279 * ClassLoader classLoader,
280 * Map<String,Object> properties ) throws JAXBException
281 *
282 * public static JAXBContext createContext(
283 * Class[] classes,
284 * Map<String,Object> properties ) throws JAXBException
285 * </pre>
286 * In this scenario, appropriate static method is used instead of instance method. This approach is incompatible
287 * with {@link java.util.ServiceLoader} so it can't be used with step 3.
288 * </ol>
289 * <p>
290 * There is no difference in behavior of given method {@code createContext(...)} regardless of whether it uses approach
291 * 1 (JAXBContextFactory) or 2 (no interface, static methods).
292 *
293 * @apiNote
294 * Service discovery method using resource {@code /META-INF/services/javax.xml.bind.JAXBContext} (described in step 4)
295 * is supported only to allow backwards compatibility, it is strongly recommended to migrate to standard
296 * {@link java.util.ServiceLoader} mechanism (described in step 3). The difference here is the resource name, which
297 * doesn't match service's type name.
298 * <p>
299 * Also using providers implementing interface {@link JAXBContextFactory} is preferred over using ones defining
300 * static methods, same as {@link JAXBContext#JAXB_CONTEXT_FACTORY} property is preferred over property
301 * {@code "javax.xml.bind.context.factory"}
302 *
303 * @implNote
304 * Within the last step, if Glassfish AS environment detected, its specific service loader is used to find factory class.
305 *
306 * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li>
307 * <li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li>
308 * <li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
309 *
310 * @see Marshaller
311 * @see Unmarshaller
312 * @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"
313 * in Java Language Specification</a>
314 *
315 * @since 1.6, JAXB 1.0
316 */
317 public abstract class JAXBContext {
318
319 /**
320 * The name of the property that contains the name of the class capable
321 * of creating new {@code JAXBContext} objects.
322 */
323 public static final String JAXB_CONTEXT_FACTORY = "javax.xml.bind.JAXBContextFactory";
324
325 protected JAXBContext() {
326 }
327
328
329 /**
330 * Create a new instance of a {@code JAXBContext} class.
331 *
332 * <p>
333 * This is a convenience method to invoke the
334 * {@link #newInstance(String,ClassLoader)} method with
335 * the context class loader of the current thread.
336 *
337 * @throws JAXBException if an error was encountered while creating the
338 * {@code JAXBContext} such as
339 * <ol>
340 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
341 * <li>an ambiguity among global elements contained in the contextPath</li>
342 * <li>failure to locate a value for the context factory provider property</li>
343 * <li>mixing schema derived packages from different providers on the same contextPath</li>
344 * <li>packages are not open to {@code java.xml.bind} module</li>
345 * </ol>
346 */
347 public static JAXBContext newInstance( String contextPath )
348 throws JAXBException {
349
350 //return newInstance( contextPath, JAXBContext.class.getClassLoader() );
351 return newInstance( contextPath, getContextClassLoader());
352 }
353
354 /**
355 * Create a new instance of a {@code JAXBContext} class.
356 *
357 * <p>
358 * The client application must supply a context path which is a list of
359 * colon (':', \u005Cu003A) separated java package names that contain
360 * schema-derived classes and/or fully qualified JAXB-annotated classes.
361 * Schema-derived
362 * code is registered with the JAXBContext by the
363 * ObjectFactory.class generated per package.
364 * Alternatively than being listed in the context path, programmer
365 * annotated JAXB mapped classes can be listed in a
366 * {@code jaxb.index} resource file, format described below.
367 * Note that a java package can contain both schema-derived classes and
368 * user annotated JAXB classes. Additionally, the java package may
369 * contain JAXB package annotations that must be processed. (see JLS,
370 * Section 7.4.1 "Named Packages").
371 * </p>
372 *
373 * <p>
374 * Every package listed on the contextPath must meet <b>one or both</b> of the
375 * following conditions otherwise a {@code JAXBException} will be thrown:
376 * </p>
377 * <ol>
378 * <li>it must contain ObjectFactory.class</li>
379 * <li>it must contain jaxb.index</li>
380 * </ol>
381 *
382 * <p>
383 * <b>Format for jaxb.index</b>
384 * <p>
385 * The file contains a newline-separated list of class names.
386 * Space and tab characters, as well as blank
387 * lines, are ignored. The comment character
388 * is '#' (0x23); on each line all characters following the first comment
389 * character are ignored. The file must be encoded in UTF-8. Classes that
390 * are reachable, as defined in {@link #newInstance(Class...)}, from the
391 * listed classes are also registered with JAXBContext.
392 * <p>
393 * Constraints on class name occuring in a {@code jaxb.index} file are:
394 * <ul>
395 * <li>Must not end with ".class".</li>
396 * <li>Class names are resolved relative to package containing
397 * {@code jaxb.index} file. Only classes occuring directly in package
398 * containing {@code jaxb.index} file are allowed.</li>
399 * <li>Fully qualified class names are not allowed.
400 * A qualified class name,relative to current package,
401 * is only allowed to specify a nested or inner class.</li>
402 * </ul>
403 *
404 * <p>
405 * To maintain compatibility with JAXB 1.0 schema to java
406 * interface/implementation binding, enabled by schema customization
407 * {@code <jaxb:globalBindings valueClass="false">},
408 * the JAXB provider will ensure that each package on the context path
409 * has a {@code jaxb.properties} file which contains a value for the
410 * {@code javax.xml.bind.context.factory} property and that all values
411 * resolve to the same provider. This requirement does not apply to
412 * JAXB annotated classes.
413 *
414 * <p>
415 * If there are any global XML element name collisions across the various
416 * packages listed on the {@code contextPath}, a {@code JAXBException}
417 * will be thrown.
418 *
419 * <p>
420 * Mixing generated interface/impl bindings from multiple JAXB Providers
421 * in the same context path may result in a {@code JAXBException}
422 * being thrown.
423 *
424 * <p>
425 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
426 *
427 * @param contextPath
428 * List of java package names that contain schema
429 * derived class and/or java to schema (JAXB-annotated)
430 * mapped classes.
431 * Packages in {@code contextPath} that are in named modules must be
432 * {@linkplain java.lang.Module#isOpen open} to at least the {@code java.xml.bind} module.
433 * @param classLoader
434 * This class loader will be used to locate the implementation
435 * classes.
436 *
437 * @return a new instance of a {@code JAXBContext}
438 * @throws JAXBException if an error was encountered while creating the
439 * {@code JAXBContext} such as
440 * <ol>
441 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
442 * <li>an ambiguity among global elements contained in the contextPath</li>
443 * <li>failure to locate a value for the context factory provider property</li>
444 * <li>mixing schema derived packages from different providers on the same contextPath</li>
445 * <li>packages are not open to {@code java.xml.bind} module</li>
446 * </ol>
447 */
448 public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) throws JAXBException {
449
450 return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap());
451 }
452
453 /**
454 * Create a new instance of a {@code JAXBContext} class.
455 *
456 * <p>
457 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)},
458 * but this version allows you to pass in provider-specific properties to configure
459 * the instantiation of {@link JAXBContext}.
460 *
461 * <p>
462 * The interpretation of properties is up to implementations. Implementations must
463 * throw {@code JAXBException} if it finds properties that it doesn't understand.
464 *
465 * @param contextPath
466 * List of java package names that contain schema
467 * derived class and/or java to schema (JAXB-annotated)
468 * mapped classes.
469 * Packages in {@code contextPath} that are in named modules must be
470 * {@linkplain java.lang.Module#isOpen open} to at least the {@code java.xml.bind} module.
471 * @param classLoader
472 * This class loader will be used to locate the implementation classes.
473 * @param properties
474 * provider-specific properties. Can be null, which means the same thing as passing
475 * in an empty map.
476 *
477 * @return a new instance of a {@code JAXBContext}
478 * @throws JAXBException if an error was encountered while creating the
479 * {@code JAXBContext} such as
480 * <ol>
481 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
482 * <li>an ambiguity among global elements contained in the contextPath</li>
483 * <li>failure to locate a value for the context factory provider property</li>
484 * <li>mixing schema derived packages from different providers on the same contextPath</li>
485 * <li>packages are not open to {@code java.xml.bind} module</li>
486 * </ol>
487 * @since 1.6, JAXB 2.0
488 */
489 public static JAXBContext newInstance( String contextPath,
490 ClassLoader classLoader,
491 Map<String,?> properties ) throws JAXBException {
492
493 return ContextFinder.find(
494 /* The default property name according to the JAXB spec */
495 JAXB_CONTEXT_FACTORY,
496
497 /* the context path supplied by the client app */
498 contextPath,
499
500 /* class loader to be used */
501 classLoader,
502 properties );
503 }
504
505 // TODO: resurrect this once we introduce external annotations
506 // /**
507 // * Create a new instance of a {@code JAXBContext} class.
508 // *
509 // * <p>
510 // * The client application must supply a list of classes that the new
511 // * context object needs to recognize.
512 // *
513 // * Not only the new context will recognize all the classes specified,
514 // * but it will also recognize any classes that are directly/indirectly
515 // * referenced statically from the specified classes.
516 // *
517 // * For example, in the following Java code, if you do
518 // * {@code newInstance(Foo.class)}, the newly created {@link JAXBContext}
519 // * will recognize both {@code Foo} and {@code Bar}, but not {@code Zot}:
520 // * <pre>
521 // * class Foo {
522 // * Bar b;
523 // * }
524 // * class Bar { int x; }
525 // * class Zot extends Bar { int y; }
526 // * </pre>
527 // *
528 // * Therefore, a typical client application only needs to specify the
529 // * top-level classes, but it needs to be careful.
530 // *
531 // * TODO: if we are to define other mechanisms, refer to them.
532 // *
533 // * @param externalBindings
534 // * list of external binding files. Can be null or empty if none is used.
535 // * when specified, those files determine how the classes are bound.
536 // *
537 // * @param classesToBeBound
538 // * list of java classes to be recognized by the new {@link JAXBContext}.
539 // * Can be empty, in which case a {@link JAXBContext} that only knows about
540 // * spec-defined classes will be returned.
541 // *
542 // * @return
543 // * A new instance of a {@code JAXBContext}.
544 // *
545 // * @throws JAXBException
546 // * if an error was encountered while creating the
547 // * {@code JAXBContext}, such as (but not limited to):
548 // * <ol>
549 // * <li>No JAXB implementation was discovered
550 // * <li>Classes use JAXB annotations incorrectly
551 // * <li>Classes have colliding annotations (i.e., two classes with the same type name)
552 // * <li>Specified external bindings are incorrect
553 // * <li>The JAXB implementation was unable to locate
554 // * provider-specific out-of-band information (such as additional
555 // * files generated at the development time.)
556 // * </ol>
557 // *
558 // * @throws IllegalArgumentException
559 // * if the parameter contains {@code null} (i.e., {@code newInstance(null);})
560 // *
561 // * @since JAXB 2.0
562 // */
563 // public static JAXBContext newInstance( Source[] externalBindings, Class... classesToBeBound )
564 // throws JAXBException {
565 //
566 // // empty class list is not an error, because the context will still include
567 // // spec-specified classes like String and Integer.
568 // // if(classesToBeBound.length==0)
569 // // throw new IllegalArgumentException();
570 //
571 // // but it is an error to have nulls in it.
572 // for( int i=classesToBeBound.length-1; i>=0; i-- )
573 // if(classesToBeBound[i]==null)
574 // throw new IllegalArgumentException();
575 //
576 // return ContextFinder.find(externalBindings,classesToBeBound);
577 // }
578
579 /**
580 * Create a new instance of a {@code JAXBContext} class.
581 *
582 * <p>
583 * The client application must supply a list of classes that the new
584 * context object needs to recognize.
585 *
586 * Not only the new context will recognize all the classes specified,
587 * but it will also recognize any classes that are directly/indirectly
588 * referenced statically from the specified classes. Subclasses of
589 * referenced classes nor {@code @XmlTransient} referenced classes
590 * are not registered with JAXBContext.
591 *
592 * For example, in the following Java code, if you do
593 * {@code newInstance(Foo.class)}, the newly created {@link JAXBContext}
594 * will recognize both {@code Foo} and {@code Bar}, but not {@code Zot} or {@code FooBar}:
595 * <pre>
596 * class Foo {
597 * @XmlTransient FooBar c;
598 * Bar b;
599 * }
600 * class Bar { int x; }
601 * class Zot extends Bar { int y; }
602 * class FooBar { }
603 * </pre>
604 *
605 * Therefore, a typical client application only needs to specify the
606 * top-level classes, but it needs to be careful.
607 *
608 * <p>
609 * Note that for each java package registered with JAXBContext,
610 * when the optional package annotations exist, they must be processed.
611 * (see JLS, Section 7.4.1 "Named Packages").
612 *
613 * <p>
614 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
615 *
616 * @param classesToBeBound
617 * List of java classes to be recognized by the new {@link JAXBContext}.
618 * Classes in {@code classesToBeBound} that are in named modules must be in a package
619 * that is {@linkplain java.lang.Module#isOpen open} to at least the {@code java.xml.bind} module.
620 * Can be empty, in which case a {@link JAXBContext} that only knows about
621 * spec-defined classes will be returned.
622 *
623 * @return
624 * A new instance of a {@code JAXBContext}.
625 *
626 * @throws JAXBException
627 * if an error was encountered while creating the
628 * {@code JAXBContext}, such as (but not limited to):
629 * <ol>
630 * <li>No JAXB implementation was discovered
631 * <li>Classes use JAXB annotations incorrectly
632 * <li>Classes have colliding annotations (i.e., two classes with the same type name)
633 * <li>The JAXB implementation was unable to locate
634 * provider-specific out-of-band information (such as additional
635 * files generated at the development time.)
636 * <li>{@code classesToBeBound} are not open to {@code java.xml.bind} module
637 * </ol>
638 *
639 * @throws IllegalArgumentException
640 * if the parameter contains {@code null} (i.e., {@code newInstance(null);})
641 *
642 * @since 1.6, JAXB 2.0
643 */
644 public static JAXBContext newInstance( Class<?> ... classesToBeBound )
645 throws JAXBException {
646
647 return newInstance(classesToBeBound,Collections.<String,Object>emptyMap());
648 }
649
650 /**
651 * Create a new instance of a {@code JAXBContext} class.
652 *
653 * <p>
654 * An overloading of {@link JAXBContext#newInstance(Class...)}
655 * to configure 'properties' for this instantiation of {@link JAXBContext}.
656 *
657 * <p>
658 * The interpretation of properties is up to implementations. Implementations must
659 * throw {@code JAXBException} if it finds properties that it doesn't understand.
660 *
661 * @param classesToBeBound
662 * List of java classes to be recognized by the new {@link JAXBContext}.
663 * Classes in {@code classesToBeBound} that are in named modules must be in a package
664 * that is {@linkplain java.lang.Module#isOpen open} to at least the {@code java.xml.bind} module.
665 * Can be empty, in which case a {@link JAXBContext} that only knows about
666 * spec-defined classes will be returned.
667 * @param properties
668 * provider-specific properties. Can be null, which means the same thing as passing
669 * in an empty map.
670 *
671 * @return
672 * A new instance of a {@code JAXBContext}.
673 *
674 * @throws JAXBException
675 * if an error was encountered while creating the
676 * {@code JAXBContext}, such as (but not limited to):
677 * <ol>
678 * <li>No JAXB implementation was discovered
679 * <li>Classes use JAXB annotations incorrectly
680 * <li>Classes have colliding annotations (i.e., two classes with the same type name)
681 * <li>The JAXB implementation was unable to locate
682 * provider-specific out-of-band information (such as additional
683 * files generated at the development time.)
684 * <li>{@code classesToBeBound} are not open to {@code java.xml.bind} module
685 * </ol>
686 *
687 * @throws IllegalArgumentException
688 * if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);})
689 *
690 * @since 1.6, JAXB 2.0
691 */
692 public static JAXBContext newInstance( Class<?>[] classesToBeBound, Map<String,?> properties )
693 throws JAXBException {
694
695 if (classesToBeBound == null) {
696 throw new IllegalArgumentException();
697 }
698
699 // but it is an error to have nulls in it.
700 for (int i = classesToBeBound.length - 1; i >= 0; i--) {
701 if (classesToBeBound[i] == null) {
702 throw new IllegalArgumentException();
703 }
704 }
705
706 return ContextFinder.find(classesToBeBound,properties);
707 }
708
709 /**
710 * Create an {@code Unmarshaller} object that can be used to convert XML
711 * data into a java content tree.
712 *
713 * @return an {@code Unmarshaller} object
714 *
715 * @throws JAXBException if an error was encountered while creating the
716 * {@code Unmarshaller} object
717 */
718 public abstract Unmarshaller createUnmarshaller() throws JAXBException;
719
720
721 /**
722 * Create a {@code Marshaller} object that can be used to convert a
723 * java content tree into XML data.
724 *
725 * @return a {@code Marshaller} object
726 *
727 * @throws JAXBException if an error was encountered while creating the
728 * {@code Marshaller} object
729 */
730 public abstract Marshaller createMarshaller() throws JAXBException;
731
732
733 /**
734 * {@link Validator} has been made optional and deprecated in JAXB 2.0. Please
735 * refer to the javadoc for {@link Validator} for more detail.
736 * <p>
737 * Create a {@code Validator} object that can be used to validate a
738 * java content tree against its source schema.
739 *
740 * @return a {@code Validator} object
741 *
742 * @throws JAXBException if an error was encountered while creating the
743 * {@code Validator} object
744 * @deprecated since JAXB2.0
745 */
746 public abstract Validator createValidator() throws JAXBException;
747
748 /**
749 * Creates a {@code Binder} object that can be used for
750 * associative/in-place unmarshalling/marshalling.
751 *
752 * @param domType select the DOM API to use by passing in its DOM Node class.
753 *
754 * @return always a new valid {@code Binder} object.
755 *
756 * @throws UnsupportedOperationException
757 * if DOM API corresponding to {@code domType} is not supported by
758 * the implementation.
759 *
760 * @since 1.6, JAXB 2.0
761 */
762 public <T> Binder<T> createBinder(Class<T> domType) {
763 // to make JAXB 1.0 implementations work, this method must not be
764 // abstract
765 throw new UnsupportedOperationException();
766 }
767
768 /**
769 * Creates a {@code Binder} for W3C DOM.
770 *
771 * @return always a new valid {@code Binder} object.
772 *
773 * @since 1.6, JAXB 2.0
774 */
775 public Binder<Node> createBinder() {
776 return createBinder(Node.class);
777 }
778
779 /**
780 * Creates a {@code JAXBIntrospector} object that can be used to
781 * introspect JAXB objects.
782 *
783 * @return
784 * always return a non-null valid {@code JAXBIntrospector} object.
785 *
786 * @throws UnsupportedOperationException
787 * Calling this method on JAXB 1.0 implementations will throw
788 * an UnsupportedOperationException.
789 *
790 * @since 1.6, JAXB 2.0
791 */
792 public JAXBIntrospector createJAXBIntrospector() {
793 // to make JAXB 1.0 implementations work, this method must not be
794 // abstract
795 throw new UnsupportedOperationException();
796 }
797
798 /**
799 * Generates the schema documents for this context.
800 *
801 * @param outputResolver
802 * this object controls the output to which schemas
803 * will be sent.
804 *
805 * @throws IOException
806 * if {@link SchemaOutputResolver} throws an {@link IOException}.
807 *
808 * @throws UnsupportedOperationException
809 * Calling this method on JAXB 1.0 implementations will throw
810 * an UnsupportedOperationException.
811 *
812 * @since 1.6, JAXB 2.0
813 */
814 public void generateSchema(SchemaOutputResolver outputResolver) throws IOException {
815 // to make JAXB 1.0 implementations work, this method must not be
816 // abstract
817 throw new UnsupportedOperationException();
818 }
819
820 private static ClassLoader getContextClassLoader() {
821 if (System.getSecurityManager() == null) {
822 return Thread.currentThread().getContextClassLoader();
823 } else {
824 return java.security.AccessController.doPrivileged(
825 new java.security.PrivilegedAction<ClassLoader>() {
826 public ClassLoader run() {
827 return Thread.currentThread().getContextClassLoader();
828 }
829 });
830 }
831 }
832
833 }