- java.lang.Object
-
- java.nio.charset.CharsetEncoder
-
public abstract class CharsetEncoder extends Object
一种引擎,可以将一系列十六位Unicode字符转换为特定字符集中的字节序列。输入字符序列被提供在字符缓冲器或一系列这样的缓冲器中。 输出字节序列被写入一个字节缓冲区或一系列这样的缓冲区。 通过进行以下的方法调用顺序,以下简称为编码操作 ,应始终使用编码器:
通过
reset
方法复位编码器,除非以前没有使用过;调用
encode
方法零次或更多次,只要附加输入可用,通过false
为endOfInput
参数填充输入缓冲区并在调用之间刷新输出缓冲区;最后一次调用
encode
方法,通过true
查询endOfInput
参数; 接着调用
flush
方法,使编码器可以将任何内部状态刷新到输出缓冲区。
encode
方法的每次调用都将从输入缓冲区编码尽可能多的字符,将生成的字节写入输出缓冲区。 当需要更多输入时,当输出缓冲区中没有足够的空间或发生编码错误时,encode
方法返回。 在每种情况下,返回一个CoderResult
对象来描述终止的原因。 调用者可以检查此对象并填写输入缓冲区,刷新输出缓冲区,或尝试从编码错误中恢复,并重试。有两种一般类型的编码错误。 如果输入字符序列不是合法的16位Unicode序列,那么输入被认为是格式错误的 。 如果输入字符序列是合法的,但不能映射到给定字符集中的有效字节序列,则会遇到不可映射的字符 。
如何处理编码错误取决于为该类型的错误所请求的操作,这由
CodingErrorAction
类的实例描述。 可能的错误动作是将错误的输入, report的错误输入, report通过返回的CoderResult
对象给调用者的错误,或replace错误的输入与替换字节数组的当前值。 最初将替换设置为编码器的默认替换,通常(但不总是)初始值为{
(byte)'?'
}
; 其值可以通过replaceWith
方法更改。错误输入和不可映射字符错误的默认操作为report 。 畸形输入错误动作可以通过
onMalformedInput
方法更改; 可以通过onUnmappableCharacter
方法更改不可映射的字符动作。该类旨在处理编码过程的许多细节,包括执行错误操作。 特定字符集的编码器是该类的具体子类,仅需实现封装基本编码循环的抽象
encodeLoop
方法。 另外,维护内部状态的子类应该覆盖implFlush
和implReset
方法。此类的实例不能安全地被多个并发线程使用。
- 从以下版本开始:
- 1.4
- 另请参见:
-
ByteBuffer
,CharBuffer
,Charset
,CharsetDecoder
-
-
构造方法摘要
构造方法 Modifier Constructor 描述 protected
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)
初始化新的编码器。protected
CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)
初始化新的编码器。
-
方法摘要
所有方法 接口方法 抽象方法 具体的方法 Modifier and Type 方法 描述 float
averageBytesPerChar()
返回为每个输入字符产生的平均字节数。boolean
canEncode(char c)
告知编码器是否可以对给定的字符进行编码。boolean
canEncode(CharSequence cs)
告知编码器是否可以对给定的字符序列进行编码。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()
复位该编码器,清除任何字符集特定的内部状态。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()
返回此编码器当前对不可映射字符错误的操作。
-
-
-
构造方法详细信息
-
CharsetEncoder
protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar, byte[] replacement)
初始化新的编码器。 新的编码器将具有给定的每字节字节和替换值。- 参数
-
cs
- 创建此编码器的字符集 -
averageBytesPerChar
- 一个正值,表示将为每个输入字符产生的预期字节数 -
maxBytesPerChar
- 一个正值,表示将为每个输入字符产生的最大字节数 -
replacement
- 初次更换; 一定不能是null
,必须有非零长度,不能超过maxBytesPerChar,而且必须是legal - 异常
-
IllegalArgumentException
- 如果参数的前提条件不成立
-
CharsetEncoder
protected CharsetEncoder(Charset cs, float averageBytesPerChar, float maxBytesPerChar)
初始化新的编码器。 新的编码器将具有给定的每字节字节值,并且其替换将是字节阵列{
(byte)'?'
}
。- 参数
-
cs
- 创建此编码器的字符集 -
averageBytesPerChar
- 一个正值,表示将为每个输入字符产生的预期字节数 -
maxBytesPerChar
- 一个正值,表示将为每个输入字符产生的最大字节数 - 异常
-
IllegalArgumentException
- 如果参数的前提条件不成立
-
-
方法详细信息
-
charset
public final 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)
告知给定的字节数组是否是该编码器的合法替换值。如果并且只有在编码器的字符集中是一个合法的字节序列,则替换是合法的; 也就是说,必须可以将替换解码为一个或多个16位Unicode字符。
该方法的默认实现不是很有效; 通常应该覆盖以提高性能。
- 参数
-
repl
- 要测试的字节数组 - 结果
-
true
如果并且只有给定的字节数组是该编码器的合法替换值
-
malformedInputAction
public CodingErrorAction malformedInputAction()
返回此编码器当前针对格式错误输入错误的操作。- 结果
-
目前的格式错误的输入动作,从不
null
-
onMalformedInput
public final CharsetEncoder onMalformedInput(CodingErrorAction newAction)
更改编码器对格式错误输入错误的操作。此方法调用
implOnMalformedInput
方法,传递新操作。- 参数
-
newAction
- 新动作 不能是null
- 结果
- 这个编码器
- 异常
-
IllegalArgumentException
- 如果参数的前提条件不成立
-
implOnMalformedInput
protected void implOnMalformedInput(CodingErrorAction newAction)
报告对该编码器的格式错误的输入操作的更改。这种方法的默认实现什么都不做。 应该通过需要通知错误输入操作更改的编码器来覆盖此方法。
- 参数
-
newAction
- 新的动作
-
unmappableCharacterAction
public CodingErrorAction unmappableCharacterAction()
返回此编码器当前对不可映射字符错误的操作。- 结果
-
当前的不可映射角色动作,从不
null
-
onUnmappableCharacter
public final CharsetEncoder onUnmappableCharacter(CodingErrorAction newAction)
更改此编码器对不可映射字符错误的操作。此方法调用
implOnUnmappableCharacter
方法,传递新操作。- 参数
-
newAction
- 新动作; 不能是null
- 结果
- 这个编码器
- 异常
-
IllegalArgumentException
- 如果参数的前提条件不成立
-
implOnUnmappableCharacter
protected void implOnUnmappableCharacter(CodingErrorAction newAction)
报告此编码器的不可映射角色动作的更改。这种方法的默认实现什么都不做。 该方法应该被需要通知不可映射角色动作的更改的编码器覆盖。
- 参数
-
newAction
- 新的动作
-
averageBytesPerChar
public final float averageBytesPerChar()
返回为每个输入字符产生的平均字节数。 该启发式值可用于估计给定输入序列所需的输出缓冲区的大小。- 结果
- 每个字符输入的平均字节数
-
maxBytesPerChar
public final float maxBytesPerChar()
返回为每个输入字符产生的最大字节数。 该值可用于计算给定输入序列所需的输出缓冲区的最坏情况大小。- 结果
- 每个字符输入的最大字节数
-
encode
public final CoderResult encode(CharBuffer in, ByteBuffer out, boolean endOfInput)
从给定的输入缓冲区编码尽可能多的字符,将结果写入给定的输出缓冲区。缓冲区从其当前位置开始读取并写入。 在大多数
in.remaining()
个字符将被读取和最out.remaining()
个字节将被写入。 缓冲区的位置将被提前以反映读取的字符和写入的字节,但是它们的标记和限制将不被修改。除了从输入缓冲区读取字符并将字节写入输出缓冲区之外,此方法返回一个
CoderResult
对象来描述其终止原因:CoderResult.UNDERFLOW
表示尽可能多的输入缓冲器已被编码。 如果没有进一步的输入,那么调用者可以进入encoding operation的下一步 。 否则,此方法应再次调用再输入。CoderResult.OVERFLOW
指示输出缓冲区中没有足够的空间来编码任何更多的字符。 应该再次使用具有remaining字节的输出缓冲区来调用此方法。 这通常通过从输出缓冲器中排出任何编码字节来完成。A malformed-input结果表示已检测到格式错误的输入错误。 格式错误的字符从输入缓冲区(可能增加)的位置开始; 可以通过调用结果对象的
length
方法来确定格式错误的字符数。 这种情况只适用于当malformed action这个编码器是CodingErrorAction.REPORT
; 否则,将根据要求忽略或替换格式错误的输入。一个unmappable-character结果表示已检测到不匹配的字符错误。 编码不可映射字符的字符从输入缓冲区(可能增加)的位置开始; 可以通过调用结果对象的
length
方法来确定这样的字符的数量。 这种情况只适用于当unmappable action这个编码器是CodingErrorAction.REPORT
; 否则不可映射的字符将被忽略或替换,根据要求。
endOfInput
参数建议您使用此方法来确定调用者是否可以提供超出给定输入缓冲区中的输入值。 如果有可能提供额外的输入,那么调用者应该通过此参数的false
; 如果不可能提供进一步的输入,则调用者应通过true
。 这并不是错误的,事实上它是很常见的,通过false
在一个调用,后来发现没有进一步的输入实际上是可用的。 然而,至关重要的是,以一系列调用方式最终调用此方法总是通过true
以便任何剩余的未编码的输入将被视为格式错误。该方法通过调用
encodeLoop
方法,解释其结果,处理错误条件以及根据需要重新启动它。- 参数
-
in
- 输入字符缓冲区 -
out
- 输出字节缓冲区 -
endOfInput
-true
如果并且仅当调用者不能提供超出给定缓冲区中的额外输入字符 - 结果
- 描述终止原因的编码器结果对象
- 异常
-
IllegalStateException
-如果编码操作已在进行中和之前的步骤是一个调用既不的reset
方法,也没有这种方法具有的值的false
为endOfInput
参数,也不该方法具有的值的true
为endOfInput
参数而是返回值,表示不完整的编码操作 -
CoderMalfunctionError
- 如果对encodeLoop方法的调用抛出了一个意外的异常
-
flush
public final CoderResult flush(ByteBuffer out)
刷新编码器。一些编码器保持内部状态,并且可能需要在读取整个输入序列后将一些最后的字节写入输出缓冲区。
任何额外的输出从其当前位置开始写入输出缓冲区。 将写入最多
out.remaining()
个字节。 缓冲区的位置将适当地提前,但其标记和限制将不会被修改。如果此方法成功完成,则返回
CoderResult.UNDERFLOW
。 如果输出缓冲区空间不足,则返回CoderResult.OVERFLOW
。 如果发生这种情况,则必须再次调用此方法,输出缓冲区有更多的空间,以完成当前的encoding operation 。如果此编码器已被刷新,则调用此方法将无效。
此方法调用
implFlush
方法来执行实际的刷新操作。- 参数
-
out
- 输出字节缓冲区 - 结果
-
编码结果对象,
CoderResult.UNDERFLOW
或CoderResult.OVERFLOW
- 异常
-
IllegalStateException
-如果当前编码操作的前一步骤既不是的调用flush
方法也不三个参数的encode
具有的值的方法true
为endOfInput
参数
-
implFlush
protected CoderResult implFlush(ByteBuffer out)
刷新编码器。这个方法的默认实现什么都不做,总是返回
CoderResult.UNDERFLOW
。 一旦整个输入序列被读取,编码器就可能需要将最后一个字节写入输出缓冲区来覆盖此方法。- 参数
-
out
- 输出字节缓冲区 - 结果
-
编码结果对象,
CoderResult.UNDERFLOW
或CoderResult.OVERFLOW
-
reset
public final CharsetEncoder reset()
复位该编码器,清除任何内部状态。该方法重置与字符集无关的状态,并且还调用
implReset
方法以执行任何特定于字符集的重置操作。- 结果
- 这个编码器
-
implReset
protected void implReset()
复位该编码器,清除任何字符集特定的内部状态。这种方法的默认实现什么都不做。 该方法应由维护内部状态的编码器覆盖。
-
encodeLoop
protected abstract CoderResult encodeLoop(CharBuffer in, ByteBuffer out)
将一个或多个字符编码为一个或多个字节。该方法封装了基本的编码循环,编码尽可能多的字符,直到其输出不足,在输出缓冲区中用完,或遇到编码错误。 该方法由
encode
方法调用,它处理结果解释和错误恢复。缓冲区从其当前位置开始读取并写入。 最多读取
in.remaining()
个字符,最多写入out.remaining()
个字节。 缓冲区的位置将被提前以反映读取的字符和写入的字节,但是它们的标记和限制将不被修改。该方法返回一个
CoderResult
对象来描述其终止原因,方式与encode
方法相同。 该方法的大多数实现将通过返回一个适当的结果对象来解决编码错误,由encode
方法进行解释。 优化的实现可能会检查相关的错误操作,并实现该操作本身。该方法的实现可以通过返回
CoderResult.UNDERFLOW
来执行任意的前瞻,直到它接收足够的输入。- 参数
-
in
- 输入字符缓冲区 -
out
- 输出字节缓冲区 - 结果
- 描述终止原因的编码器结果对象
-
encode
public final ByteBuffer encode(CharBuffer in) throws CharacterCodingException
便捷方法,将单个输入字符缓冲区的剩余内容编码到新分配的字节缓冲区中。该方法实现整个encoding operation ; 也就是说,它复位该编码器,然后对给定字符缓冲区中的字符进行编码,最后刷新该编码器。 因此,如果编码操作已经在进行中,则不能调用此方法。
- 参数
-
in
- 输入字符缓冲区 - 结果
- 包含编码操作结果的新分配的字节缓冲器。 缓冲区的位置将为零,其限制将跟随写入的最后一个字节。
- 异常
-
IllegalStateException
- 如果编码操作已在进行中 -
MalformedInputException
- 如果从输入缓冲区当前位置开始的字符序列不是合法的16位Unicode序列,并且当前格式错误的输入操作是CodingErrorAction.REPORT
-
UnmappableCharacterException
- 如果从输入缓冲区的当前位置开始的字符序列不能映射到等效的字节序列,而当前的不可 映像字符操作是CodingErrorAction.REPORT
-
CharacterCodingException
-
canEncode
public boolean canEncode(char c)
告知编码器是否可以对给定的字符进行编码。如果给定的字符是代理字符,此方法返回
false
; 这样的字符只有当它们是由高替代物和低替代品组成的成员的对象时才能被解释。 可以使用canEncode(CharSequence)
方法来测试字符序列是否可以被编码。该方法可能会修改该编码器的状态; 因此,如果一个encoding operation已经在进行中,则不应该调用它。
该方法的默认实现不是很有效; 通常应该覆盖以提高性能。
- 参数
-
c
- 给定的字符 - 结果
-
true
如果并且只有这个编码器可以对给定的字符进行编码 - 异常
-
IllegalStateException
- 如果编码操作已在进行中
-
canEncode
public boolean canEncode(CharSequence cs)
告知编码器是否可以对给定的字符序列进行编码。如果该方法对于特定字符序列返回
false
,则可以通过执行完整的encoding operation获得关于为什么不编码序列的更多信息。该方法可能会修改该编码器的状态; 因此,如果编码操作已经在进行中,则不应该调用它。
该方法的默认实现不是很有效; 通常应该覆盖以提高性能。
- 参数
-
cs
- 给定的字符序列 - 结果
-
true
如果并且仅当该编码器可以编码给定字符而不抛出任何异常并且不执行任何替换 - 异常
-
IllegalStateException
- 如果编码操作已在进行中
-
-