java.nio.charset

异常
错误
java.lang.Object
  继承者 java.nio.charset.Charset
所有已实现的接口:
Comparable< Charset>

public abstract class Charset
     
extends Object
implements Comparable< Charset>

16 位的 Unicode 代码单元序列和字节序列之间的指定映射关系。此类定义了用于创建解码器和编码器以及获取与 charset 关联的各种名称的方法。此类的实例是不可变的。

此类也定义了用于测试是否支持特定 charset 的静态方法、通过名称查找 charset 实例的静态方法,以及构造一个包含目前 Java 虚拟机支持的每个 charset 的映射静态方法。通过类 CharsetProvider 中定义的服务提供者接口可以添加对新 charset 的支持。

此类中定义的所有方法用于多个并发线程是安全的。

Charset 名称

通过以下字符所组成的字符串来命名 Charset:

  • 大写字母 'A''Z''\u0041' 到 '\u005a'),
  • 小写字母 'a''z''=pos;  到  ' apos;),
  • 数字 '0''9''\u0030'  到  '\u0039'),
  • 短划线字符 '-''\u002d'连词符号),
  • 句点字符 '.'('\u002e'句点),
  • 冒号字符 ':'('\u003a'冒号),和
  • 下划线字符 '_''\u005f'下划线)。
Charset 名称必须以字母或数字开头。空字符串不是合法的 charset 名称。Charset 名称是大小写不敏感的,也就是当比较 charset 名称时总是忽略大小写。Charset 名称通常遵循
RFC2278:IANA Charset Registration Procedures 中所记录的约定。

每个 charset 有一个规范名称,也可能有一个或多个别名。规范名称由此类的 name 方法返回。根据约定,规范名称通常是大写的。charset 的别名由 aliases 方法返回。

一些 charset 有一个历史名称,定义这个名称是为了和以前版本的 Java 平台兼容。charset 的历史名称既可以是它的规范名称,也可以是它的某个别名。历史名称由 InputStreamReaderOutputStreamWriter 类的 getEncoding() 方法返回。

如果 Java 平台的实现支持列于 IANA Charset Registry 中的 charset,那么它的规范名称必须是注册表中列出的名字。很多 charset 在注册表中给出不止一个名称,在这种情况下注册表将某个名称标识为 MIME 首选的。如果 charset 有多个注册表名称,那么它的规范名称必须是 MIME 首选的名称,并且注册表中的其他名称必须是合法的别名。如果支持的 charset 没有列在 IANA 注册表中,那么它的规范名称必须以字符串 "X-""x-" 中的一个开头。

IANA charset 注册表不断进行更改,所以特定 charset 的规范名称和别名也会随之更改。为了确保兼容性,推荐不要删除 charset 的别名,如果更改了 charset 的规范名称,那么可将以前的规范名称作为别名。

标准 charset

Java 平台的每一种实现都需要支持以下标准 charset。请参考该实现的版本文档,查看是否支持其他 charset。这些可选 charset 的行为在不同的实现之间可能有所不同。

Charset

描述

US-ASCII 7 位 ASCII 字符,也叫作 ISO646-US、Unicode 字符集的基本拉丁块
ISO-8859-1   ISO 拉丁字母表 No.1,也叫作 ISO-LATIN-1
UTF-8 8 位 UCS 转换格式
UTF-16BE 16 位 UCS 转换格式,Big Endian(最低地址存放高位字节)字节顺序
UTF-16LE 16 位 UCS 转换格式,Little-endian(最高地址存放低位字节)字节顺序
UTF-16 16 位 UCS 转换格式,字节顺序由可选的字节顺序标记来标识

UTF-8 charset 在 RFC 2279 中指定;它所基于的转换格式在 ISO 10646-1 的 Amendment 2 中指定,并在 Unicode Standard 中也有所描述。

UTF-16 charset 在 RFC 2781 中指定;它们基于的转换格式在 ISO10646-1 的 Amendment 1 中指定,并在 Unicode Standard 中也有所描述。

