# HG changeset patch # User mkos # Date 1454329677 -3600 # Node ID 59fc48a1a885ffb1b8e3ff518ec923d62871d6b4 # Parent 56a695bbebe8a5ed8965db7026ef180a6a53309f 8138699: Improving JAX-B API javadoc Reviewed-by: lancea diff -r 56a695bbebe8 -r 59fc48a1a885 jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContext.java --- a/jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContext.java Fri Jan 29 13:10:55 2016 +0100 +++ b/jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContext.java Mon Feb 01 13:27:57 2016 +0100 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -94,7 +94,7 @@ * allows the merging of global elements and type definitions across a set of schemas (listed * in the {@code contextPath}). Since each schema in the schema set can belong * to distinct namespaces, the unification of schemas to an unmarshalling - * context should be namespace independent. This means that a client + * context must 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 {@code contextPath}. For example: * @@ -200,21 +200,28 @@ * *

Discovery of JAXB implementation

*

- * When one of the {@code newInstance} methods is called, a JAXB implementation is discovered - * by the following steps. + * To create an instance of {@link JAXBContext}, one of {@code JAXBContext.newInstance(...)} methods is invoked. After + * JAX-B implementation is discovered, call is delegated to appropriate provider's method {@code createContext(...)} + * passing parameters from the original call. + *

+ * JAX-B implementation discovery happens each time {@code JAXBContext.newInstance} is invoked. If there is no user + * specific configuration provided, default JAX-B provider must be returned. + *

