1 /*
2 * Copyright (c) 2003, 2016, 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.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 * 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>
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 * <li>
231 * If the system property {@link #JAXB_CONTEXT_FACTORY} exists, then its value is assumed to be the provider
232 * factory class. If no such property exists, properties {@code "javax.xml.bind.context.factory"} and
233 * {@code "javax.xml.bind.JAXBContext"} are checked too (in this order), for backwards compatibility reasons. This phase
234 * of the look up enables per-JVM override of the JAXB implementation.
235 *
236 * <li>
237 * Provider of {@link javax.xml.bind.JAXBContextFactory} is loaded using the service-provider loading
238 * facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
239 * to locate and load an implementation of the service using the {@linkplain
240 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: the service-provider loading facility
241 * will use the {@linkplain java.lang.Thread#getContextClassLoader() current thread's context class loader}
242 * to attempt to load the context factory. If the context class loader is null, the
243 * {@linkplain ClassLoader#getSystemClassLoader() system class loader} will be used.
244 * <br>
245 * In case of {@link java.util.ServiceConfigurationError service
246 * configuration error} a {@link javax.xml.bind.JAXBException} will be thrown.
247 *
248 * <li>
249 * Look for resource {@code /META-INF/services/javax.xml.bind.JAXBContext} using provided class loader.
315
316 /**
317 * The name of the property that contains the name of the class capable
318 * of creating new {@code JAXBContext} objects.
319 */
320 public static final String JAXB_CONTEXT_FACTORY = "javax.xml.bind.JAXBContextFactory";
321
322 protected JAXBContext() {
323 }
324
325
326 /**
327 * Create a new instance of a {@code JAXBContext} class.
328 *
329 * <p>
330 * This is a convenience method to invoke the
331 * {@link #newInstance(String,ClassLoader)} method with
332 * the context class loader of the current thread.
333 *
334 * @throws JAXBException if an error was encountered while creating the
335 * {@code JAXBContext}. See {@link JAXBContext#newInstance(String, ClassLoader, Map)} for details.
336 */
337 public static JAXBContext newInstance( String contextPath )
338 throws JAXBException {
339
340 //return newInstance( contextPath, JAXBContext.class.getClassLoader() );
341 return newInstance( contextPath, getContextClassLoader());
342 }
343
344 /**
345 * Create a new instance of a {@code JAXBContext} class.
346 *
347 * <p>
348 * The client application must supply a context path which is a list of
349 * colon (':', \u005Cu003A) separated java package names that contain
350 * schema-derived classes and/or fully qualified JAXB-annotated classes.
351 * Schema-derived
352 * code is registered with the JAXBContext by the
353 * ObjectFactory.class generated per package.
354 * Alternatively than being listed in the context path, programmer
355 * annotated JAXB mapped classes can be listed in a
397 * {@code <jaxb:globalBindings valueClass="false">},
398 * the JAXB provider will ensure that each package on the context path
399 * has a {@code jaxb.properties} file which contains a value for the
400 * {@code javax.xml.bind.context.factory} property and that all values
401 * resolve to the same provider. This requirement does not apply to
402 * JAXB annotated classes.
403 *
404 * <p>
405 * If there are any global XML element name collisions across the various
406 * packages listed on the {@code contextPath}, a {@code JAXBException}
407 * will be thrown.
408 *
409 * <p>
410 * Mixing generated interface/impl bindings from multiple JAXB Providers
411 * in the same context path may result in a {@code JAXBException}
412 * being thrown.
413 *
414 * <p>
415 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
416 *
417 * @param contextPath list of java package names that contain schema
418 * derived class and/or java to schema (JAXB-annotated)
419 * mapped classes
420 * @param classLoader
421 * This class loader will be used to locate the implementation
422 * classes.
423 *
424 * @return a new instance of a {@code JAXBContext}
425 * @throws JAXBException if an error was encountered while creating the
426 * {@code JAXBContext}. See {@link JAXBContext#newInstance(String, ClassLoader, Map)} for details.
427 */
428 public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) throws JAXBException {
429
430 return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap());
431 }
432
433 /**
434 * Create a new instance of a {@code JAXBContext} class.
435 *
436 * <p>
437 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)},
438 * but this version allows you to pass in provider-specific properties to configure
439 * the instantiation of {@link JAXBContext}.
440 *
441 * <p>
442 * The interpretation of properties is up to implementations. Implementations must
443 * throw {@code JAXBException} if it finds properties that it doesn't understand.
444 *
445 * @param contextPath list of java package names that contain schema derived classes
446 * @param classLoader
447 * This class loader will be used to locate the implementation classes.
448 * @param properties
449 * provider-specific properties. Can be null, which means the same thing as passing
450 * in an empty map.
451 *
452 * @return a new instance of a {@code JAXBContext}
453 * @throws JAXBException if an error was encountered while creating the
454 * {@code JAXBContext} such as
455 * <ol>
456 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
457 * <li>an ambiguity among global elements contained in the contextPath</li>
458 * <li>failure to locate a value for the context factory provider property</li>
459 * <li>mixing schema derived packages from different providers on the same contextPath</li>
460 * </ol>
461 * @since 1.6, JAXB 2.0
462 */
463 public static JAXBContext newInstance( String contextPath,
464 ClassLoader classLoader,
465 Map<String,?> properties ) throws JAXBException {
466
467 return ContextFinder.find(
468 /* The default property name according to the JAXB spec */
469 JAXB_CONTEXT_FACTORY,
470
471 /* the context path supplied by the client app */
472 contextPath,
473
474 /* class loader to be used */
475 classLoader,
476 properties );
477 }
478
479 // TODO: resurrect this once we introduce external annotations
571 * @XmlTransient FooBar c;
572 * Bar b;
573 * }
574 * class Bar { int x; }
575 * class Zot extends Bar { int y; }
576 * class FooBar { }
577 * </pre>
578 *
579 * Therefore, a typical client application only needs to specify the
580 * top-level classes, but it needs to be careful.
581 *
582 * <p>
583 * Note that for each java package registered with JAXBContext,
584 * when the optional package annotations exist, they must be processed.
585 * (see JLS, Section 7.4.1 "Named Packages").
586 *
587 * <p>
588 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
589 *
590 * @param classesToBeBound
591 * list of java classes to be recognized by the new {@link JAXBContext}.
592 * Can be empty, in which case a {@link JAXBContext} that only knows about
593 * spec-defined classes will be returned.
594 *
595 * @return
596 * A new instance of a {@code JAXBContext}.
597 *
598 * @throws JAXBException if an error was encountered while creating the
599 * {@code JAXBContext}. See {@link JAXBContext#newInstance(Class[], Map)} for details.
600 *
601 * @throws IllegalArgumentException
602 * if the parameter contains {@code null} (i.e., {@code newInstance(null);})
603 *
604 * @since 1.6, JAXB 2.0
605 */
606 public static JAXBContext newInstance( Class<?> ... classesToBeBound )
607 throws JAXBException {
608
609 return newInstance(classesToBeBound,Collections.<String,Object>emptyMap());
610 }
611
612 /**
613 * Create a new instance of a {@code JAXBContext} class.
614 *
615 * <p>
616 * An overloading of {@link JAXBContext#newInstance(Class...)}
617 * to configure 'properties' for this instantiation of {@link JAXBContext}.
618 *
619 * <p>
620 * The interpretation of properties is up to implementations. Implementations must
621 * throw {@code JAXBException} if it finds properties that it doesn't understand.
622 *
623 * @param classesToBeBound
624 * list of java classes to be recognized by the new {@link JAXBContext}.
625 * Can be empty, in which case a {@link JAXBContext} that only knows about
626 * spec-defined classes will be returned.
627 * @param properties
628 * provider-specific properties. Can be null, which means the same thing as passing
629 * in an empty map.
630 *
631 * @return
632 * A new instance of a {@code JAXBContext}.
633 *
634 * @throws JAXBException
635 * if an error was encountered while creating the
636 * {@code JAXBContext}, such as (but not limited to):
637 * <ol>
638 * <li>No JAXB implementation was discovered
639 * <li>Classes use JAXB annotations incorrectly
640 * <li>Classes have colliding annotations (i.e., two classes with the same type name)
641 * <li>The JAXB implementation was unable to locate
642 * provider-specific out-of-band information (such as additional
643 * files generated at the development time.)
644 * </ol>
645 *
646 * @throws IllegalArgumentException
647 * if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);})
648 *
649 * @since 1.6, JAXB 2.0
650 */
651 public static JAXBContext newInstance( Class<?>[] classesToBeBound, Map<String,?> properties )
652 throws JAXBException {
653
654 if (classesToBeBound == null) {
655 throw new IllegalArgumentException();
656 }
657
658 // but it is an error to have nulls in it.
659 for (int i = classesToBeBound.length - 1; i >= 0; i--) {
660 if (classesToBeBound[i] == null) {
661 throw new IllegalArgumentException();
662 }
663 }
685 *
686 * @throws JAXBException if an error was encountered while creating the
687 * {@code Marshaller} object
688 */
689 public abstract Marshaller createMarshaller() throws JAXBException;
690
691
692 /**
693 * {@link Validator} has been made optional and deprecated in JAXB 2.0. Please
694 * refer to the javadoc for {@link Validator} for more detail.
695 * <p>
696 * Create a {@code Validator} object that can be used to validate a
697 * java content tree against its source schema.
698 *
699 * @return a {@code Validator} object
700 *
701 * @throws JAXBException if an error was encountered while creating the
702 * {@code Validator} object
703 * @deprecated since JAXB2.0
704 */
705 public abstract Validator createValidator() throws JAXBException;
706
707 /**
708 * Creates a {@code Binder} object that can be used for
709 * associative/in-place unmarshalling/marshalling.
710 *
711 * @param domType select the DOM API to use by passing in its DOM Node class.
712 *
713 * @return always a new valid {@code Binder} object.
714 *
715 * @throws UnsupportedOperationException
716 * if DOM API corresponding to {@code domType} is not supported by
717 * the implementation.
718 *
719 * @since 1.6, JAXB 2.0
720 */
721 public <T> Binder<T> createBinder(Class<T> domType) {
722 // to make JAXB 1.0 implementations work, this method must not be
723 // abstract
724 throw new UnsupportedOperationException();
|
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>
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.
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
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
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 }
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 @Deprecated
747 public abstract Validator createValidator() throws JAXBException;
748
749 /**
750 * Creates a {@code Binder} object that can be used for
751 * associative/in-place unmarshalling/marshalling.
752 *
753 * @param domType select the DOM API to use by passing in its DOM Node class.
754 *
755 * @return always a new valid {@code Binder} object.
756 *
757 * @throws UnsupportedOperationException
758 * if DOM API corresponding to {@code domType} is not supported by
759 * the implementation.
760 *
761 * @since 1.6, JAXB 2.0
762 */
763 public <T> Binder<T> createBinder(Class<T> domType) {
764 // to make JAXB 1.0 implementations work, this method must not be
765 // abstract
766 throw new UnsupportedOperationException();
|