UTF-16 charset 使用 16 位量,因此对字节顺序敏感。在这些编码中,流的字节顺序可以由 Unicode 字符 'FF' 所表示的初始字节顺序标记 来指示。按以下方式处理字节顺序标记:

  • 进行解码时,UTF-16BEUTF-16LE charset 忽略字节顺序标记;进行编码时,不写入字节顺序标记。

  • 进行解码时,UTF-16 charset 解释字节顺序标记,以指示流的字节顺序,但是如果没有字节顺序标记,则默认使用 Big Endian;进行编码时,使用 Big Endian 字节顺序并写入 Big Endian 字节顺序标记。

在任何情况中,在解码操作的开始读取字节顺序标记时,将在结果字符序列中忽略该标记。字节顺序标记出现在输入序列的第一个元素之后时,由于使用相同的代码表示 零宽度不间断空格,所以不忽略该标记。

Java 虚拟机的每个实例都有默认的 charset,它可能是也可能不是某个标准 charset。默认 charset 在虚拟机启动时决定,通常根据语言环境和底层操作系统使用的 charset 来确定。

术语

此类的名称取自 RFC 2278 中使用的术语。在该文档中,charset 被定义为编码字符集和字符编码方案的组合。

编码字符集 是抽象字符集合和整数集合之间的映射关系。US-ASCII、ISO 8859-1、JIS X 0201 和与 ISO 10646-1 相同的完整 Unicode 都是编码字符集示例。

字符编码方案 是编码字符集和八位组(八位字节)序列集合之间的映射关系。UTF-8、UCS-2、UTF-16、ISO 2022 和 EUC 是一些字符编码方案示例。编码方案通常与特定的编码字符集相关联;例如,UTF-8 只用来编码 Unicode。但是,一些方案与多个字符集相关联;例如,EUC 可用于编码各种亚洲字符集中的字符。

当编码字符集专门用于一个字符编码方案时,相应的 charset 通常使用字符集合命名;否则 charset 使用编码方案命名,很有可能使用它所支持的字符集的语言环境来命名。因此 US-ASCII 是 US-ASCII charset 名称,而 EUC-JP 是编码 JIS X 0201、JIS X 0208 和 JIS X 0212 字符集的 charset 名称。

Java 编程语言的本机字符编码方案是 UTF-16。因此 Java 平台的 charset 定义了 16 位 UTF-16 代码单元序列和字节序列之间的映射关系。

从以下版本开始:
1.4
另请参见:
CharsetDecoder, CharsetEncoder, CharsetProvider, Character

构造方法摘要
protected Charset(String canonicalName, String[] aliases)
          使用给定的规范名称和别名集合初始化新 charset。
 
方法摘要
 Set<String> aliases()
          返回包含此 charset 各个别名的集合。
static SortedMap<String,Charset> availableCharsets()
          构造从规范 charset 名称到 charset 对象的有序映射。
 boolean canEncode()
          通知此 charset 是否支持编码。
 int compareTo(Charset that)
          比较此 charset 与其他 charset。
abstract  boolean contains(Charset cs)
          通知此 charset 是否包含给定的 charset。
 CharBuffer decode(ByteBuffer bb)
          将此 charset 中的字节解码成 Unicode 字符的便捷方法。
static Charset defaultCharset()
          返回此 Java 虚拟机的默认 charset。
 String displayName()
          返回此 charset 用于默认语言环境的可读名称。
 String displayName(Locale locale)
          返回此 charset 用于给定语言环境的可读名称。
 ByteBuffer encode(CharBuffer cb)
          将此 charset 中的 Unicode 字符编码成字节的便捷方法。
 ByteBuffer encode(String str)
          将此 charset 中的字符串编码成字节的便捷方法。
 boolean equals(Object ob)
          通知此对象是否和其他对象相等。
static Charset forName(String charsetName)
          返回指定 charset 的 charset 对象。
 int hashCode()
          计算此 charset 的哈希码。
 boolean isRegistered()
          通知此 charset 是否已在 IANA Charset Registry 中注册。
static boolean isSupported(String charsetName)
          通知是否支持指定的 charset。
 String name()
          返回此 charset 的规范名称。
abstract  CharsetDecoder newDecoder()
          为此 charset 构造新的解码器。