+ * Implementation discovery consists of following steps: * *

    * *
  1. - * For each package/class explicitly passed in to the {@link #newInstance} method, in the order they are specified, - * {@code jaxb.properties} file is looked up in its package, by using the associated classloader — + * Packages/classes explicitly passed in to the {@link #newInstance} method are processed in the order they are + * specified, until {@code jaxb.properties} file is looked up in its package, by using the associated classloader — * this is {@link Class#getClassLoader() the owner class loader} for a {@link Class} argument, and for a package * the specified {@link ClassLoader}. * *

    - * 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 class loader discussed above. + * If such a resource 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. If no value + * found, {@code "javax.xml.bind.context.factory"} is used as a key for backwards compatibility reasons. This class is + * then loaded by the associated class loader discussed above. * *

    * This phase of the look up allows some packages to force the use of a certain JAXB implementation. @@ -222,7 +229,9 @@ * *

  2. * 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. + * factory class. If no such property exists, properties {@code "javax.xml.bind.context.factory"} and + * {@code "javax.xml.bind.JAXBContext"} are checked too (in this order), for backwards compatibility reasons. This phase + * of the look up enables per-JVM override of the JAXB implementation. * *
  3. * Provider of {@link javax.xml.bind.JAXBContextFactory} is loaded using the service-provider loading @@ -235,43 +244,58 @@ *
    * In case of {@link java.util.ServiceConfigurationError service * configuration error} a {@link javax.xml.bind.JAXBException} will be thrown. - *
    4. * *
  4. * 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: + * If such a resource exists, its content is assumed to be the provider factory class. + * + * This configuration method is deprecated. + * + *
  5. + * 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 Java SE can have its own JAXB implementation as the last resort. + *
* + *

+ * Once the provider factory class is discovered, context creation is delegated to one of its + * {@code createContext(...)} methods. + * + * For backward compatibility reasons, there are two ways how to implement provider factory class: + *

    + *
  1. the class is implementation of {@link javax.xml.bind.JAXBContextFactory}. It must also implement no-arg + * constructor. If discovered in other step then 3, new instance using no-arg constructor is created first. + * After that, appropriate instance method is invoked on this instance. + *
  2. the class is not implementation of interface above and then it is mandated to implement the following + * static method signatures: * 
      *
  * public static JAXBContext createContext(
  *                                      String contextPath,
  *                                      ClassLoader classLoader,
- *                                      Map<String,Object> properties throws JAXBException
+ *                                      Map<String,Object> properties ) throws JAXBException
  *
  * public static JAXBContext createContext(
  *                                      Class[] classes,
  *                                      Map<String,Object> properties ) throws JAXBException
  *
    - * This configuration method is deprecated. - * - *
  3. - * 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. + * In this scenario, appropriate static method is used instead of instance method. This approach is incompatible + * with {@link java.util.ServiceLoader} so it can't be used with step 3. *
- * *

- * Once the provider factory class {@link javax.xml.bind.JAXBContextFactory} is discovered, one of its methods - * {@link javax.xml.bind.JAXBContextFactory#createContext(String, ClassLoader, java.util.Map)} or - * {@link javax.xml.bind.JAXBContextFactory#createContext(Class[], java.util.Map)} is invoked - * to create a {@link JAXBContext}. + * There is no difference in behavior of given method {@code createContext(...)} regardless of whether it uses approach + * 1 (JAXBContextFactory) or 2 (no interface, static methods). * * @apiNote - *

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). + * Service discovery method using resource {@code /META-INF/services/javax.xml.bind.JAXBContext} (described in step 4) + * is supported only to allow backwards compatibility, it is strongly recommended to migrate to standard + * {@link java.util.ServiceLoader} mechanism (described in step 3). The difference here is the resource name, which + * doesn't match service's type name. + *

+ * Also using providers implementing interface {@link JAXBContextFactory} is preferred over using ones defining + * static methods, same as {@link JAXBContext#JAXB_CONTEXT_FACTORY} property is preferred over property + * {@code "javax.xml.bind.context.factory"} * * @implNote * Within the last step, if Glassfish AS environment detected, its specific service loader is used to find factory class. @@ -308,16 +332,10 @@ * the context class loader of the current thread. * * @throws JAXBException if an error was encountered while creating the - * {@code JAXBContext} such as - *

    - *
  1. failure to locate either ObjectFactory.class or jaxb.index in the packages
    2. - *
  2. an ambiguity among global elements contained in the contextPath
    3. - *
  3. failure to locate a value for the context factory provider property
    4. - *
  4. mixing schema derived packages from different providers on the same contextPath
    5. - *
+ * {@code JAXBContext}. See {@link JAXBContext#newInstance(String, ClassLoader, Map)} for details. */ public static JAXBContext newInstance( String contextPath ) - throws JAXBException { + throws JAXBException { //return newInstance( contextPath, JAXBContext.class.getClassLoader() ); return newInstance( contextPath, getContextClassLoader()); @@ -405,13 +423,7 @@ * * @return a new instance of a {@code JAXBContext} * @throws JAXBException if an error was encountered while creating the - * {@code JAXBContext} such as - *
    - *
  1. failure to locate either ObjectFactory.class or jaxb.index in the packages
    2. - *
  2. an ambiguity among global elements contained in the contextPath
    3. - *
  3. failure to locate a value for the context factory provider property
    4. - *
  4. mixing schema derived packages from different providers on the same contextPath
    5. - *
+ * {@code JAXBContext}. See {@link JAXBContext#newInstance(String, ClassLoader, Map)} for details. */ public static JAXBContext newInstance( String contextPath, ClassLoader classLoader ) throws JAXBException { @@ -427,7 +439,7 @@ * the instantiation of {@link JAXBContext}. * *

- * The interpretation of properties is up to implementations. Implementations should + * The interpretation of properties is up to implementations. Implementations must * throw {@code JAXBException} if it finds properties that it doesn't understand. * * @param contextPath list of java package names that contain schema derived classes @@ -439,13 +451,7 @@ * * @return a new instance of a {@code JAXBContext} * @throws JAXBException if an error was encountered while creating the - * {@code JAXBContext} such as - *

    - *
  1. failure to locate either ObjectFactory.class or jaxb.index in the packages
    2. - *
  2. an ambiguity among global elements contained in the contextPath
    3. - *
  3. failure to locate a value for the context factory provider property
    4. - *
  4. mixing schema derived packages from different providers on the same contextPath
    5. - *
+ * {@code JAXBContext}. See {@link #newInstance(String, ClassLoader)} for details. * @since 1.6, JAXB 2.0 */ public static JAXBContext newInstance( String contextPath, @@ -454,14 +460,14 @@ return ContextFinder.find( /* The default property name according to the JAXB spec */ - JAXB_CONTEXT_FACTORY, + JAXB_CONTEXT_FACTORY, /* the context path supplied by the client app */ - contextPath, + contextPath, /* class loader to be used */ - classLoader, - properties ); + classLoader, + properties ); } // TODO: resurrect this once we introduce external annotations @@ -583,17 +589,8 @@ * @return * A new instance of a {@code JAXBContext}. * - * @throws JAXBException - * if an error was encountered while creating the - * {@code JAXBContext}, such as (but not limited to): - *
    - *
  1. No JAXB implementation was discovered - *
  2. Classes use JAXB annotations incorrectly - *
  3. Classes have colliding annotations (i.e., two classes with the same type name) - *
  4. The JAXB implementation was unable to locate - * provider-specific out-of-band information (such as additional - * files generated at the development time.) - *
+ * @throws JAXBException if an error was encountered while creating the + * {@code JAXBContext}. See {@link JAXBContext#newInstance(Class[], Map)} for details. * * @throws IllegalArgumentException * if the parameter contains {@code null} (i.e., {@code newInstance(null);}) @@ -601,7 +598,7 @@ * @since 1.6, JAXB 2.0 */ public static JAXBContext newInstance( Class ... classesToBeBound ) - throws JAXBException { + throws JAXBException { return newInstance(classesToBeBound,Collections.emptyMap()); } @@ -614,7 +611,7 @@ * to configure 'properties' for this instantiation of {@link JAXBContext}. * *

- * The interpretation of properties is up to implementations. Implementations should + * The interpretation of properties is up to implementations. Implementations must * throw {@code JAXBException} if it finds properties that it doesn't understand. * * @param classesToBeBound @@ -646,10 +643,10 @@ * @since 1.6, JAXB 2.0 */ public static JAXBContext newInstance( Class[] classesToBeBound, Map properties ) - throws JAXBException { + throws JAXBException { if (classesToBeBound == null) { - throw new IllegalArgumentException(); + throw new IllegalArgumentException(); } // but it is an error to have nulls in it. diff -r 56a695bbebe8 -r 59fc48a1a885 jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContextFactory.java --- a/jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContextFactory.java Fri Jan 29 13:10:55 2016 +0100 +++ b/jaxws/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContextFactory.java Mon Feb 01 13:27:57 2016 +0100 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -56,14 +56,7 @@ * * @throws JAXBException * if an error was encountered while creating the - * {@code JAXBContext}, such as (but not limited to): - *

    - *
  1. Classes use JAXB annotations incorrectly - *
  2. Classes have colliding annotations (i.e., two classes with the same type name) - *
  3. The JAXB implementation was unable to locate - * provider-specific out-of-band information (such as additional - * files generated at the development time.) - *
+ * {@code JAXBContext}. See {@link JAXBContext#newInstance(Class[], Map)} for details. * * @throws IllegalArgumentException * if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);}) @@ -81,7 +74,7 @@ * For semantics see {@link javax.xml.bind.JAXBContext#newInstance(String, ClassLoader, java.util.Map)} * *

- * The interpretation of properties is up to implementations. Implementations should + * The interpretation of properties is up to implementations. Implementations must * throw {@code JAXBException} if it finds properties that it doesn't understand. * * @param contextPath list of java package names that contain schema derived classes @@ -93,13 +86,8 @@ * * @return a new instance of a {@code JAXBContext} * @throws JAXBException if an error was encountered while creating the - * {@code JAXBContext} such as - *

    - *
  1. failure to locate either ObjectFactory.class or jaxb.index in the packages
    2. - *
  2. an ambiguity among global elements contained in the contextPath
    3. - *
  3. failure to locate a value for the context factory provider property
    4. - *
  4. mixing schema derived packages from different providers on the same contextPath
    5. - *
+ * {@code JAXBContext}. See {@link JAXBContext#newInstance(String, ClassLoader, Map)} for details. + * * @since 9, JAXB 2.3 */ JAXBContext createContext(String contextPath,