1 /*

     2  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    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  * <p>

    38  * The <tt>JAXBContext</tt> class provides the client's entry point to the

    39  * JAXB API. It provides an abstraction for managing the XML/Java binding

    40  * information necessary to implement the JAXB binding framework operations:

    41  * unmarshal, marshal and validate.

    42  *

    43  * <p>A client application normally obtains new instances of this class using

    44  * one of these two styles for newInstance methods, although there are other

    45  * specialized forms of the method available:

    46  *

    47  * <ul>

    48  *   <li>{@link #newInstance(String,ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br/>

    49  *   The JAXBContext instance is initialized from a list of colon

    50  *   separated Java package names. Each java package contains

    51  *   JAXB mapped classes, schema-derived classes and/or user annotated

    52  *   classes. Additionally, the java package may contain JAXB package annotations

    53  *   that must be processed. (see JLS, Section 7.4.1 "Named Packages").

    54  *   </li>

    55  *   <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br/>

    56  *    The JAXBContext instance is initialized with class(es)

    57  *    passed as parameter(s) and classes that are statically reachable from

    58  *    these class(es). See {@link #newInstance(Class...)} for details.

    59  *   </li>

    60  * </ul>

    61  *

    62  * <p>

    63  * <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation

    64  * class containing the following method signatures:</i>

    65  *

    66  * <pre>

    67  * public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException

    68  * public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException

    69  * </pre>

    70  *

    71  * <p><i>

    72  * The following JAXB 1.0 requirement is only required for schema to

    73  * java interface/implementation binding. It does not apply to JAXB annotated

    74  * classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in

    75  * each package containing schema derived classes.  The property file must

    76  * contain a property named <tt>javax.xml.bind.context.factory</tt> whose

    77  * value is the name of the class that implements the <tt>createContext</tt>

    78  * APIs.</i>

    79  *

    80  * <p><i>

    81  * The class supplied by the provider does not have to be assignable to

    82  * <tt>javax.xml.bind.JAXBContext</tt>, it simply has to provide a class that

    83  * implements the <tt>createContext</tt> APIs.</i>

    84  *

    85  * <p><i>

    86  * In addition, the provider must call the

    87  * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)

    88  * DatatypeConverter.setDatatypeConverter} api prior to any client

    89  * invocations of the marshal and unmarshal methods.  This is necessary to

    90  * configure the datatype converter that will be used during these operations.</i>

    91  *

    92  * <a name="Unmarshalling"></a>

    93  * <h3>Unmarshalling</h3>

    94  * <p>

    95  * The {@link Unmarshaller} class provides the client application the ability

    96  * to convert XML data into a tree of Java content objects.

    97  * The unmarshal method allows for

    98  * any global XML element declared in the schema to be unmarshalled as

    99  * the root of an instance document.

   100  * Additionally, the unmarshal method allows for an unrecognized root element that

   101  * has  an xsi:type attribute's value that references a type definition declared in

   102  * the schema  to be unmarshalled as the root of an instance document.

   103  * The <tt>JAXBContext</tt> object

   104  * allows the merging of global elements and type definitions across a set of schemas (listed

   105  * in the <tt>contextPath</tt>). Since each schema in the schema set can belong

   106  * to distinct namespaces, the unification of schemas to an unmarshalling

   107  * context should be namespace independent.  This means that a client

   108  * application is able to unmarshal XML documents that are instances of

   109  * any of the schemas listed in the <tt>contextPath</tt>.  For example:

   110  *

   111  * <pre>

   112  *        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );

   113  *        Unmarshaller u = jc.createUnmarshaller();

   114  *        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok

   115  *        BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok

   116  *        BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath

   117  * </pre>

   118  *

   119  * <p>

   120  * The client application may also generate Java content trees explicitly rather

   121  * than unmarshalling existing XML data.  For all JAXB-annotated value classes,

   122  * an application can create content using constructors.

   123  * For schema-derived interface/implementation classes and for the

   124  * creation of elements that are not bound to a JAXB-annotated

   125  * class, an application needs to have access and knowledge about each of

   126  * the schema derived <tt> ObjectFactory</tt> classes that exist in each of

   127  * java packages contained in the <tt>contextPath</tt>.  For each schema

   128  * derived java class, there is a static factory method that produces objects

   129  * of that type.  For example,

   130  * assume that after compiling a schema, you have a package <tt>com.acme.foo</tt>

   131  * that contains a schema derived interface named <tt>PurchaseOrder</tt>.  In

   132  * order to create objects of that type, the client application would use the

   133  * factory method like this:

   134  *

   135  * <pre>

   136  *       com.acme.foo.PurchaseOrder po =

   137  *           com.acme.foo.ObjectFactory.createPurchaseOrder();

   138  * </pre>

   139  *

   140  * <p>

   141  * Once the client application has an instance of the the schema derived object,

   142  * it can use the mutator methods to set content on it.

   143  *

   144  * <p>

   145  * For more information on the generated <tt>ObjectFactory</tt> classes, see

   146  * Section 4.2 <i>Java Package</i> of the specification.

   147  *

   148  * <p>

   149  * <i><B>SPEC REQUIREMENT:</B> the provider must generate a class in each

   150  * package that contains all of the necessary object factory methods for that

   151  * package named ObjectFactory as well as the static

   152  * <tt>newInstance( javaContentInterface )</tt> method</i>

   153  *

   154  * <h3>Marshalling</h3>

   155  * <p>

   156  * The {@link Marshaller} class provides the client application the ability

   157  * to convert a Java content tree back into XML data.  There is no difference

   158  * between marshalling a content tree that is created manually using the factory

   159  * methods and marshalling a content tree that is the result an <tt>unmarshal

   160  * </tt> operation.  Clients can marshal a java content tree back to XML data

   161  * to a <tt>java.io.OutputStream</tt> or a <tt>java.io.Writer</tt>.  The

   162  * marshalling process can alternatively produce SAX2 event streams to a

   163  * registered <tt>ContentHandler</tt> or produce a DOM Node object.

   164  * Client applications have control over the output encoding as well as

   165  * whether or not to marshal the XML data as a complete document or

   166  * as a fragment.

   167  *

   168  * <p>

   169  * Here is a simple example that unmarshals an XML document and then marshals

   170  * it back out:

   171  *

   172  * <pre>

   173  *        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );

   174  *

   175  *        // unmarshal from foo.xml

   176  *        Unmarshaller u = jc.createUnmarshaller();

   177  *        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );

   178  *

   179  *        // marshal to System.out

   180  *        Marshaller m = jc.createMarshaller();

   181  *        m.marshal( fooObj, System.out );

   182  * </pre>

   183  *

   184  *

   185  * <h3>Validation</h3>

   186  * <p>

   187  * Validation has been changed significantly since JAXB 1.0.  The {@link Validator}

   188  * class has been deprecated and made optional.  This means that you are advised

   189  * not to use this class and, in fact, it may not even be available depending on

   190  * your JAXB provider.  JAXB 1.0 client applications that rely on <tt>Validator</tt>

   191  * will still work properly when deployed with the JAXB 1.0 runtime system.

   192  *

   193  * In JAXB 2.0, the {@link Unmarshaller} has included convenince methods that expose

   194  * the JAXP 1.3 {@link javax.xml.validation} framework.  Please refer to the

   195  * {@link Unmarshaller#setSchema(javax.xml.validation.Schema)} API for more

   196  * information.

   197  *

   198  *

   199  * <h3>JAXB Runtime Binding Framework Compatibility</h3>

   200  * <p>

   201  * The following JAXB 1.0 restriction only applies to binding schema to

   202  * interfaces/implementation classes.

   203  * Since this binding does not require a common runtime system, a JAXB

   204  * client application must not attempt to mix runtime objects (<tt>JAXBContext,

   205  * Marshaller</tt>, etc. ) from different providers.  This does not

   206  * mean that the client application isn't portable, it simply means that a

   207  * client has to use a runtime system provided by the same provider that was

   208  * used to compile the schema.

   209  *

   210  *

   211  * <h3>Discovery of JAXB implementation</h3>

   212  * <p>

   213  * When one of the <tt>newInstance</tt> methods is called, a JAXB implementation is discovered

   214  * by the following steps.

   215  *

   216  * <ol>

   217  * <li>

   218  * For each package/class explicitly passed in to the {@link #newInstance} method, in the order they are specified,

   219  * <tt>jaxb.properties</tt> file is looked up in its package, by using the associated classloader &mdash;

   220  * this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package

   221  * the specified {@link ClassLoader}.

   222  *

   223  * <p>

   224  * If such a file is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and

   225  * the value of the {@link #JAXB_CONTEXT_FACTORY} key will be assumed to be the provider factory class.

   226  * This class is then loaded by the associated classloader discussed above.

   227  *

   228  * <p>

   229  * This phase of the look up allows some packages to force the use of a certain JAXB implementation.

   230  * (For example, perhaps the schema compiler has generated some vendor extension in the code.)

   231  *

   232  * <li>

   233  * If the system property {@link #JAXB_CONTEXT_FACTORY} exists, then its value is assumed to be the provider

   234  * factory class. This phase of the look up enables per-JVM override of the JAXB implementation.

   235  *

   236  * <li>

   237  * Look for <tt>/META-INF/services/javax.xml.bind.JAXBContext</tt> file in the associated classloader.

   238  * This file follows the standard service descriptor convention, and if such a file exists, its content

   239  * is assumed to be the provider factory class. This phase of the look up is for automatic discovery.

   240  * It allows users to just put a JAXB implementation in a classpath and use it without any furhter configuration.

   241  *

   242  * <li>

   243  * Finally, if all the steps above fail, then the rest of the look up is unspecified. That said,

   244  * the recommended behavior is to simply look for some hard-coded platform default JAXB implementation.

   245  * This phase of the look up is so that JavaSE can have its own JAXB implementation as the last resort.

   246  * </ol>

   247  *

   248  * <p>

   249  * Once the provider factory class is discovered, its

   250  * <tt>public static JAXBContext createContext(String,ClassLoader,Map)</tt> method

   251  * (see {@link #newInstance(String, ClassLoader, Map)} for the parameter semantics.)

   252  * or <tt>public static JAXBContext createContet(Class[],Map)</tt> method

   253  * (see {@link #newInstance(Class[], Map)} for the parameter semantics) are invoked

   254  * to create a {@link JAXBContext}.

   255  *

   256  * @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>

   257  * @see Marshaller

   258  * @see Unmarshaller

   259  * @see S 7.4.1 "Named Packages" in Java Language Specification</a>

   260  * @since 1.6, JAXB 1.0

   261  */

   262 public abstract class JAXBContext {

   263 

   264     /**

   265      * The name of the property that contains the name of the class capable

   266      * of creating new <tt>JAXBContext</tt> objects.

   267      */

   268     public static final String JAXB_CONTEXT_FACTORY =

   269         "javax.xml.bind.context.factory";

   270 

   271 

   272     protected JAXBContext() {

   273     }

   274 

   275 

   276     /**

   277      * <p>

   278      * Obtain a new instance of a <tt>JAXBContext</tt> class.

   279      *

   280      * <p>

   281      * This is a convenience method to invoke the

   282      * {@link #newInstance(String,ClassLoader)} method with

   283      * the context class loader of the current thread.

   284      *

   285      * @throws JAXBException if an error was encountered while creating the

   286      *                       <tt>JAXBContext</tt> such as

   287      * <ol>

   288      *   <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>

   289      *   <li>an ambiguity among global elements contained in the contextPath</li>

   290      *   <li>failure to locate a value for the context factory provider property</li>

   291      *   <li>mixing schema derived packages from different providers on the same contextPath</li>

   292      * </ol>

   293      */

   294     public static JAXBContext newInstance( String contextPath )

   295         throws JAXBException {

   296 

   297         //return newInstance( contextPath, JAXBContext.class.getClassLoader() );

   298         return newInstance( contextPath, getContextClassLoader());

   299     }

   300 

   301     /**

   302      * <p>

   303      * Obtain a new instance of a <tt>JAXBContext</tt> class.

   304      *

   305      * <p>

   306      * The client application must supply a context path which is a list of

   307      * colon (':', \u005Cu003A) separated java package names that contain

   308      * schema-derived classes and/or fully qualified JAXB-annotated classes.

   309      * Schema-derived

   310      * code is registered with the JAXBContext by the

   311      * ObjectFactory.class generated per package.

   312      * Alternatively than being listed in the context path, programmer

   313      * annotated JAXB mapped classes can be listed in a

   314      * <tt>jaxb.index</tt> resource file, format described below.

   315      * Note that a java package can contain both schema-derived classes and

   316      * user annotated JAXB classes. Additionally, the java package may

   317      * contain JAXB package annotations  that must be processed. (see JLS,

   318      * Section 7.4.1 "Named Packages").

   319      * </p>

   320      *

   321      * <p>

   322      * Every package listed on the contextPath must meet <b>one or both</b> of the

   323      * following conditions otherwise a <tt>JAXBException</tt> will be thrown:

   324      * </p>

   325      * <ol>

   326      *   <li>it must contain ObjectFactory.class</li>

   327      *   <li>it must contain jaxb.index</li>

   328      * </ol>

   329      *

   330      * <p>

   331      * <b>Format for jaxb.index</b>

   332      * <p>

   333      * The file contains a newline-separated list of class names.

   334      * Space and tab characters, as well as blank

   335      * lines, are ignored. The comment character

   336      * is '#' (0x23); on each line all characters following the first comment

   337      * character are ignored. The file must be encoded in UTF-8. Classes that

   338      * are reachable, as defined in {@link #newInstance(Class...)}, from the

   339      * listed classes are also registered with JAXBContext.

   340      * <p>

   341      * Constraints on class name occuring in a <tt>jaxb.index</tt> file are:

   342      * <ul>

   343      *   <li>Must not end with ".class".</li>

   344      *   <li>Class names are resolved relative to package containing

   345      *       <tt>jaxb.index</tt> file. Only classes occuring directly in package

   346      *       containing <tt>jaxb.index</tt> file are allowed.</li>

   347      *   <li>Fully qualified class names are not allowed.

   348      *       A qualified class name,relative to current package,

   349      *       is only allowed to specify a nested or inner class.</li>

   350      * </ul>

   351      *

   352      * <p>

   353      * To maintain compatibility with JAXB 1.0 schema to java

   354      * interface/implementation binding, enabled by schema customization

   355      * <tt>&lt;jaxb:globalBindings valueClass="false"></tt>,

   356      * the JAXB provider will ensure that each package on the context path

   357      * has a <tt>jaxb.properties</tt> file which contains a value for the

   358      * <tt>javax.xml.bind.context.factory</tt> property and that all values

   359      * resolve to the same provider.  This requirement does not apply to

   360      * JAXB annotated classes.

   361      *

   362      * <p>

   363      * If there are any global XML element name collisions across the various

   364      * packages listed on the <tt>contextPath</tt>, a <tt>JAXBException</tt>

   365      * will be thrown.

   366      *

   367      * <p>

   368      * Mixing generated interface/impl bindings from multiple JAXB Providers

   369      * in the same context path may result in a <tt>JAXBException</tt>

   370      * being thrown.

   371      *

   372      * <p>

   373      * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.

   374      *

   375      * @param contextPath list of java package names that contain schema

   376      *                    derived class and/or java to schema (JAXB-annotated)

   377      *                    mapped classes

   378      * @param classLoader

   379      *      This class loader will be used to locate the implementation

   380      *      classes.

   381      *

   382      * @return a new instance of a <tt>JAXBContext</tt>

   383      * @throws JAXBException if an error was encountered while creating the

   384      *                       <tt>JAXBContext</tt> such as

   385      * <ol>

   386      *   <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>

   387      *   <li>an ambiguity among global elements contained in the contextPath</li>

   388      *   <li>failure to locate a value for the context factory provider property</li>

   389      *   <li>mixing schema derived packages from different providers on the same contextPath</li>

   390      * </ol>

   391      */

   392     public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) throws JAXBException {

   393 

   394         return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap());

   395     }

   396 

   397     /**

   398      * <p>

   399      * Obtain a new instance of a <tt>JAXBContext</tt> class.

   400      *

   401      * <p>

   402      * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)},

   403      * but this version allows you to pass in provider-specific properties to configure

   404      * the instantiation of {@link JAXBContext}.

   405      *

   406      * <p>

   407      * The interpretation of properties is up to implementations. Implementations should

   408      * throw <tt>JAXBException</tt> if it finds properties that it doesn't understand.

   409      *

   410      * @param contextPath list of java package names that contain schema derived classes

   411      * @param classLoader

   412      *      This class loader will be used to locate the implementation classes.

   413      * @param properties

   414      *      provider-specific properties. Can be null, which means the same thing as passing

   415      *      in an empty map.

   416      *

   417      * @return a new instance of a <tt>JAXBContext</tt>

   418      * @throws JAXBException if an error was encountered while creating the

   419      *                       <tt>JAXBContext</tt> such as

   420      * <ol>

   421      *   <li>failure to locate either ObjectFactory.class or jaxb.index in the packages</li>

   422      *   <li>an ambiguity among global elements contained in the contextPath</li>

   423      *   <li>failure to locate a value for the context factory provider property</li>

   424      *   <li>mixing schema derived packages from different providers on the same contextPath</li>

   425      * </ol>

   426      * @since 1.6, JAXB 2.0

   427      */

   428     public static JAXBContext newInstance( String contextPath, ClassLoader classLoader, Map<String,?>  properties  )

   429         throws JAXBException {

   430 

   431         return ContextFinder.find(

   432                         /* The default property name according to the JAXB spec */

   433                         JAXB_CONTEXT_FACTORY,

   434 

   435                         /* the context path supplied by the client app */

   436                         contextPath,

   437 

   438                         /* class loader to be used */

   439                         classLoader,

   440                         properties );

   441     }

   442 

   443 // TODO: resurrect this once we introduce external annotations

   444 //    /**

   445 //     * <p>

   446 //     * Obtain a new instance of a <tt>JAXBContext</tt> class.

   447 //     *

   448 //     * <p>

   449 //     * The client application must supply a list of classes that the new

   450 //     * context object needs to recognize.

   451 //     *

   452 //     * Not only the new context will recognize all the classes specified,

   453 //     * but it will also recognize any classes that are directly/indirectly

   454 //     * referenced statically from the specified classes.

   455 //     *

   456 //     * For example, in the following Java code, if you do

   457 //     * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext}

   458 //     * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt>:

   459 //     * <pre>

   460 //     * class Foo {

   461 //     *      Bar b;

   462 //     * }

   463 //     * class Bar { int x; }

   464 //     * class Zot extends Bar { int y; }

   465 //     * </pre>

   466 //     *

   467 //     * Therefore, a typical client application only needs to specify the

   468 //     * top-level classes, but it needs to be careful.

   469 //     *

   470 //     * TODO: if we are to define other mechanisms, refer to them.

   471 //     *

   472 //     * @param externalBindings

   473 //     *      list of external binding files. Can be null or empty if none is used.

   474 //     *      when specified, those files determine how the classes are bound.

   475 //     *

   476 //     * @param classesToBeBound

   477 //     *      list of java classes to be recognized by the new {@link JAXBContext}.

   478 //     *      Can be empty, in which case a {@link JAXBContext} that only knows about

   479 //     *      spec-defined classes will be returned.

   480 //     *

   481 //     * @return

   482 //     *      A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.

   483 //     *

   484 //     * @throws JAXBException

   485 //     *      if an error was encountered while creating the

   486 //     *      <tt>JAXBContext</tt>, such as (but not limited to):

   487 //     * <ol>

   488 //     *  <li>No JAXB implementation was discovered

   489 //     *  <li>Classes use JAXB annotations incorrectly

   490 //     *  <li>Classes have colliding annotations (i.e., two classes with the same type name)

   491 //     *  <li>Specified external bindings are incorrect

   492 //     *  <li>The JAXB implementation was unable to locate

   493 //     *      provider-specific out-of-band information (such as additional

   494 //     *      files generated at the development time.)

   495 //     * </ol>

   496 //     *

   497 //     * @throws IllegalArgumentException

   498 //     *      if the parameter contains {@code null} (i.e., {@code newInstance(null);})

   499 //     *

   500 //     * @since JAXB 2.0

   501 //     */

   502 //    public static JAXBContext newInstance( Source[] externalBindings, Class... classesToBeBound )

   503 //        throws JAXBException {

   504 //

   505 //        // empty class list is not an error, because the context will still include

   506 //        // spec-specified classes like String and Integer.

   507 //        // if(classesToBeBound.length==0)

   508 //        //    throw new IllegalArgumentException();

   509 //

   510 //        // but it is an error to have nulls in it.

   511 //        for( int i=classesToBeBound.length-1; i>=0; i-- )

   512 //            if(classesToBeBound[i]==null)

   513 //                throw new IllegalArgumentException();

   514 //

   515 //        return ContextFinder.find(externalBindings,classesToBeBound);

   516 //    }

   517 

   518     /**

   519      * <p>

   520      * Obtain a new instance of a <tt>JAXBContext</tt> class.

   521      *

   522      * <p>

   523      * The client application must supply a list of classes that the new

   524      * context object needs to recognize.

   525      *

   526      * Not only the new context will recognize all the classes specified,

   527      * but it will also recognize any classes that are directly/indirectly

   528      * referenced statically from the specified classes. Subclasses of

   529      * referenced classes nor <tt>&#64;XmlTransient</tt> referenced classes

   530      * are not registered with JAXBContext.

   531      *

   532      * For example, in the following Java code, if you do

   533      * <tt>newInstance(Foo.class)</tt>, the newly created {@link JAXBContext}

   534      * will recognize both <tt>Foo</tt> and <tt>Bar</tt>, but not <tt>Zot</tt> or <tt>FooBar</tt>:

   535      * <pre>

   536      * class Foo {

   537      *      @XmlTransient FooBar c;

   538      *      Bar b;

   539      * }

   540      * class Bar { int x; }

   541      * class Zot extends Bar { int y; }

   542      * class FooBar { }

   543      * </pre>

   544      *

   545      * Therefore, a typical client application only needs to specify the

   546      * top-level classes, but it needs to be careful.

   547      *

   548      * <p>

   549      * Note that for each java package registered with JAXBContext,

   550      * when the optional package annotations exist, they must be processed.

   551      * (see JLS, Section 7.4.1 "Named Packages").

   552      *

   553      * <p>

   554      * The steps involved in discovering the JAXB implementation is discussed in the class javadoc.

   555      *

   556      * @param classesToBeBound

   557      *      list of java classes to be recognized by the new {@link JAXBContext}.

   558      *      Can be empty, in which case a {@link JAXBContext} that only knows about

   559      *      spec-defined classes will be returned.

   560      *

   561      * @return

   562      *      A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.

   563      *

   564      * @throws JAXBException

   565      *      if an error was encountered while creating the

   566      *      <tt>JAXBContext</tt>, such as (but not limited to):

   567      * <ol>

   568      *  <li>No JAXB implementation was discovered

   569      *  <li>Classes use JAXB annotations incorrectly

   570      *  <li>Classes have colliding annotations (i.e., two classes with the same type name)

   571      *  <li>The JAXB implementation was unable to locate

   572      *      provider-specific out-of-band information (such as additional

   573      *      files generated at the development time.)

   574      * </ol>

   575      *

   576      * @throws IllegalArgumentException

   577      *      if the parameter contains {@code null} (i.e., {@code newInstance(null);})

   578      *

   579      * @since 1.6, JAXB 2.0

   580      */

   581     public static JAXBContext newInstance( Class... classesToBeBound )

   582         throws JAXBException {

   583 

   584         return newInstance(classesToBeBound,Collections.<String,Object>emptyMap());

   585     }

   586 

   587     /**

   588      * <p>

   589      * Obtain a new instance of a <tt>JAXBContext</tt> class.

   590      *

   591      * <p>

   592      * An overloading of {@link JAXBContext#newInstance(Class...)}

   593      * to configure 'properties' for this instantiation of {@link JAXBContext}.

   594      *

   595      * <p>

   596      * The interpretation of properties is up to implementations. Implementations should

   597      * throw <tt>JAXBException</tt> if it finds properties that it doesn't understand.

   598      *

   599      * @param classesToBeBound

   600      *      list of java classes to be recognized by the new {@link JAXBContext}.

   601      *      Can be empty, in which case a {@link JAXBContext} that only knows about

   602      *      spec-defined classes will be returned.

   603      * @param properties

   604      *      provider-specific properties. Can be null, which means the same thing as passing

   605      *      in an empty map.

   606      *

   607      * @return

   608      *      A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.

   609      *

   610      * @throws JAXBException

   611      *      if an error was encountered while creating the

   612      *      <tt>JAXBContext</tt>, such as (but not limited to):

   613      * <ol>

   614      *  <li>No JAXB implementation was discovered

   615      *  <li>Classes use JAXB annotations incorrectly

   616      *  <li>Classes have colliding annotations (i.e., two classes with the same type name)

   617      *  <li>The JAXB implementation was unable to locate

   618      *      provider-specific out-of-band information (such as additional

   619      *      files generated at the development time.)

   620      * </ol>

   621      *

   622      * @throws IllegalArgumentException

   623      *      if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);})

   624      *

   625      * @since 1.6, JAXB 2.0

   626      */

   627     public static JAXBContext newInstance( Class[] classesToBeBound, Map<String,?> properties )

   628         throws JAXBException {

   629 

   630         if (classesToBeBound == null) {

   631                 throw new IllegalArgumentException();

   632         }

   633 

   634         // but it is an error to have nulls in it.

   635         for (int i = classesToBeBound.length - 1; i >= 0; i--) {

   636             if (classesToBeBound[i] == null) {

   637                 throw new IllegalArgumentException();

   638             }

   639         }

   640 

   641         return ContextFinder.find(classesToBeBound,properties);

   642     }

   643 

   644     /**

   645      * Create an <tt>Unmarshaller</tt> object that can be used to convert XML

   646      * data into a java content tree.

   647      *

   648      * @return an <tt>Unmarshaller</tt> object

   649      *

   650      * @throws JAXBException if an error was encountered while creating the

   651      *                       <tt>Unmarshaller</tt> object

   652      */

   653     public abstract Unmarshaller createUnmarshaller() throws JAXBException;

   654 

   655 

   656     /**

   657      * Create a <tt>Marshaller</tt> object that can be used to convert a

   658      * java content tree into XML data.

   659      *

   660      * @return a <tt>Marshaller</tt> object

   661      *

   662      * @throws JAXBException if an error was encountered while creating the

   663      *                       <tt>Marshaller</tt> object

   664      */

   665     public abstract Marshaller createMarshaller() throws JAXBException;

   666 

   667 

   668     /**

   669      * {@link Validator} has been made optional and deprecated in JAXB 2.0.  Please

   670      * refer to the javadoc for {@link Validator} for more detail.

   671      * <p>

   672      * Create a <tt>Validator</tt> object that can be used to validate a

   673      * java content tree against its source schema.

   674      *

   675      * @return a <tt>Validator</tt> object

   676      *

   677      * @throws JAXBException if an error was encountered while creating the

   678      *                       <tt>Validator</tt> object

   679      * @deprecated since JAXB2.0

   680      */

   681     public abstract Validator createValidator() throws JAXBException;

   682 

   683     /**

   684      * Creates a <tt>Binder</tt> object that can be used for

   685      * associative/in-place unmarshalling/marshalling.

   686      *

   687      * @param domType select the DOM API to use by passing in its DOM Node class.

   688      *

   689      * @return always a new valid <tt>Binder</tt> object.

   690      *

   691      * @throws UnsupportedOperationException

   692      *      if DOM API corresponding to <tt>domType</tt> is not supported by

   693      *      the implementation.

   694      *

   695      * @since 1.6, JAXB 2.0

   696      */

   697     public <T> Binder<T> createBinder(Class<T> domType) {

   698         // to make JAXB 1.0 implementations work, this method must not be

   699         // abstract

   700         throw new UnsupportedOperationException();

   701     }

   702 

   703     /**

   704      * Creates a <tt>Binder</tt> for W3C DOM.

   705      *

   706      * @return always a new valid <tt>Binder</tt> object.

   707      *

   708      * @since 1.6, JAXB 2.0

   709      */

   710     public Binder<Node> createBinder() {

   711         return createBinder(Node.class);

   712     }

   713 

   714     /**

   715      * Creates a <tt>JAXBIntrospector</tt> object that can be used to

   716      * introspect JAXB objects.

   717      *

   718      * @return

   719      *      always return a non-null valid <tt>JAXBIntrospector</tt> object.

   720      *

   721      * @throws UnsupportedOperationException

   722      *      Calling this method on JAXB 1.0 implementations will throw

   723      *      an UnsupportedOperationException.

   724      *

   725      * @since 1.6, JAXB 2.0

   726      */

   727     public JAXBIntrospector createJAXBIntrospector() {

   728         // to make JAXB 1.0 implementations work, this method must not be

   729         // abstract

   730         throw new UnsupportedOperationException();

   731     }

   732 

   733     /**

   734      * Generates the schema documents for this context.

   735      *

   736      * @param outputResolver

   737      *      this object controls the output to which schemas

   738      *      will be sent.

   739      *

   740      * @throws IOException

   741      *      if {@link SchemaOutputResolver} throws an {@link IOException}.

   742      *

   743      * @throws UnsupportedOperationException

   744      *      Calling this method on JAXB 1.0 implementations will throw

   745      *      an UnsupportedOperationException.

   746      *

   747      * @since 1.6, JAXB 2.0

   748      */

   749     public void generateSchema(SchemaOutputResolver outputResolver) throws IOException  {

   750         // to make JAXB 1.0 implementations work, this method must not be

   751         // abstract

   752         throw new UnsupportedOperationException();

   753     }

   754 

   755     private static ClassLoader getContextClassLoader() {

   756         if (System.getSecurityManager() == null) {

   757             return Thread.currentThread().getContextClassLoader();

   758         } else {

   759             return (ClassLoader) java.security.AccessController.doPrivileged(

   760                     new java.security.PrivilegedAction() {

   761                         public java.lang.Object run() {

   762                             return Thread.currentThread().getContextClassLoader();

   763                         }

   764                     });

   765         }

   766     }

   767 

   768 }