abstract  CharsetEncoder newEncoder()
          为此 charset 构造新的编码器。
 String toString()
          返回描述此 charset 的字符串。
 
从类 java.lang.Object 继承的方法
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

构造方法详细信息

Charset

protected Charset(String canonicalName,
                  String[] aliases)
使用给定的规范名称和别名集合初始化新 charset。

参数:
canonicalName - 此 charset 的规范名称
aliases - 此 charset 别名的数组,如果没有别名则为 null
抛出:
IllegalCharsetNameException - 如果规范名称和任何一个别名非法
方法详细信息

isSupported

public static boolean isSupported(String charsetName)
通知是否支持指定的 charset。

参数:
charsetName - 请求的 charset 名称;可能是规范名称或别名
返回:
当且仅当当前 Java 虚拟机支持指定的 charset 时才返回 true
抛出:
IllegalCharsetNameException - 如果给定的 charset 名称是非法的
IllegalArgumentException - 如果给定的 charsetName 为 null

forName

public static Charset forName(String charsetName)
返回指定 charset 的 charset 对象。

参数:
charsetName - 请求的 charset 名称;可能是规范名称或别名
返回:
指定 charset 的 charset 对象
抛出:
IllegalCharsetNameException - 如果给定的 charset 名称是非法的
IllegalArgumentException - 如果给定的 charsetName 为 null
UnsupportedCharsetException - 如果此 Java 虚拟机的实例不支持指定 charset

availableCharsets

public static SortedMap<String,Charset> availableCharsets()
构造从规范 charset 名称到 charset 对象的有序映射。

此方法返回的映射对每个 charset 都有一项,当前 Java 虚拟机是支持这些 charset 的。如果所支持的两个或多个 charset 具有相同的规范名称,则结果映射中只包含它们中的一个;包含哪一个没有指定。

对此方法的调用,以及对结果映射的后续使用可能导致出现耗时的磁盘或网络 I/O 操作。为需要枚举所有可用 charset 的应用程序提供此方法,例如允许用户选择 charset。forName 方法不使用此方法,而是使用一种高效的增量查找算法。

如果新的 charset 提供者可供当前 Java 虚拟机动态使用,则此方法可能在不同的时间返回不同的结果。如果没有这种改变,则此方法返回的 charset 恰好是那些可以通过 forName 方法获取的 charset。

返回:
规范 charset 名称到 charset 对象的不可变的、大小写不敏感的映射

defaultCharset

public static Charset defaultCharset()
返回此 Java 虚拟机的默认 charset。

默认 charset 在虚拟机启动时决定,通常根据语言环境和底层操作系统的 charset 来确定。

返回:
默认 charset 的 charset 对象
从以下版本开始:
1.5

name

public final String name()
返回此 charset 的规范名称。

返回:
此 charset 的规范名称

aliases

public final Set<String> aliases()
返回包含此 charset 各个别名的集合。

返回:
此 charset 不可变的别名集合

displayName

public String displayName()
返回此 charset 用于默认语言环境的可读名称。

此方法的默认实现只返回此 charset 的规范名称。为了提供本地化的显示名称,此类的具体子类可以重写此方法。

返回:
默认语言环境下此 charset 的显示名称

isRegistered

public final boolean isRegistered()
通知此 charset 是否已在 IANA Charset Registry 中注册。

返回:
当且仅当此 charset 的实现程序知道此 charset 已向 IANA 注册时才返回 true

displayName

public String displayName(Locale locale)
返回此 charset 用于给定语言环境的可读名称。

此方法的默认实现只返回此 charset 的规范名称。为了提供本地化的显示名称,此类的具体子类可以重写此方法。

参数:
locale - 要为其获取显示名称的语言环境
返回:
给定语言环境下此 charset 的显示名称

contains

public abstract boolean contains(Charset cs)
通知此 charset 是否包含给定的 charset。

当且仅当在 charset D 中可表示的每个字符,在字符集 C 中也是可表示的时,才能说 C 包含 D。如果存在这种关系,就能保证可在 D 进行编码的所有字符串不用执行任何替换就可在 C 中进行编码。

C 包含 D 不表示 C 中以特定字节序列可表示的每个字符在 D 中也以相同的字节序列表示,尽管有时是这种情况。

