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.  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>'&#92;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
71public abstract class CharsetProvider {
72
73    private static Void checkPermission() {
74        SecurityManager sm = System.getSecurityManager();
75        if (sm != null)
76            sm.checkPermission(new RuntimePermission("charsetProvider"));
77        return null;
78    }
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     */
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     */
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     */
113    public abstract Charset charsetForName(String charsetName);
114
115}
116