jdk-sandbox: comparison jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContext.java

equal deleted inserted replaced

-:5b500c93ce48
+:a542f8dcbbf8
 * <p>A client application normally obtains new instances of this class using
 * one of these two styles for newInstance methods, although there are other
 * specialized forms of the method available:
 *
 * <ul>
-*   <li>{@link #newInstance(String,ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br>
+* <li>{@link #newInstance(String, ClassLoader) JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )} <br>
-*   The JAXBContext instance is initialized from a list of colon
+* The JAXBContext instance is initialized from a list of colon
-*   separated Java package names. Each java package contains
+* separated Java package names. Each java package contains
-*   JAXB mapped classes, schema-derived classes and/or user annotated
+* JAXB mapped classes, schema-derived classes and/or user annotated
-*   classes. Additionally, the java package may contain JAXB package annotations
+* classes. Additionally, the java package may contain JAXB package annotations
-*   that must be processed. (see JLS, Section 7.4.1 "Named Packages").
+* that must be processed. (see JLS, Section 7.4.1 "Named Packages").
-*   </li>
+* </li>
-*   <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br>
+* <li>{@link #newInstance(Class...) JAXBContext.newInstance( com.acme.foo.Foo.class )} <br>
-*    The JAXBContext instance is initialized with class(es)
+* The JAXBContext instance is initialized with class(es)
-*    passed as parameter(s) and classes that are statically reachable from
+* passed as parameter(s) and classes that are statically reachable from
-*    these class(es). See {@link #newInstance(Class...)} for details.
+* these class(es). See {@link #newInstance(Class...)} for details.
-*   </li>
+* </li>
 * </ul>
-*
-* <p>
-* <i><B>SPEC REQUIREMENT:</B> the provider must supply an implementation
-* class containing the following method signatures:</i>
-*
-* <pre>{@code
-* public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException
-* public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException
-* }</pre>
 *
 * <p><i>
 * The following JAXB 1.0 requirement is only required for schema to
 * java interface/implementation binding. It does not apply to JAXB annotated
 * classes. JAXB Providers must generate a <tt>jaxb.properties</tt> file in
 * context should be namespace independent.  This means that a client
 * application is able to unmarshal XML documents that are instances of
 * any of the schemas listed in the <tt>contextPath</tt>.  For example:
 *
 * <pre>
-*        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
+*      JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
-*        Unmarshaller u = jc.createUnmarshaller();
+*      Unmarshaller u = jc.createUnmarshaller();
-*        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
+*      FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
-*        BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
+*      BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
-*        BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
+*      BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath
 * </pre>
 *
 * <p>
 * The client application may also generate Java content trees explicitly rather
 * than unmarshalling existing XML data.  For all JAXB-annotated value classes,
 * <p>
 * For more information on the generated <tt>ObjectFactory</tt> classes, see
 * Section 4.2 <i>Java Package</i> of the specification.
 *
 * <p>
-* <i><B>SPEC REQUIREMENT:</B> the provider must generate a class in each
+* <i>The provider must generate a class in each
 * package that contains all of the necessary object factory methods for that
 * package named ObjectFactory as well as the static
 * <tt>newInstance( javaContentInterface )</tt> method</i>
 *
 * <h3>Marshalling</h3>
 * <p>
 * When one of the <tt>newInstance</tt> methods is called, a JAXB implementation is discovered
 * by the following steps.
 *
 * <ol>
+*
 * <li>
 * For each package/class explicitly passed in to the {@link #newInstance} method, in the order they are specified,
 * <tt>jaxb.properties</tt> file is looked up in its package, by using the associated classloader &mdash;
 * this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package
 * the specified {@link ClassLoader}.
 *
 * <p>
 * If such a file is discovered, it is {@link Properties#load(InputStream) loaded} as a property file, and
 * the value of the {@link #JAXB_CONTEXT_FACTORY} key will be assumed to be the provider factory class.
-* This class is then loaded by the associated classloader discussed above.
+* This class is then loaded by the associated class loader discussed above.
 *
 * <p>
 * This phase of the look up allows some packages to force the use of a certain JAXB implementation.
 * (For example, perhaps the schema compiler has generated some vendor extension in the code.)
 *
 * <li>
 * If the system property {@link #JAXB_CONTEXT_FACTORY} exists, then its value is assumed to be the provider
 * factory class. This phase of the look up enables per-JVM override of the JAXB implementation.
 *
 * <li>
-* Look for <tt>/META-INF/services/javax.xml.bind.JAXBContext</tt> file in the associated classloader.
+* Provider of {@link javax.xml.bind.JAXBContextFactory} is loaded using the service-provider loading
-* This file follows the standard service descriptor convention, and if such a file exists, its content
+* facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
-* is assumed to be the provider factory class. This phase of the look up is for automatic discovery.
+* to locate and load an implementation of the service using the {@linkplain
-* It allows users to just put a JAXB implementation in a classpath and use it without any furhter configuration.
+* java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: the service-provider loading facility
+* will use the {@linkplain java.lang.Thread#getContextClassLoader() current thread's context class loader}
+* to attempt to load the context factory. If the context class loader is null, the
+* {@linkplain ClassLoader#getSystemClassLoader() system class loader} will be used.
+* <br>
+* In case of {@link java.util.ServiceConfigurationError service
+* configuration error} a {@link javax.xml.bind.JAXBException} will be thrown.
+* </li>
+*
+* <li>
+* Look for resource {@code /META-INF/services/javax.xml.bind.JAXBContext} using provided class loader.
+* Methods without class loader parameter use {@code Thread.currentThread().getContextClassLoader()}.
+* If such a resource exists, its content is assumed to be the provider factory class and must supply
+* an implementation class containing the following method signatures:
+*
+* <pre>
+*
+* public static JAXBContext createContext(
+*                                      String contextPath,
+*                                      ClassLoader classLoader,
+*                                      Map&lt;String,Object&gt; properties throws JAXBException
+*
+* public static JAXBContext createContext(
+*                                      Class[] classes,
+*                                      Map&lt;String,Object&gt; properties ) throws JAXBException
+* </pre>
+* This configuration method is deprecated.
 *
 * <li>
 * Finally, if all the steps above fail, then the rest of the look up is unspecified. That said,
 * the recommended behavior is to simply look for some hard-coded platform default JAXB implementation.
 * This phase of the look up is so that JavaSE can have its own JAXB implementation as the last resort.
 * </ol>
 *
 * <p>
-* Once the provider factory class is discovered, its
+* Once the provider factory class {@link javax.xml.bind.JAXBContextFactory} is discovered, one of its methods
-* <tt>public static JAXBContext createContext(String,ClassLoader,Map)</tt> method
+* {@link javax.xml.bind.JAXBContextFactory#createContext(String, ClassLoader, java.util.Map)} or
-* (see {@link #newInstance(String, ClassLoader, Map)} for the parameter semantics.)
+* {@link javax.xml.bind.JAXBContextFactory#createContext(Class[], java.util.Map)} is invoked
-* or <tt>public static JAXBContext createContet(Class[],Map)</tt> method
-* (see {@link #newInstance(Class[], Map)} for the parameter semantics) are invoked
 * to create a {@link JAXBContext}.
 *
-* @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
+* <p/>
+*
+* @apiNote
+* <p>Service discovery method using file /META-INF/services/javax.xml.bind.JAXBContext (described in step 4)
+* and leveraging provider's static methods is supported only to allow backwards compatibility, but it is strongly
+* recommended to migrate to standard ServiceLoader mechanism (described in step 3).
+*
+* @implNote
+* Within the last step, if Glassfish AS environment detected, its specific service loader is used to find factory class.
+*
+* @author <ul><li>Ryan Shoemaker, Sun Microsystems, Inc.</li>
+*             <li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li>
+*             <li>Joe Fialli, Sun Microsystems, Inc.</li></ul>
+*
 * @see Marshaller
 * @see Unmarshaller
-* @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1">S 7.4.1 "Named Packages" in Java Language Specification</a>
+* @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1">S 7.4.1 "Named Packages"
+*      in Java Language Specification</a>
+*
 * @since 1.6, JAXB 1.0
 */
 public abstract class JAXBContext {
 /**
 * The name of the property that contains the name of the class capable
 * of creating new <tt>JAXBContext</tt> objects.
 */
-public static final String JAXB_CONTEXT_FACTORY =
+public static final String JAXB_CONTEXT_FACTORY = "javax.xml.bind.JAXBContextFactory";
-"javax.xml.bind.context.factory";
 protected JAXBContext() {
 }
 /**
 * <p>
-* Obtain a new instance of a <tt>JAXBContext</tt> class.
+* Create a new instance of a <tt>JAXBContext</tt> class.
 *
 * <p>
 * This is a convenience method to invoke the
 * {@link #newInstance(String,ClassLoader)} method with
 * the context class loader of the current thread.
 return newInstance( contextPath, getContextClassLoader());
 }
 /**
 * <p>
-* Obtain a new instance of a <tt>JAXBContext</tt> class.
+* Create a new instance of a <tt>JAXBContext</tt> class.
 *
 * <p>
 * The client application must supply a context path which is a list of
 * colon (':', \u005Cu003A) separated java package names that contain
 * schema-derived classes and/or fully qualified JAXB-annotated classes.
 return newInstance(contextPath,classLoader,Collections.<String,Object>emptyMap());
 }
 /**
 * <p>
-* Obtain a new instance of a <tt>JAXBContext</tt> class.
+* Create a new instance of a <tt>JAXBContext</tt> class.
 *
 * <p>
 * This is mostly the same as {@link JAXBContext#newInstance(String, ClassLoader)},
 * but this version allows you to pass in provider-specific properties to configure
 * the instantiation of {@link JAXBContext}.
 *   <li>failure to locate a value for the context factory provider property</li>
 *   <li>mixing schema derived packages from different providers on the same contextPath</li>
 * </ol>
 * @since 1.6, JAXB 2.0
 */
-public static JAXBContext newInstance( String contextPath, ClassLoader classLoader, Map<String,?>  properties  )
+public static JAXBContext newInstance( String contextPath,
-throws JAXBException {
+ClassLoader classLoader,
+Map<String,?>  properties  ) throws JAXBException {
 return ContextFinder.find(
 /* The default property name according to the JAXB spec */
 JAXB_CONTEXT_FACTORY,
 }
 // TODO: resurrect this once we introduce external annotations
 //    /**
 //     * <p>
-//     * Obtain a new instance of a <tt>JAXBContext</tt> class.
+//     * Create a new instance of a <tt>JAXBContext</tt> class.
 //     *
 //     * <p>
 //     * The client application must supply a list of classes that the new
 //     * context object needs to recognize.
 //     *
 //     *      list of java classes to be recognized by the new {@link JAXBContext}.
 //     *      Can be empty, in which case a {@link JAXBContext} that only knows about
 //     *      spec-defined classes will be returned.
 //     *
 //     * @return
-//     *      A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.
+//     *      A new instance of a <tt>JAXBContext</tt>.
 //     *
 //     * @throws JAXBException
 //     *      if an error was encountered while creating the
 //     *      <tt>JAXBContext</tt>, such as (but not limited to):
 //     * <ol>
 //        return ContextFinder.find(externalBindings,classesToBeBound);
 //    }
 /**
 * <p>
-* Obtain a new instance of a <tt>JAXBContext</tt> class.
+* Create a new instance of a <tt>JAXBContext</tt> class.
 *
 * <p>
 * The client application must supply a list of classes that the new
 * context object needs to recognize.
 *
 *      list of java classes to be recognized by the new {@link JAXBContext}.
 *      Can be empty, in which case a {@link JAXBContext} that only knows about
 *      spec-defined classes will be returned.
 *
 * @return
-*      A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.
+*      A new instance of a <tt>JAXBContext</tt>.
 *
 * @throws JAXBException
 *      if an error was encountered while creating the
 *      <tt>JAXBContext</tt>, such as (but not limited to):
 * <ol>
 * @throws IllegalArgumentException
 *      if the parameter contains {@code null} (i.e., {@code newInstance(null);})
 *
 * @since 1.6, JAXB 2.0
 */
-public static JAXBContext newInstance( Class... classesToBeBound )
+public static JAXBContext newInstance( Class<?> ... classesToBeBound )
 throws JAXBException {
 return newInstance(classesToBeBound,Collections.<String,Object>emptyMap());
 }
 /**
 * <p>
-* Obtain a new instance of a <tt>JAXBContext</tt> class.
+* Create a new instance of a <tt>JAXBContext</tt> class.
 *
 * <p>
 * An overloading of {@link JAXBContext#newInstance(Class...)}
 * to configure 'properties' for this instantiation of {@link JAXBContext}.
 *
 * @param properties
 *      provider-specific properties. Can be null, which means the same thing as passing
 *      in an empty map.
 *
 * @return
-*      A new instance of a <tt>JAXBContext</tt>. Always non-null valid object.
+*      A new instance of a <tt>JAXBContext</tt>.
 *
 * @throws JAXBException
 *      if an error was encountered while creating the
 *      <tt>JAXBContext</tt>, such as (but not limited to):
 * <ol>
 * @throws IllegalArgumentException
 *      if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);})
 *
 * @since 1.6, JAXB 2.0
 */
-public static JAXBContext newInstance( Class[] classesToBeBound, Map<String,?> properties )
+public static JAXBContext newInstance( Class<?>[] classesToBeBound, Map<String,?> properties )
 throws JAXBException {
 if (classesToBeBound == null) {
 throw new IllegalArgumentException();
 }
 private static ClassLoader getContextClassLoader() {
 if (System.getSecurityManager() == null) {
 return Thread.currentThread().getContextClassLoader();
 } else {
-return (ClassLoader) java.security.AccessController.doPrivileged(
+return java.security.AccessController.doPrivileged(
-new java.security.PrivilegedAction() {
+new java.security.PrivilegedAction<ClassLoader>() {
-public java.lang.Object run() {
+public ClassLoader run() {
 return Thread.currentThread().getContextClassLoader();
 }
 });
 }
 }

changeset 31109	a542f8dcbbf8
parent 29839	6d5d546e953b
child 31501	1b48499c9e1c