Build 1.0_r1(from source)

java.nio.charset
Class Charset

java.lang.Object
  extended by java.nio.charset.Charset
All Implemented Interfaces:
Comparable<Charset>

public abstract class Charset
extends Object
implements Comparable<Charset>

A charset defines a mapping between a Unicode character sequence and a byte sequence. It facilitate the encoding from a Unicode character sequence into a byte sequence, and the decoding from a byte sequence into a Unicode character sequence.

A charset has a canonical name, which are usually in uppercase. Typically it also has one or more aliases. The name string can only consist of the following characters: '0' - '9', 'A' - 'Z', 'a' - 'z', '.', ':'. '-' and '_'. The first character of the name must be a digit or a letter.

The following charsets should be supported by any java platforms: US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16.

Additional charsets can be made available by configuring one or more charset providers through provider configuration files. Such files are always named as "java.nio.charset.spi.CharsetProvider" and located in the "META-INF/services" sub folder of one or more classpaths. The files should be encoded in "UTF-8". Each line of their content specifies the class name of a charset provider which extends java.nio.spi.CharsetProvider. A line should ends with '\r', '\n' or '\r\n'. Leading and trailing whitespaces are trimmed. Blank lines, and lines (after trimmed) starting with "#" which are regarded as comments, are both ignored. Duplicates of already appeared names are also ignored. Both the configuration files and the provider classes will be loaded using the thread context class loader.

This class is thread-safe.

See Also:
CharsetProvider

Nested Class Summary
(package private) static class Charset.IgnoreCaseComparator
          A comparator that ignores case.
 
Constructor Summary
protected Charset(String canonicalName, String[] aliases)
          Constructs a Charset object.
 
Method Summary
 Set<String> aliases()
          Gets the set of this charset's aliases.
static SortedMap<String,Charset> availableCharsets()
          Gets a map of all available charsets supported by the runtime.
 boolean canEncode()
          Returns true if this charset supports encoding, otherwise false.
 int compareTo(Charset charset)
          Compares this charset with the given charset.
abstract  boolean contains(Charset charset)
          Determines whether this charset is a super set of the given charset.
 CharBuffer decode(ByteBuffer buffer)
          Decodes the content of the give byte buffer and outputs to a character buffer that is to be returned.
static Charset defaultCharset()
          Gets the system default charset from jvm.
 String displayName()
          Gets the name of this charset for the default locale.
 String displayName(Locale l)
          Gets the name of this charset for the specified locale.
 ByteBuffer encode(CharBuffer buffer)
          Encodes the content of the give character buffer and outputs to a byte buffer that is to be returned.
 ByteBuffer encode(String s)
          Encodes a string and outputs to a byte buffer that is to be returned.
 boolean equals(Object obj)
          Determines whether this charset equals to the given object.
static Charset forName(String charsetName)
          Gets a Charset instance for the specified charset name.
 int hashCode()
          Gets the hash code of this charset.
 boolean isRegistered()
          Returns whether this charset is known to be registered in the IANA Charset Registry.
static boolean isSupported(String charsetName)
          Determines whether the specified charset is supported by this runtime.
 String name()
          Gets the canonical name of this charset.
abstract  CharsetDecoder newDecoder()
          Gets a new instance of decoder for this charset.
abstract  CharsetEncoder newEncoder()
          Gets a new instance of encoder for this charset.
 String toString()
          Gets a string representation of this charset.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Charset

protected Charset(String canonicalName,
                  String[] aliases)
           throws IllegalCharsetNameException
Constructs a Charset object. Duplicated aliases are ignored.

Parameters:
canonicalName - the canonical name of the charset
aliases - an array containing all aliases of the charset
Throws:
IllegalCharsetNameException - on an illegal value being supplied for either canonicalName or for any element of aliases.
Method Detail

availableCharsets

public static SortedMap<String,Charset> availableCharsets()
Gets a map of all available charsets supported by the runtime.

The returned map contains mappings from canonical names to corresponding instances of Charset. The canonical names can be considered as case-insensitive.

Returns:
an unmodifiable map of all available charsets supported by the runtime

