Java java.nio.charset 类 CharsetEncoder（JDK5）

所有类

概述  软件包   类  使用  树  已过时  索引  帮助
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

java.nio.charset
类 CharsetEncoder

java.lang.Object
  java.nio.charset.CharsetEncoder

---

public abstract class CharsetEncoder
   
   
   
   
   
extends Object
   
   
   
   
   

能够把 16 位 Unicode 字符序列转换成特定 charset 中字节序列的引擎。

输入字符序列由字符缓冲区或一系列这样的缓冲区提供。输出字节序列写入字节缓冲区或一系列这样的缓冲区。应该始终通过下面的方法调用序列使用编码器，下文称为编码操作：

1. 通过 reset 方法重置编码器，除非以前未使用过；

2. 只要有其他的输入数据就应零次或多次调用 encode，为 endOfInput 参数传递 false，在调用之间填充输入缓冲区并刷新输出缓冲区。

3. 最后时刻调用一次 encode 方法，为 endOfInput 参数传递 true；然后

4. 调用 flush 方法，这样编码器能够将任何内部状态刷新到输出缓冲区。

每次调用 encode 方法将编码尽可能多的输入缓冲区中的字符，将得到的字节写入输出缓冲区。当需要更多的输入时、输出缓冲区没有足够的空间或出现编码错误时，encode 方法返回。在每种情况下都返回用于描述终止原因的 CoderResult 对象。调用者可根据相应的状况检查此对象并填充输入缓冲区、刷新输出缓冲区或尝试从编码错误中恢复，并再次进行尝试。

有两种常规编码错误类型。如果输入字符序列不是合法的 16 位 Unicode 序列，那么就认为输入是错误的。如果输入字符序列是合法的，但不能映射为给定 charset 中的有效字节序列，那么就出现了不可映射的字符。

如何处理编码错误取决于为该错误类型所请求的操作，在 CodingErrorAction 类的实例中描述了该类型的错误。可能的错误操作是忽略错误的输入、通过返回的 CoderResult 对象将错误报告给调用者，或者用当前的替换字节数组值替换错误的输入。 该替换值初始设置为编码器的默认替换值，这个值通常（但并非总是）具有初始值 { (byte)'?' }； 可通过 replaceWith 方法更改此值。

对于错误输入和不可映射的字符错误的默认操作是报告它们。可通过 onMalformedInput 方法更改针对错误输入的错误操作；可通过 onUnmappableCharacter 方法更改不可映射的字符错误的操作。

此类设计用来处理编码过程中的许多细节问题，包括错误操作的实现。一个特定 charset 的编码器是此类的具体子类，它只需要实现抽象的 encodeLoop 方法，这个方法封装了基本的编码循环。另外，维护内部状态的子类应该重写 flush 和 reset 方法。

此类的实例用于多个并发线程是不安全的。

从以下版本开始：

1.4

另请参见：

ByteBuffer, CharBuffer, Charset, CharsetDecoder

---

构造方法摘要
protected	CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)           初始化新的编码器。
protected	CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)           初始化新的编码器。

 

