# HG changeset patch
# User Doug Simon <doug.simon@oracle.com>
# Date 1433946481 -7200
# Node ID 763db13bd6f49af2b919792c0e0ff051caf4d8ab
# Parent  91b861398ad60733b663baf885362bdd69b3e018
reworded Service documentation to be interms of "providers" instead of "implementations" to better match documentation for the standard ServiceLoader mechanism

diff -r 91b861398ad6 -r 763db13bd6f4 jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/Service.java
--- a/jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/Service.java	Wed Jun 10 16:10:26 2015 +0200
+++ b/jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/Service.java	Wed Jun 10 16:28:01 2015 +0200
@@ -23,11 +23,14 @@
 package com.oracle.jvmci.service;
 
 /**
- * Marker interface for a service implementation that can be loaded by {@link Services#load(Class)}
- * or {@link Services#loadSingle(Class, boolean)}. These implementations are hidden behind a class
- * loader not accessible to applications. For this reason, {@link Services#load(Class)} and
+ * Marker interface for a service provider that can be loaded by {@link Services#load(Class)} or
+ * {@link Services#loadSingle(Class, boolean)}. These providers are hidden behind a class loader not
+ * accessible to applications. For this reason, {@link Services#load(Class)} and
  * {@link Services#loadSingle(Class, boolean)} perform {@link SecurityManager} checks.
  *
+ * If this marker interface is applied to a service interface <i>S</I> as opposed to a service
+ * provider, then all providers implementing <i>S</i> have the semantics described above.
+ *
  * @see Services
  * @see ServiceProvider
  */
diff -r 91b861398ad6 -r 763db13bd6f4 jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/ServiceProvider.java
--- a/jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/ServiceProvider.java	Wed Jun 10 16:10:26 2015 +0200
+++ b/jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/ServiceProvider.java	Wed Jun 10 16:28:01 2015 +0200
@@ -25,8 +25,8 @@
 import java.lang.annotation.*;
 
 /**
- * Annotates a JVMCI implementation of a service. This annotation is used by the JVMCI build system
- * to deploy the necessary files used to {@linkplain Services#load(Class) load} services at runtime.
+ * Annotates a JVMCI provider of a service. This annotation is used by the JVMCI build system to
+ * deploy the necessary files used to {@linkplain Services#load(Class) load} services at runtime.
  */
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.TYPE)
diff -r 91b861398ad6 -r 763db13bd6f4 jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/Services.java
--- a/jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/Services.java	Wed Jun 10 16:10:26 2015 +0200
+++ b/jvmci/com.oracle.jvmci.service/src/com/oracle/jvmci/service/Services.java	Wed Jun 10 16:28:01 2015 +0200
@@ -27,15 +27,15 @@
 import sun.reflect.*;
 
 /**
- * An mechanism for loading services that have a {@linkplain Service JVMCI implementation}.
+ * An mechanism for accessing {@link Service JVMCI service providers}.
  */
 public class Services {
 
     private static final String SUPPRESS_PROPERTY_NAME = "jvmci.service.suppressNoClassDefFoundError";
 
     /**
-     * Determines whether to suppress the {@link NoClassDefFoundError} raised if a service
-     * implementation class specified in a {@code <jre>/jvmci/services/*} file is missing.
+     * Determines whether to suppress the {@link NoClassDefFoundError} raised if a service provider
+     * class specified in a {@code <jre>/jvmci/services/*} file is missing.
      */
     private static final boolean SuppressNoClassDefFoundError = Boolean.getBoolean(SUPPRESS_PROPERTY_NAME);
 
@@ -59,7 +59,7 @@
     };
 
     /**
-     * Gets an {@link Iterable} of the JVMCI implementations available for a given service.
+     * Gets an {@link Iterable} of the JVMCI providers available for a given service.
      *
      * @throws SecurityException if a security manager is present and it denies
      *             <tt>{@link RuntimePermission}("jvmciServices")</tt>
@@ -79,12 +79,11 @@
     }
 
     /**
-     * Gets the JVMCI implementation for a given service for which at most one implementation must
-     * be available.
+     * Gets the JVMCI provider for a given service for which at most one provider must be available.
      *
-     * @param service the service whose implementation is being requested
-     * @param required specifies if an {@link InternalError} should be thrown if no implementation
-     *            of {@code service} is available
+     * @param service the service whose provider is being requested
+     * @param required specifies if an {@link InternalError} should be thrown if no provider of
+     *            {@code service} is available
      * @throws SecurityException if a security manager is present and it denies
      *             <tt>{@link RuntimePermission}("jvmciServices")</tt>
      */
@@ -95,21 +94,21 @@
         if (sm != null) {
             sm.checkPermission(new RuntimePermission("jvmciServices"));
         }
-        Iterable<S> impls;
+        Iterable<S> providers;
         try {
-            impls = (Iterable<S>) cache.get(service);
+            providers = (Iterable<S>) cache.get(service);
         } catch (UnsatisfiedLinkError e) {
-            impls = Collections.emptyList();
+            providers = Collections.emptyList();
         }
 
-        S singleImpl = null;
-        for (S impl : impls) {
-            if (singleImpl != null) {
-                throw new InternalError(String.format("Multiple %s implementations found: %s, %s", service.getName(), singleImpl.getClass().getName(), impl.getClass().getName()));
+        S singleProvider = null;
+        for (S provider : providers) {
+            if (singleProvider != null) {
+                throw new InternalError(String.format("Multiple %s providers found: %s, %s", service.getName(), singleProvider.getClass().getName(), provider.getClass().getName()));
             }
-            singleImpl = impl;
+            singleProvider = provider;
         }
-        if (singleImpl == null && required) {
+        if (singleProvider == null && required) {
             String javaHome = System.getProperty("java.home");
             String vmName = System.getProperty("java.vm.name");
             Formatter errorMessage = new Formatter();
@@ -118,7 +117,7 @@
             errorMessage.format("Currently used VM configuration is: %s", vmName);
             throw new UnsupportedOperationException(errorMessage.toString());
         }
-        return singleImpl;
+        return singleProvider;
     }
 
     static {