forName

public static Charset forName(String charsetName)
                       throws IllegalCharsetNameException,
                              UnsupportedCharsetException
Gets a Charset instance for the specified charset name.

Parameters:
charsetName - the name of the charset
Returns:
a Charset instance for the specified charset name
Throws:
IllegalCharsetNameException - If the specified charset name is illegal.
UnsupportedCharsetException - If the desired charset is not supported by this runtime.

isSupported

public static boolean isSupported(String charsetName)
                           throws IllegalCharsetNameException
Determines whether the specified charset is supported by this runtime.

Parameters:
charsetName - the name of the charset
Returns:
true if the specified charset is supported, otherwise false
Throws:
IllegalCharsetNameException - If the specified charset name is illegal.

contains

public abstract boolean contains(Charset charset)
Determines whether this charset is a super set of the given charset.

Parameters:
charset - a given charset
Returns:
true if this charset is a super set of the given charset, otherwise false

newEncoder

public abstract CharsetEncoder newEncoder()
Gets a new instance of encoder for this charset.

Returns:
a new instance of encoder for this charset

newDecoder

public abstract CharsetDecoder newDecoder()
Gets a new instance of decoder for this charset.

Returns:
a new instance of decoder for this charset

name

public final String name()
Gets the canonical name of this charset.

Returns:
this charset's name in canonical form.

aliases

public final Set<String> aliases()
Gets the set of this charset's aliases.

Returns:
an unmodifiable set of this charset's aliases

displayName

public String displayName()
Gets the name of this charset for the default locale.

Returns:
the name of this charset for the default locale

displayName

public String displayName(Locale l)
Gets the name of this charset for the specified locale.

Parameters:
l - a certain locale
Returns:
the name of this charset for the specified locale

isRegistered

public final boolean isRegistered()
Returns whether this charset is known to be registered in the IANA Charset Registry.

Returns:
true if the charset is known to be registered, otherwise returns false.

canEncode

public boolean canEncode()
Returns true if this charset supports encoding, otherwise false.

Returns:
true

encode

public final ByteBuffer encode(CharBuffer buffer)
Encodes the content of the give character buffer and outputs to a byte buffer that is to be returned.

The default action in case of encoding errors is CodingErrorAction.REPLACE.

Parameters:
buffer - the character buffer containing the content to be encoded
Returns:
the result of the encoding

encode

public final ByteBuffer encode(String s)
Encodes a string and outputs to a byte buffer that is to be returned.

The default action in case of encoding errors is CodingErrorAction.REPLACE.

Parameters:
s - the string to be encoded
Returns:
the result of the encoding

decode

public final CharBuffer decode(ByteBuffer buffer)
Decodes the content of the give byte buffer and outputs to a character buffer that is to be returned.

The default action in case of decoding errors is CodingErrorAction.REPLACE.

Parameters:
buffer - the byte buffer containing the content to be decoded
Returns:
a character buffer containing the output of the decoding

compareTo

public final int compareTo(Charset charset)
Compares this charset with the given charset.

Specified by:
compareTo in interface Comparable<Charset>
Parameters:
charset - the given object to be compared with
Returns:
a negative integer if less than the given object, a positive integer if larger than it, or 0 if equal to it

equals

public final boolean equals(Object obj)
Determines whether this charset equals to the given object. They are considered to be equal if they have the same canonical name.

Overrides:
equals in class Object
Parameters:
obj - the given object to be compared with
Returns:
true if they have the same canonical name, otherwise false
See Also:
Object.hashCode()

hashCode

public final int hashCode()
Gets the hash code of this charset.

Overrides:
hashCode in class Object
Returns:
the hash code of this charset
See Also:
Object.equals(java.lang.Object)

toString

public final String toString()
Gets a string representation of this charset. Usually this contains the canonical name of the charset.

Overrides:
toString in class Object
Returns:
a string representation of this charset

defaultCharset

public static Charset defaultCharset()
Gets the system default charset from jvm.

Returns:
the default charset

Build 1.0_r1(from source)

Please submit a feedback, bug or feature