net.sf.jsonunicode

Class JsonIo

java.lang.Object

net.sf.jsonunicode.JsonIo

public final class JsonIo
extends Object

Methods for detecting JSON document encodings.

To open a stream to write JSON, use:

 OutputStream out = new FileOutputStream(file);
 Closeable res = out;
 try {
   Writer writer = JsonIo.newJsonWriter(out);
   res = writer;
   // write JSON
 } finally {
   res.close();
 }
 

To open a stream to read JSON, use:

 InputStream in = new FileInputStream(file);
 Closeable res = in;
 try {
   Reader reader = JsonIo.newJsonReader(in);
   res = reader;
   // read JSON
 } finally {
   res.close();
 }
 

This type does a best-guess detection of the encoding of a JSON data source by inspecting the first four bytes as described in RFC 4627.

Note: byte-order-marks are not supported; UTF-32 is not a standard Java encoding and may no be supported by the runtime.

Streams are intollerant of malformed Unicode data by default.

See Also:

JsonCharsets

Method Summary

Methods

Modifier and Type	Method and Description
static Charset	detectJsonEncoding(InputStream in) Detects the character encoding of the given JSON data stream.
static Writer	newCompactJsonWriter(OutputStream out) As newCompactJsonWriter(OutputStream, int, CodingErrorAction) with CodingErrorAction.REPORT and a default buffer size.
static Writer	newCompactJsonWriter(OutputStream out, int bufferSize) As newCompactJsonWriter(OutputStream, int, CodingErrorAction) with CodingErrorAction.REPORT.
static Writer	newCompactJsonWriter(OutputStream out, int bufferSize, CodingErrorAction errorHandling) A writer that chooses between UTF-8 and UTF-16 by buffering a certain amount of output and measuring how compact it will be when encoded using either of those encodings.
static Reader	newJsonReader(InputStream in) As newJsonReader(InputStream, CodingErrorAction) with a default of CodingErrorAction.REPORT.
static Reader	newJsonReader(InputStream in, CodingErrorAction errorHandling) Detects the JSON encoding and decorates the input with the appropriate Reader.
static Writer	newJsonWriter(OutputStream out) As newJsonWriter(OutputStream, CodingErrorAction) with CodingErrorAction.REPORT.
static Writer	newJsonWriter(OutputStream out, CodingErrorAction errorHandling) Creates a UTF-8 writer.

Methods inherited from class java.lang.Object

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

Method Detail

newJsonReader

public static Reader newJsonReader(InputStream in,
                   CodingErrorAction errorHandling)
                            throws IOException,
                                   UnsupportedCharsetException

Detects the JSON encoding and decorates the input with the appropriate Reader.

Parameters:

in - a JSON source

errorHandling - how to handle malformed character data

Returns:

the character decoder

Throws:

IOException - on error

UnsupportedCharsetException - UTF-32 is unsupported on Sun Java 5

newJsonReader

public static Reader newJsonReader(InputStream in)
                            throws IOException,
                                   UnsupportedCharsetException

As newJsonReader(InputStream, CodingErrorAction) with a default of CodingErrorAction.REPORT.

Throws:

IOException

UnsupportedCharsetException

detectJsonEncoding

public static Charset detectJsonEncoding(InputStream in)
                                  throws IOException,
                                         UnsupportedCharsetException

Detects the character encoding of the given JSON data stream.

The stream must return true when InputStream.markSupported() is called.

Parameters:

in - a stream that supports mark

Returns:

the detected encoding

Throws:

IOException - on error

UnsupportedCharsetException - UTF-32 is unsupported on Sun Java 5

See Also:

JsonCharsets

newJsonWriter

public static Writer newJsonWriter(OutputStream out,
                   CodingErrorAction errorHandling)
                            throws IOException

Creates a UTF-8 writer. Convenience method; UTF-8 is the default encoding for JSON.

Parameters:

out - the JSON target

errorHandling - the action on malformed data

Returns:

the encoder

Throws:

IOException - on IO error

newJsonWriter

public static Writer newJsonWriter(OutputStream out)
                            throws IOException

As newJsonWriter(OutputStream, CodingErrorAction) with CodingErrorAction.REPORT.

Throws:

IOException

newCompactJsonWriter

public static Writer newCompactJsonWriter(OutputStream out)

As newCompactJsonWriter(OutputStream, int, CodingErrorAction) with CodingErrorAction.REPORT and a default buffer size.

newCompactJsonWriter

public static Writer newCompactJsonWriter(OutputStream out,
                          int bufferSize)

As newCompactJsonWriter(OutputStream, int, CodingErrorAction) with CodingErrorAction.REPORT.

newCompactJsonWriter

public static Writer newCompactJsonWriter(OutputStream out,
                          int bufferSize,
                          CodingErrorAction errorHandling)

A writer that chooses between UTF-8 and UTF-16 by buffering a certain amount of output and measuring how compact it will be when encoded using either of those encodings.

Note: this method is only useful for certain ranges of Unicode data (e.g. a high proportion of Japanese natural language data.) Clients that assume JSON is UTF-8 may fail when faced with the results. The compression may be redundant when combined with over-the-wire compression methods (e.g. GZIP.)

If in doubt, use newJsonWriter(OutputStream) instead.

Calling Writer.flush() will cause the measuring phase to finish and an encoding to be chosen if this has not happened already.

Parameters:

out - the data target

bufferSize - the maximum size of the in-memory buffer

errorHandling - how to react to malformed data

Returns:

the encoder