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, that is, jar files placed into any of 39 * the usual extension directories. Providers may also be made available by 40 * adding them to the applet or application class path or by some other 41 * platform-specific means. Charset providers are looked up via the current 42 * thread's {@link java.lang.Thread#getContextClassLoader() context class 43 * loader}. 44 * 45 * <p> A charset provider identifies itself with a provider-configuration file 46 * named <tt>java.nio.charset.spi.CharsetProvider</tt> in the resource 47 * directory <tt>META-INF/services</tt>. The file should contain a list of 48 * fully-qualified concrete charset-provider class names, one per line. A line 49 * is terminated by any one of a line feed (<tt>'\n'</tt>), a carriage return 50 * (<tt>'\r'</tt>), or a carriage return followed immediately by a line feed. 51 * Space and tab characters surrounding each name, as well as blank lines, are 52 * ignored. The comment character is <tt>'#'</tt> (<tt>'\u0023'</tt>); on 53 * each line all characters following the first comment character are ignored. 54 * The file must be encoded in UTF-8. 55 * 56 * <p> If a particular concrete charset provider class is named in more than 57 * one configuration file, or is named in the same configuration file more than 58 * once, then the duplicates will be ignored. The configuration file naming a 59 * particular provider need not be in the same jar file or other distribution 60 * unit as the provider itself. The provider must be accessible from the same 61 * class loader that was initially queried to locate the configuration file; 62 * this is not necessarily the class loader that loaded the file. </p> 63 * 64 * 65 * @author Mark Reinhold 66 * @author JSR-51 Expert Group 67 * @since 1.4 68 * 69 * @see java.nio.charset.Charset 70 */ 71 72 public abstract class CharsetProvider { 73 74 /** 75 * Initializes a new charset provider. 76 * 77 * @throws SecurityException 78 * If a security manager has been installed and it denies 79 * {@link RuntimePermission}<tt>("charsetProvider")</tt> 80 */ CharsetProvider()81 protected CharsetProvider() { 82 SecurityManager sm = System.getSecurityManager(); 83 if (sm != null) 84 sm.checkPermission(new RuntimePermission("charsetProvider")); 85 } 86 87 /** 88 * Creates an iterator that iterates over the charsets supported by this 89 * provider. This method is used in the implementation of the {@link 90 * java.nio.charset.Charset#availableCharsets Charset.availableCharsets} 91 * method. 92 * 93 * @return The new iterator 94 */ charsets()95 public abstract Iterator<Charset> charsets(); 96 97 /** 98 * Retrieves a charset for the given charset name. 99 * 100 * @param charsetName 101 * The name of the requested charset; may be either 102 * a canonical name or an alias 103 * 104 * @return A charset object for the named charset, 105 * or <tt>null</tt> if the named charset 106 * is not supported by this provider 107 */ charsetForName(String charsetName)108 public abstract Charset charsetForName(String charsetName); 109 110 } 111