CKTIS / Java
Transcode windows-1250 to UTF-8 and handle decoding errors
Convert windows-1250 bytes to UTF-8 by decoding them into Unicode characters and then encoding those characters again. Choose how the decoder handles each kind of error.
Version: Java SE 21
Syntax
Java SE 21 — java.nio.charset (buffers in java.nio)
Charset.forName(String charsetName) -> Charset
Charset.forName(String charsetName, Charset fallback) -> Charset
charset.newDecoder() -> CharsetDecoder
charset.newEncoder() -> CharsetEncoder
decoder.onMalformedInput(CodingErrorAction action) -> CharsetDecoder
decoder.onUnmappableCharacter(CodingErrorAction action) -> CharsetDecoder
decoder.decode(ByteBuffer in) -> CharBuffer; throws CharacterCodingException
decoder.decode(ByteBuffer in, CharBuffer out, boolean endOfInput) -> CoderResult
encoder.encode(CharBuffer in) -> ByteBuffer; throws CharacterCodingException
encoder.encode(CharBuffer in, ByteBuffer out, boolean endOfInput) -> CoderResultIn Java SE 21, Charset.forName(String) in java.nio.charset looks up a charset by its canonical name or an alias. It throws IllegalCharsetNameException for an illegal name and UnsupportedCharsetException for an unsupported one. The forName(String, Charset) overload, available since Java 18, returns the fallback (which can be null) for either case. Both overloads reject a null name with IllegalArgumentException.
The Charset.forName/newDecoder/newEncoder methods cover lookup and conversion setup: call newDecoder() on the source charset to read bytes as Unicode characters, then newEncoder() on the target charset to write new bytes. Oracle JDK 21 supports windows-1250, but Java SE does not require it; StandardCharsets.UTF_8 is guaranteed. newEncoder() throws UnsupportedOperationException if the charset cannot encode. Decoders and encoders are stateful and not thread-safe.
With CharsetDecoder.onMalformedInput/onUnmappableCharacter/decode, you configure two independent error actions before decoding. onMalformedInput(action) handles byte sequences that violate the charset's rules; onUnmappableCharacter(action) handles structurally valid sequences with no Unicode mapping. Both setters modify and return the same decoder. REPORT is the default and signals the error; REPLACE inserts replacement text (initially U+FFFD); IGNORE drops the offending input. Replacement and omission lose information. Use REPORT when errors must not pass silently, but do not treat it as proof that you picked the right source charset. The Charset.decode(...) shortcut replaces both kinds of errors.
The one-argument CharsetDecoder.decode(ByteBuffer) and CharsetEncoder.encode(CharBuffer) read the remaining input and return a new CharBuffer or ByteBuffer, respectively. With REPORT, a coding error throws MalformedInputException or UnmappableCharacterException, both subclasses of CharacterCodingException. To process chunks, use the overload with an output buffer and an endOfInput flag: check CoderResult, retain unconsumed input, and call flush(...) after the final chunk. Do not call the one-argument overload while that operation is in progress.
Examples
import java.nio.ByteBuffer;
import java.nio.CharBuffer;
import java.nio.charset.Charset;
import java.nio.charset.CharsetDecoder;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.MalformedInputException;
import java.nio.charset.StandardCharsets;
import java.util.HexFormat;
public class CharsetDemo {
private static CharsetDecoder decoder(Charset charset, CodingErrorAction action) {
return charset.newDecoder()
.onMalformedInput(action)
.onUnmappableCharacter(action);
}
public static void main(String[] args) throws java.nio.charset.CharacterCodingException {
Charset source = Charset.forName("windows-1250");
Charset utf8 = StandardCharsets.UTF_8;
byte[] legacy = {(byte) 0xA5};
CharBuffer text = decoder(source, CodingErrorAction.REPORT)
.decode(ByteBuffer.wrap(legacy));
ByteBuffer encoded = utf8.newEncoder().encode(text);
byte[] output = new byte[encoded.remaining()];
encoded.get(output);
System.out.println("windows-1250 -> UTF-8: "
+ HexFormat.ofDelimiter(" ").withUpperCase().formatHex(output));
byte[] truncatedUtf8 = {(byte) 0xC3};
try {
decoder(utf8, CodingErrorAction.REPORT).decode(ByteBuffer.wrap(truncatedUtf8));
throw new AssertionError("Expected malformed UTF-8");
} catch (MalformedInputException expected) {
System.out.println("REPORT: MalformedInputException");
}
CharBuffer repaired = decoder(utf8, CodingErrorAction.REPLACE)
.decode(ByteBuffer.wrap(truncatedUtf8));
System.out.printf("REPLACE: U+%04X%n", Character.codePointAt(repaired, 0));
}
}Result
windows-1250 -> UTF-8: C4 84 REPORT: MalformedInputException REPLACE: U+FFFD
The windows-1250 byte `A5` represents `U+0104`, which UTF-8 writes as `C4 84`. In a separate test, a lone `C3` starts an incomplete UTF-8 sequence: `REPORT` throws, while `REPLACE` produces `U+FFFD`. Hex output avoids relying on the terminal's Unicode rendering.
Related lessons
- Java · Lesson 51 · Advanced · Version: 2