方法摘要
float	averageBytesPerChar()           返回为每个输入字符生成的平均字节数。
boolean	canEncode(char c)           通知此编码器是否能够编码给定的字符。
boolean	canEncode(CharSequence cs)           通过此编码器是否能够编码给定的字符序列。
Charset	charset()           返回创建此编码器的 charset。
ByteBuffer	encode(CharBuffer in)           把单个输入字符缓冲区的剩余内容编码到新分配的字节缓冲区的便捷方法。
CoderResult	encode(CharBuffer in, ByteBuffer out, boolean endOfInput)           从给定输入缓冲区中编码尽可能多的字符，把结果写入给定的输出缓冲区。
protected abstract  CoderResult	encodeLoop(CharBuffer in, ByteBuffer out)           将一个或多个字符编码为一个或多个字节。
CoderResult	flush(ByteBuffer out)           刷新此编码器。
protected  CoderResult	implFlush(ByteBuffer out)           刷新此编码器。
protected  void	implOnMalformedInput(CodingErrorAction newAction)           报告此编码器的错误输入操作的更改。
protected  void	implOnUnmappableCharacter(CodingErrorAction newAction)           报告此编码器的不可映射的字符操作的更改。
protected  void	implReplaceWith(byte[] newReplacement)           报告此编码器替换值的更改。
protected  void	implReset()           重置此编码器，清除所有特定于 charset 的内部状态。
boolean	isLegalReplacement(byte[] repl)           通知给定的字节数组是否为此编码器的合法替换值。
CodingErrorAction	malformedInputAction()           返回此编码器对错误输入错误的当前操作。
float	maxBytesPerChar()           返回为每个输入字符生成的最大字节数。
CharsetEncoder	onMalformedInput(CodingErrorAction newAction)           更改此编码器对错误输入错误的操作。
CharsetEncoder	onUnmappableCharacter(CodingErrorAction newAction)           更改此编码器对不可映射的字符错误的操作。
byte[]	replacement()           返回此编码器的替换值。
CharsetEncoder	replaceWith(byte[] newReplacement)           更改此编码器的替换值。
CharsetEncoder	reset()           重置此编码器，清除所有内部状态。
CodingErrorAction	unmappableCharacterAction()           返回此编码器对不可映射的字符错误的当前操作。

 

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

构造方法详细信息

CharsetEncoder

protected CharsetEncoder(Charset cs,
                         float averageBytesPerChar,
                         float maxBytesPerChar,
                         byte[] replacement)

初始化新的编码器。新编码器具有给定的每字符多少个字节 (chars-per-byte) 值和替换值。

参数：

averageBytesPerChar - 一个正的 float 值，指示为每个输入字符所生成的字节数

maxBytesPerChar - 一个正的 float 值，指示为每个输入字符所生成的最大字节数

replacement - 初始替换值；一定不能为 null、必须具有非零长度、必须小于 maxBytesPerChar，并且必须为 legal

抛出：

IllegalArgumentException - 如果参数有关的前提不成立

---

CharsetEncoder

protected CharsetEncoder(Charset cs,
                         float averageBytesPerChar,
                         float maxBytesPerChar)

初始化新的编码器。新编码器具有给定的每字符多少个字节值，它的替换值为字节数组 { (byte)'?' }。

参数：

averageBytesPerChar - 一个正的 float 值，指示为每个输入字符所生成的字节数

maxBytesPerChar - 一个正的 float 值，指示为每个输入字符所生成的最大字节数

抛出：

IllegalArgumentException - 如果参数有关的前提不成立

方法详细信息

charset

public final Charset charset()

返回创建此编码器的 charset。

返回：

此编码器的 charset

---

replacement

public final byte[] replacement()

返回此编码器的替换值。

返回：

此编码器的当前替换值，它永远不能为 null，也不能为空

---

replaceWith

public final CharsetEncoder replaceWith(byte[] newReplacement)

更改此编码器的替换值。

此方法调用 implReplaceWith 方法，检查新的替换值是可接受的后，传递该新替换值。

参数：

newReplacement - 新的替换值；一定不能为 null、必须具有非零长度、必须小于 maxBytesPerChar 所返回的值，并且必须为 legal

返回：

此编码器

抛出：

IllegalArgumentException - 如果参数有关的前提不成立

---

implReplaceWith

protected void implReplaceWith(byte[] newReplacement)

报告此编码器替换值的更改。

此方法的默认实现不执行任何操作。需要通知替换值更改的编码器应该重写此方法。

参数：

newReplacement -

---

isLegalReplacement

public boolean isLegalReplacement(byte[] repl)

通知给定的字节数组是否为此编码器的合法替换值。

当且仅当替换值是此编码器的 charset 中合法的字节序列时才是合法的；也就是说，能够把替换值解码成一个或多个 16 位 Unicode 字符。

此方法的默认实现效率不是很高；为了提高性能通常应该重写它。

参数：

repl - 要被测试的字节数组

返回：

当且仅当给定的字节数组是此编码器的合法替换值时才返回 true

---

malformedInputAction

public CodingErrorAction malformedInputAction()

返回此编码器对错误输入错误的当前操作。

返回：

当前的错误输入操作，它永远不能为 null