Summary

Update the CharsetProvider specification to reflect its current state as well as remove outdated statements.

Problem

The CharsetProvider specification has not been updated since the module system was introduced, and thus lacks commentary on deploying as a module. Additionally, there is some outdated wording that should be clarified or removed, such as "Charset providers are looked up via the current thread's context class loader". In reality, it is the system class loader that looks up CharsetProvider SPI implementations.

Solution

Make apparent that a CharsetProvider implementation can be provided via the application module path. Provide a brief description and example, as well as pointing users to ServiceLoader's deploying service providers section for further info.

Additionally, remove the statement that providers may be installed as extensions and fix the incorrect statement that providers are loaded via the context class loader.

Specification

In the main class description,

  * <p> A charset provider is a concrete subclass of this class that has a
- * zero-argument constructor and some number of associated charset
- * implementation classes.  Charset providers may be installed in an instance
- * of the Java platform as extensions.  Providers may also be made available by
- * adding them to the application class path or by some other
- * platform-specific means.  Charset providers are looked up via the current
- * thread's {@link java.lang.Thread#getContextClassLoader() context class
- * loader}.
+ * zero-argument constructor and some number of associated {@code Charset}
+ * implementation classes.  Charset providers are deployed on the application
+ * module path or the application class path. In order to be looked up, charset
+ * providers must be visible to the {@link ClassLoader#getSystemClassLoader() system
+ * class loader}. See {@link java.util.ServiceLoader##developing-service-providers
+ * Deploying Service Providers} for further detail on deploying a charset
+ * provider as a module or on the class path.
  *
- * <p> A charset provider identifies itself with a provider-configuration file
- * named {@code java.nio.charset.spi.CharsetProvider} in the resource
- * directory {@code META-INF/services}.  The file should contain a list of
+ * <p> For a charset provider deployed in a module, the <i>provides</i>
+ * directive must be specified in the module declaration. The provides directive
+ * specifies both the service and the service provider. In this case, the service
+ * is {@code java.nio.charset.spi.CharsetProvider}.
+ *
+ * <p> As an example, a charset provider deployed as a module might specify the
+ * following directive:
+ * <pre>{@code
+ *     provides java.nio.charset.spi.CharsetProvider with com.example.ExternalCharsetProvider;
+ * }</pre>
+ *
+ * <p> For a charset provider deployed on the class path, it identifies itself
+ * with a provider-configuration file named {@code
+ * java.nio.charset.spi.CharsetProvider} in the resource directory
+ * {@code META-INF/services}.  The file should contain a list of
  * fully-qualified concrete charset-provider class names, one per line.  A line