java.nio.charset
Class Charset

java.lang.Object
  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