KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > nio > charset > spi > CharsetProvider


1 /*
2  * @(#)CharsetProvider.java 1.15 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.nio.charset.spi;
9
10 import java.nio.charset.Charset JavaDoc;
11 import java.util.Iterator JavaDoc;
12
13
14 /**
15  * Charset service-provider class.
16  *
17  * <p> A charset provider is a concrete subclass of this class that has a
18  * zero-argument constructor and some number of associated charset
19  * implementation classes. Charset providers may be installed in an instance
20  * of the Java platform as extensions, that is, jar files placed into any of
21  * the usual extension directories. Providers may also be made available by
22  * adding them to the applet or application class path or by some other
23  * platform-specific means. Charset providers are looked up via the current
24  * thread's {@link java.lang.Thread#getContextClassLoader() </code>context
25  * class loader<code>}.
26  *
27  * <p> A charset provider identifies itself with a provider-configuration file
28  * named <tt>java.nio.charset.spi.CharsetProvider</tt> in the resource
29  * directory <tt>META-INF/services</tt>. The file should contain a list of
30  * fully-qualified concrete charset-provider class names, one per line. A line
31  * is terminated by any one of a line feed (<tt>'\n'</tt>), a carriage return
32  * (<tt>'\r'</tt>), or a carriage return followed immediately by a line feed.
33  * Space and tab characters surrounding each name, as well as blank lines, are
34  * ignored. The comment character is <tt>'#'</tt> (<tt>'&#92;u0023'</tt>); on
35  * each line all characters following the first comment character are ignored.
36  * The file must be encoded in UTF-8.
37  *
38  * <p> If a particular concrete charset provider class is named in more than
39  * one configuration file, or is named in the same configuration file more than
40  * once, then the duplicates will be ignored. The configuration file naming a
41  * particular provider need not be in the same jar file or other distribution
42  * unit as the provider itself. The provider must be accessible from the same
43  * class loader that was initially queried to locate the configuration file;
44  * this is not necessarily the class loader that loaded the file. </p>
45  *
46  *
47  * @author Mark Reinhold
48  * @author JSR-51 Expert Group
49  * @version 1.15, 04/05/05
50  * @since 1.4
51  *
52  * @see java.nio.charset.Charset
53  */
54
55 public abstract class CharsetProvider {
56
57     /**
58      * Initializes a new charset provider. </p>
59      *
60      * @throws SecurityException
61      * If a security manager has been installed and it denies
62      * {@link RuntimePermission}<tt>("charsetProvider")</tt>
63      */
64     protected CharsetProvider() {
65     SecurityManager JavaDoc sm = System.getSecurityManager();
66     if (sm != null)
67         sm.checkPermission(new RuntimePermission JavaDoc("charsetProvider"));
68     }
69
70     /**
71      * Creates an iterator that iterates over the charsets supported by this
72      * provider. This method is used in the implementation of the {@link
73      * java.nio.charset.Charset#availableCharsets Charset.availableCharsets}
74      * method. </p>
75      *
76      * @return The new iterator
77      */
78     public abstract Iterator JavaDoc<Charset JavaDoc> charsets();
79
80     /**
81      * Retrieves a charset for the given charset name. </p>
82      *
83      * @param charsetName
84      * The name of the requested charset; may be either
85      * a canonical name or an alias
86      *
87      * @return A charset object for the named charset,
88      * or <tt>null</tt> if the named charset
89      * is not supported by this provider
90      */
91     public abstract Charset JavaDoc charsetForName(String JavaDoc charsetName);
92
93 }
94
Popular Tags