8340404: CharsetProvider specification updates

Reviewed-by: alanb, naoto
This commit is contained in:
Justin Lu 2024-09-27 18:26:08 +00:00
parent a7bfced605
commit 082125d61e
4 changed files with 178 additions and 10 deletions
src/java.base/share/classes/java/nio/charset/spi
test/jdk/java/nio/charset/spi

@ -33,17 +33,29 @@ import java.util.Iterator;
* 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.

@ -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()");
}
}
}
}

@ -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;
}

@ -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;
}
}
}