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