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

CKTIS / Java

CodingErrorAction: comunicar ou substituir entradas inválidas

CodingErrorAction controla a forma como um descodificador ou codificador de conjuntos de caracteres trata erros de codificação. REPORT comunica o erro ao código chamador, enquanto REPLACE substitui o fragmento defeituoso pelo valor configurado e prossegue o processamento. As políticas para entradas malformadas e caracteres não representáveis são configuradas separadamente.

Versão: Java SE 21; repository runtime, production runtime not attested

Sintaxe

coder.onMalformedInput(CodingErrorAction.REPORT);
coder.onUnmappableCharacter(CodingErrorAction.REPLACE);

CodingErrorAction, de java.nio.charset, define políticas de tratamento de erros para CharsetDecoder e CharsetEncoder. É uma classe com constantes que representam as ações disponíveis, não uma declaração enum. Uma entrada malformada viola as regras de codificação; um erro de carácter não representável significa que uma sequência válida não pode ser representada na saída. Configure estas políticas separadamente através de onMalformedInput(...) e onUnmappableCharacter(...).

CodingErrorAction.REPORT comunica um erro: os métodos de processamento incremental de buffers devolvem um CoderResult adequado, enquanto os métodos com um único argumento decode(...) e encode(...) lançam uma subclasse adequada de CharacterCodingException. Os novos descodificadores e codificadores usam REPORT por predefinição para ambas as categorias de erro. Isto não significa que todas as APIs de conversão de texto utilizem a mesma política.

CodingErrorAction.REPLACE ignora a entrada com erro, acrescenta o valor de substituição e continua. Um descodificador insere texto; um codificador insere bytes. Altere esse valor com replaceWith(...). Isto implica perda de informação, não repara o original. Escolha REPORT quando for necessário detetar erros e REPLACE apenas quando a substituição for aceitável. O exemplo para Java SE 21 compara ambas as ações com um byte UTF-8 inválido e define explicitamente ? para tornar o resultado legível.

Exemplos

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

public class Main {
    public static void main(String[] args) throws CharacterCodingException {
        byte[] input = {(byte) 0xFF, 0x41};

        var strict = StandardCharsets.UTF_8.newDecoder()
                .onMalformedInput(CodingErrorAction.REPORT);
        try {
            strict.decode(ByteBuffer.wrap(input));
        } catch (CharacterCodingException e) {
            System.out.println("REPORT: " + e.getClass().getSimpleName());
        }

        var tolerant = StandardCharsets.UTF_8.newDecoder()
                .onMalformedInput(CodingErrorAction.REPLACE)
                .replaceWith("?");
        System.out.println("REPLACE: " + tolerant.decode(ByteBuffer.wrap(input)));
    }
}

Resultado

REPORT: MalformedInputException
REPLACE: ?A

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