8340404: CharsetProvider specification updates

Reviewed-by: alanb, naoto

Author: Justin Lu

src/java.base/share/classes/java/nio/charset/spi/CharsetProvider.java

@@ -33,17 +33,29 @@
  * Charset service-provider class.
  *
  * <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
  * is terminated by any one of a line feed ({@code '\n'}), a carriage return
  * ({@code '\r'}), or a carriage return followed immediately by a line feed.

test/jdk/java/nio/charset/spi/CharsetProviderAsModuleTest.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2024, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug 8340404
+ * @summary Check that a CharsetProvider SPI can be deployed as a module
+ * @build provider/*
+ * @run main/othervm CharsetProviderAsModuleTest
+ */
+
+import java.nio.charset.Charset;
+
+public class CharsetProviderAsModuleTest {
+
+    // Basic test ensures that our BAZ charset is loaded via the BazProvider
+    public static void main(String[] args) {
+        var cs = Charset.availableCharsets();
+        Charset bazCs;
+        // check provider is providing BAZ via charsets()
+        if (!cs.containsKey("BAZ")) {
+            throw new RuntimeException("SPI BazProvider did not provide BAZ Charset");
+        } else {
+            bazCs = cs.get("BAZ");
+            // check provider is in a named module
+            if (!bazCs.getClass().getModule().isNamed()) {
+                throw new RuntimeException("BazProvider is not a named module");
+            }
+            var aliases = bazCs.aliases();
+            // check BAZ cs aliases were loaded correctly
+            if (!aliases.contains("BAZ-1") || !aliases.contains("BAZ-2")) {
+                throw new RuntimeException("BAZ Charset did not provide correct aliases");
+            }
+            // check provider implements charsetForName()
+            if (!bazCs.equals(Charset.forName("BAZ"))) {
+                throw new RuntimeException("SPI BazProvider provides bad charsetForName()");
+            }
+        }
+    }
+}

test/jdk/java/nio/charset/spi/provider/module-info.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2024, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+module provider {
+    provides java.nio.charset.spi.CharsetProvider with spi.BazProvider;
+}

test/jdk/java/nio/charset/spi/provider/spi/BazProvider.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2024, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package spi;
+
+import java.nio.charset.Charset;
+import java.nio.charset.CharsetDecoder;
+import java.nio.charset.CharsetEncoder;
+import java.nio.charset.spi.CharsetProvider;
+import java.util.Collections;
+import java.util.Iterator;
+
+// Provides some simple BAZ related attributes to our provider
+public class BazProvider extends CharsetProvider {
+
+    @Override
+    public Iterator charsets() {
+        return Collections.singleton(new BazCharset()).iterator();
+    }
+
+    @Override
+    public Charset charsetForName(String charsetName) {
+        if (charsetName.equals("BAZ")) {
+            return new BazCharset();
+        } else {
+            return null;
+        }
+    }
+
+    public static class BazCharset extends Charset {
+
+        public BazCharset() {
+            super("BAZ", new String[] { "BAZ-1", "BAZ-2" });
+        }
+
+        // Overrides to satisfy Charset
+        @Override
+        public boolean contains(Charset cs) {
+            return false;
+        }
+
+        @Override
+        public CharsetDecoder newDecoder() {
+            return null;
+        }
+
+        @Override
+        public CharsetEncoder newEncoder() {
+            return null;
+        }
+    }
+}