public abstract class

Charset

extends Object
implements Comparable<T>
java.lang.Object
   ↳ java.nio.charset.Charset

Class Overview

A charset defines a mapping between a Unicode character sequence and a byte sequence. It facilitates 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 is 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 platform: 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.charset.spi.CharsetProvider. A line should end with '\r', '\n' or '\r\n'. Leading and trailing whitespaces are trimmed. Blank lines, and lines (after trimming) starting with "#" which are regarded as comments, are both ignored. Duplicates of names already found 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

Summary

Protected Constructors
Charset(String canonicalName, String[] aliases)
Constructs a Charset object.
Public Methods
final 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, false otherwise.
final 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.
final CharBuffer decode(ByteBuffer buffer)
Decodes the content of the specified byte buffer and writes it to a character buffer that is to be returned.
static Charset defaultCharset()
Gets the system default charset from the virtual machine.
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.
final ByteBuffer encode(CharBuffer buffer)
Encodes the content of the give character buffer and outputs to a byte buffer that is to be returned.
final ByteBuffer encode(String s)
Encodes a string and outputs to a byte buffer that is to be returned.
final 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.
final int hashCode()
Gets the hash code of this charset.
final boolean isRegistered()
Indicates whether this charset is known to be registered in the IANA Charset Registry.
synchronized static boolean isSupported(String charsetName)
Determines whether the specified charset is supported by this runtime.
final String name()
Gets the canonical name of this charset.
abstract CharsetDecoder newDecoder()
Gets a new instance of a decoder for this charset.
abstract CharsetEncoder newEncoder()
Gets a new instance of an encoder for this charset.
final String toString()
Gets a string representation of this charset.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Comparable

Protected Constructors

protected Charset (String canonicalName, String[] aliases)

Since: API Level 1

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. May be null.
Throws
IllegalCharsetNameException on an illegal value being supplied for either canonicalName or for any element of aliases.

Public Methods

public final Set<String> aliases ()

Since: API Level 1

Gets the set of this charset's aliases.

Returns
  • an unmodifiable set of this charset's aliases.

public static SortedMap<String, Charset> availableCharsets ()

Since: API Level 1

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

public boolean canEncode ()

Since: API Level 1

Returns true if this charset supports encoding, false otherwise.

Returns
  • true if this charset supports encoding, false otherwise.

public final int compareTo (Charset charset)

Since: API Level 1

Compares this charset with the given charset. This comparation is based on the case insensitive canonical names of the charsets.

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.

public abstract boolean contains (Charset charset)

Since: API Level 1

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, false if it's unknown or this charset is not a superset of the given charset.

public final CharBuffer decode (ByteBuffer buffer)

Since: API Level 1

Decodes the content of the specified byte buffer and writes it 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.

public static Charset defaultCharset ()

Since: API Level 1

Gets the system default charset from the virtual machine.

Returns
  • the default charset.

public String displayName ()

Since: API Level 1

Gets the name of this charset for the default locale.

The default implementation returns the canonical name of this charset. Subclasses may return a localized display name.

Returns
  • the name of this charset for the default locale.

public String displayName (Locale l)

Since: API Level 1

Gets the name of this charset for the specified locale.

The default implementation returns the canonical name of this charset. Subclasses may return a localized display name.

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

public final ByteBuffer encode (CharBuffer buffer)

Since: API Level 1

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.

public final ByteBuffer encode (String s)

Since: API Level 1

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.

public final boolean equals (Object obj)

Since: API Level 1

Determines whether this charset equals to the given object. They are considered to be equal if they have the same canonical name.

Parameters
obj the given object to be compared with.
Returns
  • true if they have the same canonical name, otherwise false.

public static Charset forName (String charsetName)

Since: API Level 1

Gets a Charset instance for the specified charset name.

Parameters
charsetName the canonical name of the charset or an alias.
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.

public final int hashCode ()

Since: API Level 1

Gets the hash code of this charset.

Returns
  • the hash code of this charset.

public final boolean isRegistered ()

Since: API Level 1

Indicates 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.

public static synchronized boolean isSupported (String charsetName)

Since: API Level 1

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.

public final String name ()

Since: API Level 1

Gets the canonical name of this charset.

Returns
  • this charset's name in canonical form.

public abstract CharsetDecoder newDecoder ()

Since: API Level 1

Gets a new instance of a decoder for this charset.

Returns
  • a new instance of a decoder for this charset.

public abstract CharsetEncoder newEncoder ()

Since: API Level 1

Gets a new instance of an encoder for this charset.

Returns
  • a new instance of an encoder for this charset.

public final String toString ()

Since: API Level 1

Gets a string representation of this charset. Usually this contains the canonical name of the charset.

Returns
  • a string representation of this charset.