1 /*
2 * Copyright 2000-2004 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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() </code>context
43 * class loader<code>}.
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. </p>
76 *
77 * @throws SecurityException
78 * If a security manager has been installed and it denies
79 * {@link RuntimePermission}<tt>("charsetProvider")</tt>
80 */
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. </p>
92 *
93 * @return The new iterator
94 */
95 public abstract Iterator<Charset> charsets();
96
97 /**
98 * Retrieves a charset for the given charset name. </p>
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 */
108 public abstract Charset charsetForName(String charsetName);
109
110 }
Save This Page