1 /*

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

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

     4  *

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

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

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

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

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

    10  *

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

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

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

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

    15  * accompanied this code).

    16  *

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

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

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

    20  *

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

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

    23  * questions.

    24  */

    25 

    26 package javax.xml.bind;

    27 

    28 import java.util.Map;

    29 

    30 /**

    31  * <p>Factory that creates new <code>JAXBContext</code> instances.

    32  *

    33  * JAXBContextFactory can be located using {@link java.util.ServiceLoader#load(Class)}

    34  *

    35  * @since 1.9, JAXB 2.3

    36  */

    37 public interface JAXBContextFactory {

    38 

    39     /**

    40      * <p>

    41      * Create a new instance of a <tt>JAXBContext</tt> class.

    42      *

    43      * <p>

    44      * For semantics see {@link javax.xml.bind.JAXBContext#newInstance(Class[], java.util.Map)}

    45      *

    46      * @param classesToBeBound

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

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

    49      *      spec-defined classes will be returned.

    50      * @param properties

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

    52      *      in an empty map.

    53      *

    54      * @return

    55      *      A new instance of a <tt>JAXBContext</tt>.

    56      *

    57      * @throws JAXBException

    58      *      if an error was encountered while creating the

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

    60      * <ol>

    61      *  <li>Classes use JAXB annotations incorrectly

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

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

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

    65      *      files generated at the development time.)

    66      * </ol>

    67      *

    68      * @throws IllegalArgumentException

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

    70      *

    71      * @since 1.9, JAXB 2.3

    72      */

    73     JAXBContext createContext(Class<?>[] classesToBeBound,

    74                               Map<String, ?> properties ) throws JAXBException;

    75 

    76     /**

    77      * <p>

    78      * Create a new instance of a <tt>JAXBContext</tt> class.

    79      *

    80      * <p>

    81      * For semantics see {@link javax.xml.bind.JAXBContext#newInstance(String, ClassLoader, java.util.Map)}

    82      *

    83      * <p>

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

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

    86      *

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

    88      * @param classLoader

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

    90      * @param properties

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

    92      *      in an empty map.

    93      *

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

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

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

    97      * <ol>

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

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

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

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

   102      * </ol>

   103      * @since 1.9, JAXB 2.3

   104      */

   105     JAXBContext createContext(String contextPath,

   106                               ClassLoader classLoader,

   107                               Map<String, ?> properties ) throws JAXBException;

   108 

   109 }