Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Java

CharsetDecoder — descodificar bytes com controlo de erros

CharsetDecoder converte bytes de um conjunto de caracteres selecionado em caracteres Unicode. Permite configurar separadamente o tratamento de sequências malformadas e não mapeáveis: comunicar erros, substituir a entrada ou ignorá-la.

Versão: Documentation target: Java SE 21; repository and production runtime versions are not attested.

Sintaxe

CharsetDecoder decoder = charset.newDecoder()
    .onMalformedInput(CodingErrorAction.REPORT)
    .onUnmappableCharacter(CodingErrorAction.REPORT);
CharBuffer text = decoder.decode(input);

java.nio.charset.CharsetDecoder converte bytes em caracteres Unicode; crie-o através de charset.newDecoder(). Esta entrada diz respeito a Java SE 21; as versões dos ambientes de execução do repositório e de produção não estão atestadas.

CharsetDecoder.onMalformedInput controla as sequências inválidas no conjunto de caracteres. CharsetDecoder.onUnmappableCharacter aplica-se a sequências válidas sem correspondência em caracteres Unicode. Ambos os métodos aceitam CodingErrorAction: REPORT comunica um erro, REPLACE substitui os dados errados e IGNORE descarta-os. Substituir e omitir implica perda de informação.

CharsetDecoder.decode(ByteBuffer) devolve um CharBuffer; com REPORT, os erros são lançados como exceções da família CharacterCodingException. A sobrecarga decode(ByteBuffer, CharBuffer, boolean) permite o processamento incremental e devolve um CoderResult que tem de ser tratado.

O exemplo utiliza 0xFF, um byte UTF-8 inválido. Primeiro comunica o erro e, em seguida, substitui o byte por ?. Isto demonstra uma entrada malformada, não uma sequência não mapeável; a segunda política continua definida como REPORT.

Exemplos

import java.nio.ByteBuffer;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.CharsetDecoder;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;

public class DecoderDemo {
    public static void main(String[] args) throws CharacterCodingException {
        byte[] bytes = {65, (byte) 0xFF, 66};
        CharsetDecoder decoder = StandardCharsets.UTF_8.newDecoder()
            .onMalformedInput(CodingErrorAction.REPORT)
            .onUnmappableCharacter(CodingErrorAction.REPORT);

        try {
            decoder.decode(ByteBuffer.wrap(bytes));
        } catch (CharacterCodingException ex) {
            System.out.println("REPORT: " + ex.getClass().getSimpleName());
        }

        decoder.reset();
        decoder.onMalformedInput(CodingErrorAction.REPLACE)
            .replaceWith("?");
        System.out.println("REPLACE: " + decoder.decode(ByteBuffer.wrap(bytes)));
    }
}

Resultado

REPORT: MalformedInputException
REPLACE: A?B

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes