/*

 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.nio.charset.spi;

import java.nio.charset.Charset;

import java.util.Iterator;

/**

 * Charset service-provider class.

 *

 * <p> A charset provider is a concrete subclass of this class that has a

 * zero-argument constructor and some number of associated charset

 * implementation classes.  Charset providers may be installed in an instance

 * adding them to the applet or application class path or by some other

 * platform-specific means.  Charset providers are looked up via the current

 * thread's {@link java.lang.Thread#getContextClassLoader() context class

 * loader}.

 *

 * <p> A charset provider identifies itself with a provider-configuration file

 * named <tt>java.nio.charset.spi.CharsetProvider</tt> in the resource

 * directory <tt>META-INF/services</tt>.  The file should contain a list of

 * fully-qualified concrete charset-provider class names, one per line.  A line

 * is terminated by any one of a line feed (<tt>'\n'</tt>), a carriage return

 * (<tt>'\r'</tt>), or a carriage return followed immediately by a line feed.

 * Space and tab characters surrounding each name, as well as blank lines, are

 * ignored.  The comment character is <tt>'#'</tt> (<tt>'&#92;u0023'</tt>); on

 * each line all characters following the first comment character are ignored.

 * The file must be encoded in UTF-8.

 *

 * <p> If a particular concrete charset provider class is named in more than

 * one configuration file, or is named in the same configuration file more than

 * once, then the duplicates will be ignored.  The configuration file naming a

 * particular provider need not be in the same jar file or other distribution

 * unit as the provider itself.  The provider must be accessible from the same

 * class loader that was initially queried to locate the configuration file;

 * this is not necessarily the class loader that loaded the file. </p>

 *

 *

 * @author Mark Reinhold

 * @author JSR-51 Expert Group

 * @since 1.4

 *

 * @see java.nio.charset.Charset

 */

public abstract class CharsetProvider {

    private static Void checkPermission() {

        SecurityManager sm = System.getSecurityManager();

        if (sm != null)

            sm.checkPermission(new RuntimePermission("charsetProvider"));

        return null;

    }

    private CharsetProvider(Void ignore) { }

    /**

     * Initializes a new charset provider.

     *

     * @throws  SecurityException

     *          If a security manager has been installed and it denies

     *          {@link RuntimePermission}<tt>("charsetProvider")</tt>

     */

    protected CharsetProvider() {

        this(checkPermission());

    }

    /**

     * Creates an iterator that iterates over the charsets supported by this

     * provider.  This method is used in the implementation of the {@link

     * java.nio.charset.Charset#availableCharsets Charset.availableCharsets}

     * method.

     *

     * @return  The new iterator

     */

    public abstract Iterator<Charset> charsets();

    /**

     * Retrieves a charset for the given charset name.

     *

     * @param  charsetName

     *         The name of the requested charset; may be either

     *         a canonical name or an alias

     *

     * @return  A charset object for the named charset,

     *          or <tt>null</tt> if the named charset

     *          is not supported by this provider

     */

    public abstract Charset charsetForName(String charsetName);

}