©
このドキュメントでは、 php中国語ネットマニュアル リリース
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
java.lang.Object java.nio.charset.CharsetEncoder
public abstract class CharsetEncoder
能够把 16 位 Unicode 字符序列转换成特定 charset 中字节序列的引擎。
输入字符序列由字符缓冲区或一系列这样的缓冲区提供。输出字节序列写入字节缓冲区或一系列这样的缓冲区。应该始终通过下面的方法调用序列使用编码器,下文称为编码操作:
通过 只要有其他的输入数据就应零次或多次调用 最后时刻调用一次 调用 有两种常规编码错误类型。如果输入字符序列不是合法的 16 位 Unicode 序列,那么就认为输入是错误的。如果输入字符序列是合法的,但不能映射为给定 charset 中的有效字节序列,那么就出现了不可映射的字符。
如何处理编码错误取决于为该错误类型所请求的操作,在 对于错误输入和不可映射的字符错误的默认操作是
此类设计用来处理编码过程中的许多细节问题,包括错误操作的实现。一个特定 charset 的编码器是此类的具体子类,它只需要实现抽象的 此类的实例用于多个并发线程是不安全的。
每次调用 reset
方法重置编码器,除非以前未使用过; encode
,为 endOfInput 参数传递 false,在调用之间填充输入缓冲区并刷新输出缓冲区。 encode
方法,为 endOfInput 参数传递 true;然后 flush
方法,这样编码器能够将任何内部状态刷新到输出缓冲区。 encode
方法将编码尽可能多的输入缓冲区中的字符,将得到的字节写入输出缓冲区。当需要更多的输入时、输出缓冲区没有足够的空间或出现编码错误时,encode
方法返回。在每种情况下都返回用于描述终止原因的 CoderResult
对象。调用者可根据相应的状况检查此对象并填充输入缓冲区、刷新输出缓冲区或尝试从编码错误中恢复,并再次进行尝试。
CodingErrorAction
类的实例中描述了该类型的错误。可能的错误操作是
忽略
错误的输入、通过返回的
CoderResult
对象将错误
报告
给调用者,或者用当前的替换 byte 数组值
替换
错误的输入。
该替换值初始设置为编码器的默认替换值,这个值通常(但并非总是)具有初始值 { (byte)'?' };
可通过
replaceWith
方法更改此值。
报告
它们。可通过
onMalformedInput
方法更改针对错误输入的错误操作;可通过 onUnmappableCharacter
方法更改不可映射的字符错误的操作。
encodeLoop
方法,这个方法封装了基本的编码循环。另外,维护内部状态的子类应该重写 implFlush
和 implReset
方法。
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)
通知给定的 byte 数组是否为此编码器的合法替换值。 |
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 |
构造方法详细信息 |
---|
protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)
averageBytesPerChar
- 一个正的 float 值,指示为每个输入字符所生成的字节数maxBytesPerChar
- 一个正的 float 值,指示为每个输入字符所生成的最大字节数replacement
- 初始替换值;一定不能为 null、必须具有非零长度、必须小于 maxBytesPerChar,并且必须为
legal
IllegalArgumentException
- 如果参数有关的前提不成立protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)
averageBytesPerChar
- 一个正的 float 值,指示为每个输入字符所生成的字节数maxBytesPerChar
- 一个正的 float 值,指示为每个输入字符所生成的最大字节数
IllegalArgumentException
- 如果参数有关的前提不成立方法详细信息 |
---|
public final Charset charset()
public final byte[] replacement()
public final CharsetEncoder replaceWith(byte[] newReplacement)
此方法调用 implReplaceWith
方法,检查新的替换值是可接受的后,传递该新替换值。
newReplacement
- 新的替换值;一定不能为 null、必须具有非零长度、必须小于 maxBytesPerChar
所返回的值,并且必须为
legal
IllegalArgumentException
- 如果参数有关的前提不成立protected void implReplaceWith(byte[] newReplacement)
此方法的默认实现不执行任何操作。需要通知替换值更改的编码器应该重写此方法。
newReplacement
- public boolean isLegalReplacement(byte[] repl)
当且仅当替换值是此编码器的 charset 中合法的字节序列时才是合法的;也就是说,能够把替换值解码成一个或多个 16 位 Unicode 字符。
此方法的默认实现效率不是很高;为了提高性能通常应该重写它。
repl
- 要被测试的 byte 数组
public CodingErrorAction malformedInputAction()
public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)
此方法调用 implOnMalformedInput
方法,传递新的操作。
newAction
- 新的操作;一定不能为 null
IllegalArgumentException
- 如果参数有关的前提不成立protected void implOnMalformedInput(CodingErrorAction newAction)
此方法的默认实现不执行任何操作。需要通知错误输入操作更改的编码器应该重写此方法。
public CodingErrorAction unmappableCharacterAction()
public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)
此方法调用 implOnUnmappableCharacter
方法,传递新的操作。
newAction
- 新的操作;一定不能为 null
IllegalArgumentException
- 如果参数有关的前提不成立protected void implOnUnmappableCharacter(CodingErrorAction newAction)
此方法的默认实现不执行任何操作。需要通知不可映射的字符操作更改的编码器应该重写此方法。
public final float averageBytesPerChar()
public final float maxBytesPerChar()
public final CoderResult encode(CharBuffer in, ByteBuffer out, boolean endOfInput)
应该从各缓冲区的当前位置开始进行读取和写入。最多将读取 in.remaining()
个字符,最多将写入 out.remaining()
个字节。前移缓冲区的位置,以反映字符读取和写入字节,但是其标记和界限将无法修改。
除了从输入缓冲区读取字符和向输出缓冲区写入字节,此方法还返回一个 CoderResult
对象来描述它终止的原因:
CoderResult.UNDERFLOW
指示已编码尽可能多的输入缓冲区。如果没有进一步的输入,则调用者可以进行到编码操作的下一个步骤。否则,应该使用进一步的输入再次调用此方法。
CoderResult.OVERFLOW
指示该输出缓冲区中没有足够空间来编码任何更多字符。应该使用具有更多剩余字节的输出缓冲区再次调用此方法。这通常是通过排空输出缓冲区的所有编码字节来完成的。
CoderResult#malformedForLength
malformed-input 结果指示已检测到错误输入错误。错误的字符起始于输入缓冲区(可能向前增加)的位置;错误字符数可以通过调用结果对象的
length
方法来确定。这种情况只适用于此编码器的
错误输入的动作
是
CodingErrorAction.REPORT
的情况下;否则将像请求的那样忽略或替换错误的输入。
CoderResult#unmappableForLength
unmappable-character 结果指示已检测到不可映射的字符错误。编码不可映射的字符的字符起始于输入缓冲区(可能向前增加)的位置;这种字符的数目可以通过调用结果对象的
length
方法来确定。这种情况只适用于此编码器的
不可映射的字符的动作
是
CodingErrorAction.REPORT
的情况下;否则将像请求的那样忽略或替换不可映射的字符。
endOfInput 参数通知此方法除了给定输入缓冲区包含的内容,调用者是否能提供更多的输入。如果可能提供其他的输入,则调用者应该为此参数传递 false;如果不能提供更多的输入,则调用者应该传递 true。实际上在一次调用中传递 false,但后来发现实际上没有更多的输入可用是相当普遍的,这不是错误。但关键是,在此方法的一系列调用中,最后一次调用总是传递 true,这样所有剩余的未编码输入都作为错误输入处理。
此方法通过调用 encodeLoop
方法、解释它的结果、处理错误情况并重新调用(如有必要)来完成其工作。
in
- 输入字符缓冲区out
- 输出字节缓冲区endOfInput
- 当且仅当调用者除了给定缓冲区中的内容外不提供其他输入字符时才为 true
IllegalStateException
- 如果编码操作已在进行中并且前面的步骤不是调用 reset
方法,也不是为 endOfInput 参数使用 false 来调用此方法,也不是为 endOfInput 参数使用 true 来调用此方法,而是一个指示未完成编码操作的返回值
CoderMalfunctionError
- 如果对 encodeLoop 方法的调用抛出不可预料的异常public final CoderResult flush(ByteBuffer out)
一些编码器维护内部状态,并且一旦读取完所有的输入序列后,可能需要向输出缓冲区写入一些最终字节。
任何其他输出写入输出缓冲区时都要从缓冲区的当前位置开始。最多将写入 out.remaining()
个字节。缓冲区的位置要相应地向前移动,但是其标记和界限将无法修改。
如果此方法成功完成,则它返回 CoderResult.UNDERFLOW
。如果输出缓冲区没有足够的空间,则它返回 CoderResult.OVERFLOW
。如果发生这种情况,那么为了完成当前的编码操作,必须使用具有更多空间的输出缓冲区再次调用此方法。
如果此编码器已刷新,则调用此方法无效。
此方法调用 implFlush
方法来执行实际的刷新操作。
out
- 输出字节缓冲区
CoderResult.UNDERFLOW
或 CoderResult.OVERFLOW
IllegalStateException
- 如果当前编码操作的前一步既不是调用 flush
方法,也不是为 endOfInput 参数使用 true 来调用三参数的 encode
方法protected CoderResult implFlush(ByteBuffer out)
此方法的默认实现不执行任何操作,并且始终返回 CoderResult.UNDERFLOW
。对于那些一旦读取完整个的输入序列后,可能需要向输出缓冲区写入最终字节的编码器而言,应该重写此方法。
out
- 输出字节缓冲区
CoderResult.UNDERFLOW
或 CoderResult.OVERFLOW
public final CharsetEncoder reset()
此方法重置与 charset 无关的状态,并且为了执行所有特定于 charset 的重置操作,还会调用 implReset
方法。
protected void implReset()
此方法的默认实现不执行任何操作。维护内部状态的编码器应该重写此方法。
protected abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out)
此方法封装了基本的编码循环,在用完输入、用完输出缓冲区的空间或遇到编码错误之前编码尽可能多的字符。此方法由 encode
方法调用,encode
方法处理结果解释和错误恢复。
应该从各缓冲区的当前位置开始进行读取和写入。最多将读取 in.remaining()
个字符,最多将写入 out.remaining()
个字节。前移缓冲区的位置,以反映字符读取和写入字节,但是其标记和界限将无法修改。
此方法返回一个 CoderResult
对象描述它终止的原因,其方式和 encode
方法的相同。大多数此方法的实现处理编码错误的方式是由 encode
方法返回一个用来解释错误的相应结果对象。最优的实现可能是检查相关的错误操作并且自己实现该操作。
此方法的一种实现可能在接收到足够的输入之前,通过返回 CoderResult.UNDERFLOW
来执行任意的 lookahead。
in
- 输入字符缓冲区out
- 输出字节缓冲区
public final ByteBuffer encode(CharBuffer in) throws CharacterCodingException
此方法实现完整的编码操作;也就是说,它重置编码器,然后编码给定字符缓冲区中的字符,最后刷新此编码器。因此如果正在进行编码操作,则不应该调用此方法。
in
- 输入字符缓冲区
IllegalStateException
- 如果已经进行编码操作
MalformedInputException
- 如果从输入缓冲区当前位置开始的字符序列不是合法的 16 位 Unicode 序列,并且当前的错误输入操作是 CodingErrorAction.REPORT
UnmappableCharacterException
- 如果从输入缓冲区当前位置开始的字符序列不能映射到等同的字节序列,并且当前的不可映射的字符操作是 CodingErrorAction.REPORT
CharacterCodingException
public boolean canEncode(char c)
如果给定的字符是代理项字符,则此方法返回 false;只有当这些字符是高代理项后跟低代理项所组成的代理项对的成员时,才能对其进行解释。可使用 canEncode(CharSequence)
方法来检测是否能够编码某个字符序列。
此方法可以修改此编码器的状态;因此如果正在进行编码操作,则不应该调用此方法。
此方法的默认实现效率不是很高;为了提高性能通常应该重写它。
IllegalStateException
- 如果已经进行编码操作public boolean canEncode(CharSequence cs)
如果此方法对特定的字符序列返回 false,则通过执行完整编码操作可获得有关无法编码序列的更多信息。
此方法可以修改此编码器的状态;因此如果正在进行编码操作,则不应该调用此方法。
此方法的默认实现效率不是很高;为了提高性能通常应该重写它。
IllegalStateException
- 如果已经进行编码操作
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。