1 /* 2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.nio.charset.spi; 27 28 import java.nio.charset.Charset; 29 import java.util.Iterator; 30 31 32 /** 33 * Charset service-provider class. 34 * 35 * <p> A charset provider is a concrete subclass of this class that has a 36 * zero-argument constructor and some number of associated charset 37 * implementation classes. Charset providers may be installed in an instance 38 * of the Java platform as extensions. Providers may also be made available by 39 * adding them to the applet or application class path or by some other 40 * platform-specific means. Charset providers are looked up via the current 41 * thread's {@link java.lang.Thread#getContextClassLoader() context class 42 * loader}. 43 * 44 * <p> A charset provider identifies itself with a provider-configuration file 45 * named {@code java.nio.charset.spi.CharsetProvider} in the resource 46 * directory {@code META-INF/services}. The file should contain a list of 47 * fully-qualified concrete charset-provider class names, one per line. A line 48 * is terminated by any one of a line feed ({@code '\n'}), a carriage return 49 * ({@code '\r'}), or a carriage return followed immediately by a line feed. 50 * Space and tab characters surrounding each name, as well as blank lines, are 51 * ignored. The comment character is {@code '#'} (<code>'\u0023'</code>); on 52 * each line all characters following the first comment character are ignored. 53 * The file must be encoded in UTF-8. 54 * 55 * <p> If a particular concrete charset provider class is named in more than 56 * one configuration file, or is named in the same configuration file more than 57 * once, then the duplicates will be ignored. The configuration file naming a 58 * particular provider need not be in the same jar file or other distribution 59 * unit as the provider itself. The provider must be accessible from the same 60 * class loader that was initially queried to locate the configuration file; 61 * this is not necessarily the class loader that loaded the file. </p> 62 * 63 * 64 * @author Mark Reinhold 65 * @author JSR-51 Expert Group 66 * @since 1.4 67 * 68 * @see java.nio.charset.Charset 69 */ 70 71 public abstract class CharsetProvider { 72 checkPermission()73 private static Void checkPermission() { 74 SecurityManager sm = System.getSecurityManager(); 75 if (sm != null) 76 sm.checkPermission(new RuntimePermission("charsetProvider")); 77 return null; 78 } CharsetProvider(Void ignore)79 private CharsetProvider(Void ignore) { } 80 81 /** 82 * Initializes a new charset provider. 83 * 84 * @throws SecurityException 85 * If a security manager has been installed and it denies 86 * {@link RuntimePermission}{@code ("charsetProvider")} 87 */ CharsetProvider()88 protected CharsetProvider() { 89 this(checkPermission()); 90 } 91 92 /** 93 * Creates an iterator that iterates over the charsets supported by this 94 * provider. This method is used in the implementation of the {@link 95 * java.nio.charset.Charset#availableCharsets Charset.availableCharsets} 96 * method. 97 * 98 * @return The new iterator 99 */ charsets()100 public abstract Iterator<Charset> charsets(); 101 102 /** 103 * Retrieves a charset for the given charset name. 104 * 105 * @param charsetName 106 * The name of the requested charset; may be either 107 * a canonical name or an alias 108 * 109 * @return A charset object for the named charset, 110 * or {@code null} if the named charset 111 * is not supported by this provider 112 */ charsetForName(String charsetName)113 public abstract Charset charsetForName(String charsetName); 114 115 } 116