每个 charset 包含其自身。

此方法计算近似的包含关系:如果返回 true,则已知给定的 charset 包含在此 charset 中;但是如果返回 false,则不一定说明给定的 charset 不包含在此 charset 中。

返回:
如果给定的 charset 包含在此 charset 中,则返回 true

newDecoder

public abstract CharsetDecoder newDecoder()
为此 charset 构造新的解码器。

返回:
此 charset 的新解码器

newEncoder

public abstract CharsetEncoder newEncoder()
为此 charset 构造新的编码器。

返回:
此 charset 的新编码器
抛出:
UnsupportedOperationException - 如果此 charset 不支持编码

canEncode

public boolean canEncode()
通知此 charset 是否支持编码。

几乎所有的 charset 都支持编码。常见的例外是专用的自动检测 charset,它的解码器通过检查输入字节序列,就能够确定正在使用多个可能编码方案中的哪一个。此类 charset 不支持编码是由于无法确定输出时应该使用哪种编码。此类 charset 的实现应该重写此方法以返回 false

返回:
当且仅当此 charset 支持编码时才返回 true

decode

public final CharBuffer decode(ByteBuffer bb)
将此 charset 中的字节解码成 Unicode 字符的便捷方法。

在 charset cs 上调用此方法,会返回和下面表达式相同的结果

 cs.newDecoder() .onMalformedInput(CodingErrorAction.REPLACE) .onUnmappableCharacter(CodingErrorAction.REPLACE) .decode(bb); 
除此之外它可能更为高效,因为它能在两次连续的调用之间缓存解码器。

此方法总是用此 charset 的默认替换 byte 数组替换错误输入和不可映射的字符序列。为了检测此种序列,可直接使用 CharsetDecoder.decode(java.nio.ByteBuffer) 方法。

参数:
bb - 要解码的 byte 缓冲区
返回:
包含已解码字符的 char 缓冲区

encode

public final ByteBuffer encode(CharBuffer cb)
将此 charset 中的 Unicode 字符编码成字节的便捷方法。

在 charset cs 上调用此方法,会返回和下面表达式相同的结果

 cs.newEncoder() .onMalformedInput(CodingErrorAction.REPLACE) .onUnmappableCharacter(CodingErrorAction.REPLACE) .encode(bb); 
除此之外它可能更为高效,因为它能在两次连续的调用之间缓存编码器。

此方法总是用此 charset 的默认替换字符串替换错误输入和不可映射的字符序列。为了检测此种序列,可直接使用 CharsetEncoder.encode(java.nio.CharBuffer) 方法。

参数:
cb - 要编码的 char 缓冲区
返回:
包含已编码字符的 byte 缓冲区

encode

public final ByteBuffer encode(String str)
将此 charset 中的字符串编码成字节的便捷方法。

在 charset cs 上调用此方法,会返回和下面表达式相同的结果

 cs.encode(CharBuffer.wrap(s)); 

参数:
str - 要编码的字符串
返回:
包含已编码字符的 byte 缓冲区

compareTo

public final int compareTo(Charset that)
比较此 charset 与其他 charset。

charset 根据它们的规范名称排序,而不考虑大小写。

指定者:
接口 Comparable<Charset> 中的 compareTo
参数:
that - 和此 charset 进行比较的 charset
返回:
如果此 charset 小于、等于或大于指定的 charset,则分别返回负整数、零或正整数

hashCode

public final int hashCode()
计算此 charset 的哈希码。

覆盖:
Object 中的 hashCode
返回:
整数哈希码
另请参见:
Object.equals(java.lang.Object), Hashtable

equals

public final boolean equals(Object ob)
通知此对象是否和其他对象相等。

当且仅当两个 charset 具有相同的规范名称时它们才相等。一个 charset 从来不和任何其他类型的对象相等。

覆盖:
Object 中的 equals
参数:
ob - 要与之比较的引用对象。
返回:
当且仅当此 charset 等于给定对象时才返回 true
另请参见:
Object.hashCode(), Hashtable

toString

public final String toString()
返回描述此 charset 的字符串。

覆盖:
Object 中的 toString
返回:
描述此 charset 的字符串