模块  java.base
软件包  java.nio.charset

Class CharsetEncoder

  • public abstract class CharsetEncoderextends Object
    一种引擎，可以将16位Unicode字符序列转换为特定字符集中的字节序列。

    输入字符序列在字符缓冲区或一系列这样的缓冲区中提供。 输出字节序列被写入字节缓冲区或一系列此类缓冲区。 应始终通过进行以下方法调用序列来使用编码器，以下称为编码操作 ：

    1. 通过reset方法重置编码器，除非之前没有使用过;

    2. 只要有额外的输入可用，就调用encode方法零次或多次，为endOfInput参数传递false并填充输入缓冲区并在调用之间刷新输出缓冲区;

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

    4. 调用flush方法，以便编码器可以将任何内部状态刷新到输出缓冲区。

    每次调用encode方法都会从输入缓冲区中编码尽可能多的字符，并将结果字节写入输出缓冲区。 当需要更多输入，输出缓冲区中没有足够空间或发生编码错误时， encode方法返回。 在每种情况下，返回CoderResult对象以描述终止的原因。 调用者可以检查此对象并填充输入缓冲区，刷新输出缓冲区，或尝试从编码错误中恢复（如果适用），然后重试。

    编码错误有两种常见类型。 如果输入字符序列不是合法的16位Unicode序列，则输入被视为格式错误 。 如果输入字符序列是合法的但无法映射到给定字符集中的有效字节序列，则会遇到不可映射的字符 。

    如何处理编码错误取决于为该类型的错误请求的操作，该操作由CodingErrorAction类的实例描述。 可能的错误操作是ignore错误输入， report通过返回的CoderResult对象向调用者发出错误，或replace错误输入与替换字节数组的当前值。 替换最初设置为编码器的默认替换，通常（但不总是）具有初始值{ (byte)'?' } ; 其值可以通过replaceWith方法更改。

    malformed -input和unmappable-character错误的默认操作是report 。 可以通过onMalformedInput方法更改格式错误的输入错误操作; 可以通过onUnmappableCharacter方法更改不可映射字符操作。

    此类旨在处理编码过程的许多细节，包括错误操作的实现。 特定字符集的编码器（该类的具体子类）只需要实现抽象encodeLoop方法，该方法封装了基本的编码循环。 另外，维护内部状态的子类应该覆盖implFlush和implReset方法。

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

    从以下版本开始：
    1.4
    另请参见：
    ByteBuffer ， CharBuffer ， Charset ， CharsetDecoder

    • 构造方法详细信息

      • 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

      • implOnMalformedInput

        protected void implOnMalformedInput​(CodingErrorAction newAction)
        报告对此编码器的格式错误输入操作的更改。

        此方法的默认实现不执行任何操作。 编码器应该覆盖此方法，该编码器需要通知对格式错误的输入操作进行更改。

        参数
        newAction - 新动作

      • unmappableCharacterAction

        public CodingErrorAction unmappableCharacterAction()
        返回此编码器对不可映射字符错误的当前操作。
        结果
        当前不可映射的字符操作，永远不会是 null

      • 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字节的输出缓冲区再次调用此方法。 这通常通过从输出缓冲区中排出任何编码字节来完成。

        • 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方法的调用，也不是 endOfInput参数的值为 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()
        重置此编码器，清除任何内部状态。

        此方法重置与charset无关的状态，并调用implReset方法以执行任何特定于charset的重置操作。

        结果
        这个编码器

      • 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 - 如果编码操作已在进行中