org.mdiutil.io.charset

Class CharsetDetector

java.lang.Object

org.mdiutil.io.charset.CharsetDetector

public class CharsetDetector
extends Object

CharsetDetector provides a facility for detecting the charset or encoding of character data in an unknown format. The input data can either be from an input stream or an array of bytes. The result of the detection operation is a list of possibly matching charsets, or, for simple use, you can just ask for a Java Reader that will will work over the input data.

Character set detection is at best an imprecise operation. The detection process will attempt to identify the charset that best matches the characteristics of the byte data, but the process is partly statistical in nature, and the results can not be guaranteed to always be correct.

For best accuracy in charset detection, the input data should be primarily in a single language, and a minimum of a few hundred bytes worth of plain text in the language are needed. The detection process will attempt to ignore html or xml style markup that could otherwise obscure the content.

Constructor Summary

Constructors

Constructor and Description
CharsetDetector() Constructor.

Method Summary

Modifier and Type	Method and Description
CharsetMatch	detect() Return the charset that best matches the supplied input data.
CharsetMatch[]	detectAll() Return an array of all charsets that appear to be plausible matches with the input data.
static CharsetMatch	detectCharsetMatch(File file) Return the guessed encoding of a file.
static CharsetMatch	detectCharsetMatch(URL url) Return the guessed encoding of an URL.
boolean	enableInputFilter(boolean filter) Enable filtering of input text.
static String[]	getAllDetectableCharsets() Get the names of all charsets supported by CharsetDetector class.
CharsetMatch	getCharsetMatch(File file) Return the guessed encoding of a file.
CharsetMatch	getCharsetMatch(URL url) Return the guessed encoding of an URL.
Reader	getReader(InputStream in, String declaredEncoding) Autodetect the charset of an inputStream, and return a Java Reader to access the converted input data.
String	getString(byte[] in, String declaredEncoding) Autodetect the charset of an inputStream, and return a String containing the converted input data.
boolean	inputFilterEnabled() Test whether or not input filtering is enabled.
CharsetDetector	setDeclaredEncoding(String encoding) Set the declared encoding for charset detection.
CharsetDetector	setText(byte[] in) Set the input text (byte) data whose charset is to be detected.
CharsetDetector	setText(InputStream in) Set the input text (byte) data whose charset is to be detected.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CharsetDetector

public CharsetDetector()

Constructor.

Method Detail

getCharsetMatch

public CharsetMatch getCharsetMatch(URL url)
                             throws IOException

Return the guessed encoding of an URL.

Parameters:

url - the URL

Returns:

the guessed CharsetMatch of the URL

Throws:

IOException

getCharsetMatch

public CharsetMatch getCharsetMatch(File file)
                             throws IOException

Return the guessed encoding of a file.

Parameters:

file - the file

Returns:

the guessed CharsetMatch of the file

Throws:

IOException

detectCharsetMatch

public static CharsetMatch detectCharsetMatch(File file)
                                       throws IOException

Return the guessed encoding of a file.

Parameters:

file - the file

Returns:

the guessed CharsetMatch of the file

Throws:

IOException

detectCharsetMatch

public static CharsetMatch detectCharsetMatch(URL url)
                                       throws IOException

Return the guessed encoding of an URL.

Parameters:

url - the URL

Returns:

the guessed CharsetMatch of the URL

Throws:

IOException

setDeclaredEncoding

public CharsetDetector setDeclaredEncoding(String encoding)

Set the declared encoding for charset detection. The declared encoding of an input text is an encoding obtained from an http header or xml declaration or similar source that can be provided as additional information to the charset detector. A match between a declared encoding and a possible detected encoding will raise the quality of that detected encoding by a small delta, and will also appear as a "reason" for the match.

A declared encoding that is incompatible with the input data being analyzed will not be added to the list of possible encodings.

Parameters:

encoding - The declared encoding

Returns:

this

setText

public CharsetDetector setText(byte[] in)

Set the input text (byte) data whose charset is to be detected.

Parameters:

in - the input text of unknown encoding

Returns:

This CharsetDetector

setText

public CharsetDetector setText(InputStream in)
                        throws IOException

Set the input text (byte) data whose charset is to be detected.

The input stream that supplies the character data must have markSupported() == true; the charset detection process will read a small amount of data, then return the stream to its original position via the InputStream.reset() operation. The exact amount that will be read depends on the characteristics of the data itself.

Parameters:

in - the input text of unknown encoding

Returns:

This CharsetDetector

Throws:

IOException

detect

public CharsetMatch detect()

Return the charset that best matches the supplied input data. Note though, that because the detection only looks at the start of the input data, there is a possibility that the returned charset will fail to handle the full set of input data.

Raise an exception if

• no charset appears to match the data.
• no input text has been provided

Returns:

a CharsetMatch object representing the best matching charset, or null if there are no matches.

detectAll

public CharsetMatch[] detectAll()

Return an array of all charsets that appear to be plausible matches with the input data. The array is ordered with the best quality match first.

Raise an exception if

• no charsets appear to match the input data.
• no input text has been provided

Returns:

An array of CharsetMatch objects representing possibly matching charsets.

getReader

public Reader getReader(InputStream in,
                        String declaredEncoding)

Autodetect the charset of an inputStream, and return a Java Reader to access the converted input data.

This is a convenience method that is equivalent to this.setDeclaredEncoding(declaredEncoding).setText(in).detect().getReader();

For the input stream that supplies the character data, markSupported() must be true; the charset detection will read a small amount of data, then return the stream to its original position via the InputStream.reset() operation. The exact amount that will be read depends on the characteristics of the data itself.

Raise an exception if no charsets appear to match the input data.

Parameters:

in - The source of the byte data in the unknown charset.

declaredEncoding - A declared encoding for the data, if available, or null or an empty string if none is available.

Returns:

the reader

getString

public String getString(byte[] in,
                        String declaredEncoding)

Autodetect the charset of an inputStream, and return a String containing the converted input data.

This is a convenience method that is equivalent to this.setDeclaredEncoding(declaredEncoding).setText(in).detect().getString();

Raise an exception if no charsets appear to match the input data.

Parameters:

in - The source of the byte data in the unknown charset.

declaredEncoding - A declared encoding for the data, if available, or null or an empty string if none is available.

Returns:

the string

getAllDetectableCharsets

public static String[] getAllDetectableCharsets()

Get the names of all charsets supported by CharsetDetector class.

Note: Multiple different charset encodings in a same family may use a single shared name in this implementation. For example, this method returns an array including "ISO-8859-1" (ISO Latin 1), but not including "windows-1252" (Windows Latin 1). However, actual detection result could be "windows-1252" when the input data matches Latin 1 code points with any points only available in "windows-1252".

Returns:

an array of the names of all charsets supported by CharsetDetector class.

inputFilterEnabled

public boolean inputFilterEnabled()

Test whether or not input filtering is enabled.

Returns:

true if input text will be filtered.

See Also:

enableInputFilter(boolean)

enableInputFilter

public boolean enableInputFilter(boolean filter)

Enable filtering of input text. If filtering is enabled, text within angle brackets ("<" and ">") will be removed before detection.

Parameters:

filter - true to enable input text filtering.

Returns:

The previous setting