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>
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 }
|
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>
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} such as
336 * <ol>
337 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
338 * <li>an ambiguity among global elements contained in the contextPath</li>
339 * <li>failure to locate a value for the context factory provider property</li>
340 * <li>mixing schema derived packages from different providers on the same contextPath</li>
341 * <li>packages are not open to {@code java.xml.bind} module</li>
342 * </ol>
343 */
344 public static JAXBContext newInstance( String contextPath )
345 throws JAXBException {
346
347 //return newInstance( contextPath, JAXBContext.class.getClassLoader() );
348 return newInstance( contextPath, getContextClassLoader());
349 }
350
351 /**
352 * Create a new instance of a {@code JAXBContext} class.
353 *
354 * <p>
355 * The client application must supply a context path which is a list of
356 * colon (':', \u005Cu003A) separated java package names that contain
357 * schema-derived classes and/or fully qualified JAXB-annotated classes.
358 * Schema-derived
359 * code is registered with the JAXBContext by the
360 * ObjectFactory.class generated per package.
361 * Alternatively than being listed in the context path, programmer
362 * annotated JAXB mapped classes can be listed in a
404 * {@code <jaxb:globalBindings valueClass="false">},
405 * the JAXB provider will ensure that each package on the context path
406 * has a {@code jaxb.properties} file which contains a value for the
407 * {@code javax.xml.bind.context.factory} property and that all values
408 * resolve to the same provider. This requirement does not apply to
409 * JAXB annotated classes.
410 *
411 * <p>
412 * If there are any global XML element name collisions across the various
413 * packages listed on the {@code contextPath}, a {@code JAXBException}
414 * will be thrown.
415 *
416 * <p>
417 * Mixing generated interface/impl bindings from multiple JAXB Providers
418 * in the same context path may result in a {@code JAXBException}
419 * being thrown.
420 *
421 * <p>
422 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
423 *
424 * @param contextPath
425 * List of java package names that contain schema
426 * derived class and/or java to schema (JAXB-annotated)
427 * mapped classes.
428 * Packages in {@code contextPath} that are in named modules must be
429 * {@linkplain java.lang.reflect.Module#isOpen open} to the {@code java.xml.bind} module.
430 * @param classLoader
431 * This class loader will be used to locate the implementation
432 * classes.
433 *
434 * @return a new instance of a {@code JAXBContext}
435 * @throws JAXBException if an error was encountered while creating the
436 * {@code JAXBContext} such as
437 * <ol>
438 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
439 * <li>an ambiguity among global elements contained in the contextPath</li>
440 * <li>failure to locate a value for the context factory provider property</li>
441 * <li>mixing schema derived packages from different providers on the same contextPath</li>
442 * <li>packages are not open to {@code java.xml.bind} module</li>
443 * </ol>
444 */
445 public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) throws JAXBException {
446
447 return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap());
448 }
449
450 /**
451 * Create a new instance of a {@code JAXBContext} class.
452 *
453 * <p>
454 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)},
455 * but this version allows you to pass in provider-specific properties to configure
456 * the instantiation of {@link JAXBContext}.
457 *
458 * <p>
459 * The interpretation of properties is up to implementations. Implementations must
460 * throw {@code JAXBException} if it finds properties that it doesn't understand.
461 *
462 * @param contextPath
463 * List of java package names that contain schema
464 * derived class and/or java to schema (JAXB-annotated)
465 * mapped classes.
466 * Packages in {@code contextPath} that are in named modules must be
467 * {@linkplain java.lang.reflect.Module#isOpen open} to the {@code java.xml.bind} module.
468 * @param classLoader
469 * This class loader will be used to locate the implementation classes.
470 * @param properties
471 * provider-specific properties. Can be null, which means the same thing as passing
472 * in an empty map.
473 *
474 * @return a new instance of a {@code JAXBContext}
475 * @throws JAXBException if an error was encountered while creating the
476 * {@code JAXBContext} such as
477 * <ol>
478 * <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>
479 * <li>an ambiguity among global elements contained in the contextPath</li>
480 * <li>failure to locate a value for the context factory provider property</li>
481 * <li>mixing schema derived packages from different providers on the same contextPath</li>
482 * <li>packages are not open to {@code java.xml.bind} module</li>
483 * </ol>
484 * @since 1.6, JAXB 2.0
485 */
486 public static JAXBContext newInstance( String contextPath,
487 ClassLoader classLoader,
488 Map<String,?> properties ) throws JAXBException {
489
490 return ContextFinder.find(
491 /* The default property name according to the JAXB spec */
492 JAXB_CONTEXT_FACTORY,
493
494 /* the context path supplied by the client app */
495 contextPath,
496
497 /* class loader to be used */
498 classLoader,
499 properties );
500 }
501
502 // TODO: resurrect this once we introduce external annotations
594 * @XmlTransient FooBar c;
595 * Bar b;
596 * }
597 * class Bar { int x; }
598 * class Zot extends Bar { int y; }
599 * class FooBar { }
600 * </pre>
601 *
602 * Therefore, a typical client application only needs to specify the
603 * top-level classes, but it needs to be careful.
604 *
605 * <p>
606 * Note that for each java package registered with JAXBContext,
607 * when the optional package annotations exist, they must be processed.
608 * (see JLS, Section 7.4.1 "Named Packages").
609 *
610 * <p>
611 * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.
612 *
613 * @param classesToBeBound
614 * List of java classes to be recognized by the new {@link JAXBContext}.
615 * Classes in {@code classesToBeBound} that are in named modules must be in a package
616 * that is {@linkplain java.lang.reflect.Module#isOpen open} to the {@code java.xml.bind} module.
617 * Can be empty, in which case a {@link JAXBContext} that only knows about
618 * spec-defined classes will be returned.
619 *
620 * @return
621 * A new instance of a {@code JAXBContext}.
622 *
623 * @throws JAXBException
624 * if an error was encountered while creating the
625 * {@code JAXBContext}, such as (but not limited to):
626 * <ol>
627 * <li>No JAXB implementation was discovered
628 * <li>Classes use JAXB annotations incorrectly
629 * <li>Classes have colliding annotations (i.e., two classes with the same type name)
630 * <li>The JAXB implementation was unable to locate
631 * provider-specific out-of-band information (such as additional
632 * files generated at the development time.)
633 * <li>{@code classesToBeBound} are not open to {@code java.xml.bind} module
634 * </ol>
635 *
636 * @throws IllegalArgumentException
637 * if the parameter contains {@code null} (i.e., {@code newInstance(null);})
638 *
639 * @since 1.6, JAXB 2.0
640 */
641 public static JAXBContext newInstance( Class<?> ... classesToBeBound )
642 throws JAXBException {
643
644 return newInstance(classesToBeBound,Collections.<String,Object>emptyMap());
645 }
646
647 /**
648 * Create a new instance of a {@code JAXBContext} class.
649 *
650 * <p>
651 * An overloading of {@link JAXBContext#newInstance(Class...)}
652 * to configure 'properties' for this instantiation of {@link JAXBContext}.
653 *
654 * <p>
655 * The interpretation of properties is up to implementations. Implementations must
656 * throw {@code JAXBException} if it finds properties that it doesn't understand.
657 *
658 * @param classesToBeBound
659 * List of java classes to be recognized by the new {@link JAXBContext}.
660 * Classes in {@code classesToBeBound} that are in named modules must be in a package
661 * that is {@linkplain java.lang.reflect.Module#isOpen open} to the {@code java.xml.bind} module.
662 * Can be empty, in which case a {@link JAXBContext} that only knows about
663 * spec-defined classes will be returned.
664 * @param properties
665 * provider-specific properties. Can be null, which means the same thing as passing
666 * in an empty map.
667 *
668 * @return
669 * A new instance of a {@code JAXBContext}.
670 *
671 * @throws JAXBException
672 * if an error was encountered while creating the
673 * {@code JAXBContext}, such as (but not limited to):
674 * <ol>
675 * <li>No JAXB implementation was discovered
676 * <li>Classes use JAXB annotations incorrectly
677 * <li>Classes have colliding annotations (i.e., two classes with the same type name)
678 * <li>The JAXB implementation was unable to locate
679 * provider-specific out-of-band information (such as additional
680 * files generated at the development time.)
681 * <li>{@code classesToBeBound} are not open to {@code java.xml.bind} module
682 * </ol>
683 *
684 * @throws IllegalArgumentException
685 * if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);})
686 *
687 * @since 1.6, JAXB 2.0
688 */
689 public static JAXBContext newInstance( Class<?>[] classesToBeBound, Map<String,?> properties )
690 throws JAXBException {
691
692 if (classesToBeBound == null) {
693 throw new IllegalArgumentException();
694 }
695
696 // but it is an error to have nulls in it.
697 for (int i = classesToBeBound.length - 1; i >= 0; i--) {
698 if (classesToBeBound[i] == null) {
699 throw new IllegalArgumentException();
700 }
701 }
|