--- old/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContextFactory.java 2017-05-03 18:05:15.655096015 +0300
+++ new/src/java.xml.bind/share/classes/javax/xml/bind/JAXBContextFactory.java 2017-05-03 18:05:15.547096018 +0300
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2017, 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
@@ -44,7 +44,9 @@
* For semantics see {@link javax.xml.bind.JAXBContext#newInstance(Class[], java.util.Map)}
*
* @param classesToBeBound
- * list of java classes to be recognized by the new {@link JAXBContext}.
+ * List of java classes to be recognized by the new {@link JAXBContext}.
+ * Classes in {@code classesToBeBound} that are in named modules must be in a package
+ * that is {@linkplain java.lang.reflect.Module#isOpen open} to at least the {@code java.xml.bind} module.
* Can be empty, in which case a {@link JAXBContext} that only knows about
* spec-defined classes will be returned.
* @param properties
@@ -56,7 +58,16 @@
*
* @throws JAXBException
* if an error was encountered while creating the
- * {@code JAXBContext}. See {@link JAXBContext#newInstance(Class[], Map)} for details.
+ * {@code JAXBContext}, such as (but not limited to):
+ *
+ * - No JAXB implementation was discovered
+ *
- Classes use JAXB annotations incorrectly
+ *
- Classes have colliding annotations (i.e., two classes with the same type name)
+ *
- The JAXB implementation was unable to locate
+ * provider-specific out-of-band information (such as additional
+ * files generated at the development time.)
+ *
- {@code classesToBeBound} are not open to {@code java.xml.bind} module
+ *
*
* @throws IllegalArgumentException
* if the parameter contains {@code null} (i.e., {@code newInstance(null,someMap);})
@@ -77,7 +88,10 @@
* 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
+ * @param contextPath
+ * List of java package names that contain schema derived classes.
+ * Classes in {@code classesToBeBound} that are in named modules must be in a package
+ * that is {@linkplain java.lang.reflect.Module#isOpen open} to at least the {@code java.xml.bind} module.
* @param classLoader
* This class loader will be used to locate the implementation classes.
* @param properties
@@ -86,7 +100,14 @@
*
* @return a new instance of a {@code JAXBContext}
* @throws JAXBException if an error was encountered while creating the
- * {@code JAXBContext}. See {@link JAXBContext#newInstance(String, ClassLoader, Map)} for details.
+ * {@code JAXBContext} such as
+ *
+ * - failure to locate either ObjectFactory.class or jaxb.index in the packages
+ * - an ambiguity among global elements contained in the contextPath
+ * - failure to locate a value for the context factory provider property
+ * - mixing schema derived packages from different providers on the same contextPath
+ * - packages are not open to {@code java.xml.bind} module
+ *
*
* @since 9, JAXB 2.3
*/