Java CharConversionException Class
Last modified: April 16, 2025
The java.io.CharConversionException is an exception thrown when a
character conversion error occurs. It signals problems during character encoding
or decoding operations. This is a checked exception that extends IOException.
CharConversionException typically occurs when reading or writing
text data with incompatible character encodings. It indicates malformed input
data or unsupported character mappings. Applications should handle this exception
gracefully.
CharConversionException Class Overview
CharConversionException extends IOException and
represents character conversion failures. It has two constructors - a default
one and one accepting an error message. No additional methods are provided.
public class CharConversionException extends IOException {
public CharConversionException();
public CharConversionException(String s);
}
The code above shows the simple structure of CharConversionException.
The first constructor creates an exception without a message. The second allows
specifying a custom error message describing the conversion failure.
Basic CharConversionException Example
This example demonstrates a simple case where CharConversionException
might be thrown. We'll attempt to read a file with an unsupported encoding.
import java.io.*;
public class Main {
public static void main(String[] args) {
try {
// Attempt to read with unsupported encoding
InputStreamReader reader = new InputStreamReader(
new FileInputStream("data.txt"), "UNSUPPORTED_ENCODING");
int data;
while ((data = reader.read()) != -1) {
System.out.print((char) data);
}
reader.close();
} catch (CharConversionException e) {
System.err.println("Character conversion failed: " + e.getMessage());
} catch (IOException e) {
e.printStackTrace();
}
}
}
This example attempts to read a file using an unsupported character encoding.
The InputStreamReader throws CharConversionException
when it cannot perform the requested character conversion. Always handle this
exception when working with character encodings.
Handling Malformed Input
CharConversionException often occurs when input data contains
invalid character sequences. This example shows how to handle such cases when
processing text data.
import java.io.*;
public class Main {
public static void main(String[] args) {
// Create a byte array with invalid UTF-8 sequence
byte[] invalidData = {(byte)0xC0, (byte)0x80}; // Invalid UTF-8
try {
InputStreamReader reader = new InputStreamReader(
new ByteArrayInputStream(invalidData), "UTF-8");
int data;
while ((data = reader.read()) != -1) {
System.out.print((char) data);
}
reader.close();
} catch (CharConversionException e) {
System.err.println("Invalid character sequence: " + e.getMessage());
} catch (IOException e) {
e.printStackTrace();
}
}
}
This example demonstrates handling invalid UTF-8 byte sequences. The byte array contains an invalid UTF-8 sequence that triggers the exception. The program catches the exception and provides an appropriate error message.
Custom Character Conversion
When implementing custom character conversion logic, you might need to throw
CharConversionException. This example shows how to do this properly.
import java.io.*;
public class Main {
static String convertToUpperCase(String input) throws CharConversionException {
if (input == null) {
throw new CharConversionException("Input cannot be null");
}
// Simulate conversion failure for demonstration
if (input.contains("�")) {
throw new CharConversionException("Invalid replacement character found");
}
return input.toUpperCase();
}
public static void main(String[] args) {
try {
String result = convertToUpperCase("hello world�");
System.out.println(result);
} catch (CharConversionException e) {
System.err.println("Conversion error: " + e.getMessage());
}
}
}
This example shows a custom method that throws CharConversionException
when encountering invalid input. The method checks for null input and replacement
characters. This demonstrates proper exception usage in custom conversion logic.
Working with Different Encodings
This example shows how different character encodings can lead to
CharConversionException when reading files with mismatched encodings.
import java.io.*;
public class Main {
public static void main(String[] args) {
String filename = "data_utf16.txt";
try {
// Wrongly assuming UTF-8 for a UTF-16 file
BufferedReader reader = new BufferedReader(
new InputStreamReader(
new FileInputStream(filename), "UTF-8"));
String line;
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
reader.close();
} catch (CharConversionException e) {
System.err.println("Encoding mismatch detected: " + e.getMessage());
System.err.println("Try specifying UTF-16 encoding instead");
} catch (IOException e) {
e.printStackTrace();
}
}
}
This example attempts to read a UTF-16 encoded file using UTF-8 encoding. The
mismatch causes CharConversionException. The catch block suggests
trying the correct encoding. Always verify file encodings before processing.
Recovering from Conversion Errors
This example demonstrates a strategy for recovering from character conversion errors by falling back to a different encoding when the primary one fails.
import java.io.*;
public class Main {
public static void main(String[] args) {
String filename = "unknown_encoding.txt";
String[] encodings = {"UTF-8", "ISO-8859-1", "UTF-16"};
for (String encoding : encodings) {
try {
BufferedReader reader = new BufferedReader(
new InputStreamReader(
new FileInputStream(filename), encoding));
System.out.println("Success with encoding: " + encoding);
String line;
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
reader.close();
break; // Exit loop if successful
} catch (CharConversionException e) {
System.err.println("Failed with " + encoding +
": " + e.getMessage());
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
This example tries multiple encodings until finding one that works. It starts with UTF-8, then falls back to ISO-8859-1, and finally UTF-16. This approach can handle files with unknown encodings gracefully.
Preventing Conversion Errors
This example shows best practices for preventing CharConversionException
by validating input and specifying correct encodings upfront.
import java.io.*;
import java.nio.charset.Charset;
public class Main {
public static void main(String[] args) {
String filename = "important_data.txt";
try {
// Check if encoding is supported
if (!Charset.isSupported("UTF-8")) {
throw new CharConversionException("UTF-8 not supported");
}
// Get file encoding from metadata if available
String detectedEncoding = detectFileEncoding(filename);
BufferedReader reader = new BufferedReader(
new InputStreamReader(
new FileInputStream(filename), detectedEncoding));
// Process file contents
String line;
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
reader.close();
} catch (CharConversionException e) {
System.err.println("Encoding problem: " + e.getMessage());
} catch (IOException e) {
e.printStackTrace();
}
}
private static String detectFileEncoding(String filename) {
// In real implementation, use actual detection logic
return "UTF-8"; // Default assumption
}
}
This example demonstrates preventive measures against conversion errors. It checks
encoding support before use and attempts to detect the file's actual encoding.
Such practices reduce the likelihood of CharConversionException.
Source
Java CharConversionException Class Documentation
In this article, we've covered the essential aspects of the Java CharConversionException class. Understanding these concepts is crucial for working with text data and character encodings in Java applications.
Author
List all Java tutorials.