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
26package java.nio.charset.spi;
27
28import java.nio.charset.Charset;
29import 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>'&#92;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
72public 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     */
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     */
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     */
108    public abstract Charset charsetForName(String charsetName);
109
110}
111