#184: Refine implementation discovery

Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>
jakartaee · Feb 23, 2022 · 0458140 · 0458140
1 parent 2b5290a
commit 0458140
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 53 deletions.
diff --git a/api/src/main/java/jakarta/xml/ws/spi/FactoryFinder.java b/api/src/main/java/jakarta/xml/ws/spi/FactoryFinder.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2022 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -85,17 +85,13 @@ public WebServiceException createException(Throwable throwable, String message)
     static <T> T find(Class<T> factoryClass, String fallbackClassName) {
         ClassLoader classLoader = ServiceLoaderUtil.contextClassLoader(EXCEPTION_HANDLER);
 
-        T provider = ServiceLoaderUtil.firstByServiceLoader(factoryClass, LOGGER, EXCEPTION_HANDLER);
-        if (provider != null) return provider;
-
         String factoryId = factoryClass.getName();
 
-        // try to read from $java.home/lib/jaxws.properties
-        provider = fromJDKProperties(factoryId, fallbackClassName, classLoader);
+        // Use the system property
+        T provider = fromSystemProperty(factoryId, fallbackClassName, classLoader);
         if (provider != null) return provider;
 
-        // Use the system property
-        provider = fromSystemProperty(factoryId, fallbackClassName, classLoader);
+        provider = ServiceLoaderUtil.firstByServiceLoader(factoryClass, LOGGER, EXCEPTION_HANDLER);
         if (provider != null) return provider;
 
         // handling Glassfish (platform specific default)
@@ -130,35 +126,6 @@ private static <T> T fromSystemProperty(String factoryId,
         return null;
     }
 
-    private static <T> T fromJDKProperties(String factoryId,
-                                            String fallbackClassName,
-                                            ClassLoader classLoader) {
-        Path path = null;
-        try {
-            String JAVA_HOME = System.getProperty("java.home");
-            path = Paths.get(JAVA_HOME, "conf", "jaxws.properties");
-
-            // to ensure backwards compatibility
-            if (!Files.exists(path)) {
-                path = Paths.get(JAVA_HOME, "lib", "jaxws.properties");
-            }
-
-            if (Files.exists(path)) {
-                LOGGER.log(Level.FINE, "Found {0}", path);
-                Properties props = new Properties();
-                try (InputStream inStream = Files.newInputStream(path)) {
-                    props.load(inStream);
-                }
-                String factoryClassName = props.getProperty(factoryId);
-                return newInstance(factoryClassName, fallbackClassName, classLoader);
-            }
-        } catch (Throwable t) {
-            LOGGER.log(Level.SEVERE, "Error reading Jakarta XML Web Services configuration from ["  + path +
-                    "] file. Check it is accessible and has correct format.", t);
-        }
-        return null;
-    }
-
     private static final String OSGI_SERVICE_LOADER_CLASS_NAME = "org.glassfish.hk2.osgiresourcelocator.ServiceLoader";
 
     private static boolean isOsgi() {

diff --git a/api/src/main/java/jakarta/xml/ws/spi/Provider.java b/api/src/main/java/jakarta/xml/ws/spi/Provider.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2022 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -45,16 +45,16 @@ protected Provider() {
      * The algorithm used to locate the provider subclass to use consists
      * of the following steps:
      * <ul>
+     *  <li> If a system property with the name {@code jakarta.xml.ws.spi.Provider}
+     *  is defined, then its value is used as the name of the implementation class.
+     *  This phase of the look up enables per-JVM override of the Jakarta XML Web Services implementation.
      *  <li> Use the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class,
      *  to attempt to locate and load an implementation of {@link jakarta.xml.ws.spi.Provider} service using
      *  the {@linkplain java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}.
-     *  <li>Use the configuration file "jaxws.properties". The file is in standard
-     *  {@link java.util.Properties} format and typically located in the
-     *  {@code conf} directory of the Java installation. It contains the fully qualified
-     *  name of the implementation class with the key {@code jakarta.xml.ws.spi.Provider}.
-     *  <li> If a system property with the name {@code jakarta.xml.ws.spi.Provider}
-     *  is defined, then its value is used as the name of the implementation class.
-     *  <li> Finally, a platform default implementation is used.
+     *  <li>
+     *  Finally, if all the steps above fail, then the rest of the lookup is unspecified. That said,
+     *  the recommended behavior is to simply look for some hard-coded platform default Jakarta XML Web Services implementation.
+     *  This phase of the lookup is so that the environment can have its own Jakarta XML Web Services implementation as the last resort.
      * </ul>
      *
      * @return provider object

diff --git a/spec/src/main/asciidoc/appB-change_log.adoc b/spec/src/main/asciidoc/appB-change_log.adoc
@@ -11,6 +11,8 @@
 * Merged Jakarta Web Services Metadata specification into Jakarta Web Services specification.
 * Annotated `jakarta.xml.ws.AsyncHandler` with `@FunctionalInterface`.
 * Extended the API of `jakarta.xml.ws.wsaddressing.W3CEndpointReference` with getters.
+* Updated the definition of the discovery process of
+`javax.xml.ws.spi.Provider` implementation (<<providerdiscovery>>)
 
 === 3.0 Changes
 

diff --git a/spec/src/main/asciidoc/ch06-core_apis.adoc b/spec/src/main/asciidoc/ch06-core_apis.adoc
@@ -1,5 +1,5 @@
 //
-// Copyright (c) 2020 Contributors to the Eclipse Foundation
+// Copyright (c) 2020, 2022 Contributors to the Eclipse Foundation
 //
 
 [[core-apis]]
@@ -70,17 +70,18 @@ the `java.lang.Class.forName(String)` method. As soon as a step results
 in an implementation class being successfully loaded, the algorithm
 terminates.
 
+. If a system property with the name `jakarta.xml.ws.spi.Provider` is
+defined, then its value is used as the name of the implementation class.
+This phase of the look up enables per-JVM override
+of the Jakarta XML Web Services implementation.
 . Use the service-provider loading facilities, defined by the
 `java.util.ServiceLoader` class, to attempt to locate and load an
 implementation of `jakarta.xml.ws.spi.Provider` service using the default
 loading mechanism .
-. Use the configuration file `jaxws.properties`. The file is in
-standard `java.util.Properties` format and typically located in the conf
-directory of the Java installation. It contains the fully qualified name
-of the implementation class with the key `jakarta.xml.ws.spi.Provider`.
-. If a system property with the name `jakarta.xml.ws.spi.Provider` is
-defined, then its value is used as the name of the implementation class.
-. Finally, a platform implementation is used.
+. Finally, if all the steps above fail, then the rest of the lookup is unspecified.
+That said, the recommended behavior is to simply look for some hard-coded platform
+default Jakarta XML Web Services implementation. This phase of the lookup is
+so that the environment can have its own Jakarta XML Web Services implementation as the last resort.
 
 [[providerendpointcreation]]
 ==== Creating Endpoint Objects