com.fasterxml.jackson.jr.ob

Class JSON

java.lang.Object

com.fasterxml.jackson.jr.ob.JSON

All Implemented Interfaces:

Versioned

public class JSON
extends Object
implements Versioned

Main entry point for functionality for reading and writing JSON and configuring details of reading and writing.

Note that instances are fully immutable, and thereby thread-safe.

Note on source types: source to read is declared as Object but covers following types:

• InputStream
• Reader
• byte[]
• char[]
• String/CharSequence
• URL
• File

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	JSON.Builder Builder class that needs to be used for certain kind of "static" configuration (settings that can not vary on per-call basis for JSON), such as Extension registration.
static class	JSON.Feature Simple on/off (enabled/disabled) features for JSON; used for simple configuration aspects.

Field Summary

Fields

Modifier and Type	Field and Description
protected int	_features
protected JsonFactory	_jsonFactory Underlying JSON factory used for creating Streaming parsers and generators.
protected PrettyPrinter	_prettyPrinter
protected JSONReader	_reader Blueprint instance of the reader to use for reading JSON as simple Objects.
protected TreeCodec	_treeCodec Optional handler for TreeNode values: if defined, we can read and write TreeNode instances that codec supports.
protected ValueReaderLocator	_valueReaderLocator
protected ValueWriterLocator	_valueWriterLocator
protected JSONWriter	_writer Blueprint instance of the writer to use for writing JSON given simple Objects.
static int	CACHE_FLAGS
static JSON	std Singleton instance with standard, default configuration.

Constructor Summary

Constructors

Modifier	Constructor and Description
	JSON()
	JSON(JSON.Builder b) Constructor used when creating instance using JSON.Builder.
	JSON(JsonFactory jsonF)
protected	JSON(JSON base, int features, JsonFactory jsonF, TreeCodec trees, JSONReader r, JSONWriter w, PrettyPrinter pp)
protected	JSON(JSON base, ValueReaderLocator rloc, ValueWriterLocator wloc)

Method Summary

Modifier and Type	Method and Description
protected void	_close(Closeable cl)
protected <T> T	_closeWithError(Closeable cl, Exception e)
protected JsonGenerator	_config(JsonGenerator g)
protected JsonParser	_config(JsonParser p)
protected JSONReader	_defaultReader()
protected JSONWriter	_defaultWriter()
protected JsonParser	_initForReading(JsonParser p)
protected void	_noTreeCodec(String msg)
protected JsonParser	_parser(Object source)
protected JSONReader	_readerForOperation(JsonParser p)
protected <T> T	_throw(Exception e)
protected JSON	_with(int features) Internal mutant factory method used for constructing
protected JSON	_with(int features, JsonFactory jsonF, TreeCodec trees, JSONReader reader, JSONWriter writer, PrettyPrinter pp)
protected void	_writeAndClose(Object value, JsonGenerator g)
protected JSONWriter	_writerForOperation(JsonGenerator gen)
Object	anyFrom(Object source) Read method that will take given JSON Source (of one of supported types), read contents and map it to one of simple mappings (Map for JSON Objects, List for JSON Arrays, String for JSON Strings, null for JSON null, Boolean for JSON booleans and Number for JSON numbers.
ValueIterator<Object>	anySequenceFrom(Object source) Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as "Simple" type: Map, List, String, Number or Boolean.
Object[]	arrayFrom(Object source)
<T> T[]	arrayOfFrom(Class<T> type, Object source)
byte[]	asBytes(Object value)
ObjectCodec	asCodec() Convenience method for constructing an adapter that uses this instance as a ObjectCodec
String	asString(Object value)
<T> T	beanFrom(Class<T> type, Object source)
<T> ValueIterator<T>	beanSequenceFrom(Class<T> type, Object source) Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound to specific Bean (POJO) type.
static JSON.Builder	builder()
static JSON.Builder	builder(JsonFactory streamFactory)
JSONComposer<byte[]>	composeBytes()
<C extends Collection<Object>> CollectionComposer<?,C>	composeCollection(C collection)
CollectionComposer<?,List<Object>>	composeList()
MapComposer<?>	composeMap()
MapComposer<?>	composeMap(Map<String,Object> map)
JSONComposer<String>	composeString()
JSONComposer<OutputStream>	composeTo(File f)
JSONComposer<OutputStream>	composeTo(OutputStream out)
JSONComposer<OutputStream>	composeTo(Writer w)
JSONComposer<OutputStream>	composeUsing(JsonGenerator gen)
<T extends TreeNode> T	createArrayNode() Convenience method, equivalent to:
<T extends TreeNode> T	createObjectNode() Convenience method, equivalent to:
JsonParser	createParser(Object source) Factory method for opening a JsonParser to read content from one of following supported sources InputStream Reader byte[] char[] String/CharSequence URL File
JsonFactory	getStreamingFactory()
TreeCodec	getTreeCodec()
boolean	isEnabled(JSON.Feature f)
List<Object>	listFrom(Object source)
<T> List<T>	listOfFrom(Class<T> type, Object source)
Map<String,Object>	mapFrom(Object source)
<T> Map<String,T>	mapOfFrom(Class<T> type, Object source) Read method for reading a Map of type (usually POJO) values.
<T extends TreeNode> T	treeFrom(Object source) Method for reading content as a JSON Tree (of type that configured TreeCodec, see with(TreeCodec)) supports.
<T extends TreeNode> ValueIterator<T>	treeSequenceFrom(Object source) Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as JSON Trees(of type that configured TreeCodec, see with(TreeCodec)) supports.
Version	version()
JSON	with(CollectionBuilder b) Mutant factory for constructing an instance with specified CollectionBuilder, and returning new instance (or, if there would be no change, this instance).
JSON	with(JSON.Feature... features) Mutant factory for constructing an instance with specified features enabled.
JSON	with(JSON.Feature feature, boolean state) Mutant factory for constructing an instance with specified feature enabled or disabled (depending on state), and returning an instance with that setting; this may either be this instance (if feature already had specified state), or a newly constructed instance.
JSON	with(JsonFactory f) Deprecated. Since 2.11 should not try changing underlying stream factory but create a new instance if necessary: method will be removed from 3.0 at latest
JSON	with(JSONReader r) Deprecated. Since 2.11 should try using builder (see builder() and create properly configured instance
JSON	with(JSONWriter w) Deprecated. Since 2.11 should try using builder (see builder() and create properly configured instance
JSON	with(MapBuilder b) Mutant factory for constructing an instance with specified MapBuilder, and returning new instance (or, if there would be no change, this instance).
JSON	with(PrettyPrinter pp) Mutant factory for constructing an instance with specified PrettyPrinter, and returning new instance (or, if there would be no change, this instance).
JSON	with(ReaderWriterProvider rwp) Deprecated. Since 2.11 should register using JacksonJrExtension
JSON	with(TreeCodec c) Deprecated. Since 2.11 should try using builder (see builder() and create properly configured instance
JSON	without(JSON.Feature... features) Mutant factory for constructing an instance with specified features disabled.
void	write(Object value, File f)
void	write(Object value, JsonGenerator gen)
void	write(Object value, OutputStream out)
void	write(Object value, Writer w)

Methods inherited from class java.lang.Object

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

Field Detail

CACHE_FLAGS

public static final int CACHE_FLAGS

std

public static final JSON std

Singleton instance with standard, default configuration. May be used with direct references like:

   String json = JSON.std.asString(map);

_jsonFactory

protected final JsonFactory _jsonFactory

Underlying JSON factory used for creating Streaming parsers and generators.

_treeCodec

protected final TreeCodec _treeCodec

Optional handler for TreeNode values: if defined, we can read and write TreeNode instances that codec supports.

_valueReaderLocator

protected final ValueReaderLocator _valueReaderLocator

_valueWriterLocator

protected final ValueWriterLocator _valueWriterLocator

_reader

protected final JSONReader _reader

Blueprint instance of the reader to use for reading JSON as simple Objects.

_writer

protected final JSONWriter _writer

Blueprint instance of the writer to use for writing JSON given simple Objects.

_features

protected final int _features

_prettyPrinter

protected final PrettyPrinter _prettyPrinter

Constructor Detail

JSON

public JSON()

JSON

public JSON(JsonFactory jsonF)

JSON

public JSON(JSON.Builder b)

Constructor used when creating instance using JSON.Builder.

Parameters:

b - Builder that has configured settings to use.

Since:

2.11

JSON

protected JSON(JSON base,
               int features,
               JsonFactory jsonF,
               TreeCodec trees,
               JSONReader r,
               JSONWriter w,
               PrettyPrinter pp)

JSON

protected JSON(JSON base,
               ValueReaderLocator rloc,
               ValueWriterLocator wloc)

Method Detail

builder

public static JSON.Builder builder()

Since:

2.11

builder

public static JSON.Builder builder(JsonFactory streamFactory)

Since:

2.11

_defaultReader

protected JSONReader _defaultReader()

_defaultWriter

protected JSONWriter _defaultWriter()

asCodec

public ObjectCodec asCodec()

Convenience method for constructing an adapter that uses this instance as a ObjectCodec

Returns:

Wrapper over this object to adapt to ObjectCodec API

version

public Version version()

Specified by:

version in interface Versioned

with

public JSON with(PrettyPrinter pp)

Mutant factory for constructing an instance with specified PrettyPrinter, and returning new instance (or, if there would be no change, this instance).

Parameters:

pp - PrettyPrinter to use for pretty-printing output (of null to disable pretty-printing)

Returns:

New instance with specified PrettyPrinter (if not same as currently configured); this otherwise.

with

public JSON with(JSON.Feature feature,
                 boolean state)

Mutant factory for constructing an instance with specified feature enabled or disabled (depending on state), and returning an instance with that setting; this may either be this instance (if feature already had specified state), or a newly constructed instance.

with

public JSON with(JSON.Feature... features)

Mutant factory for constructing an instance with specified features enabled.

without

public JSON without(JSON.Feature... features)

Mutant factory for constructing an instance with specified features disabled.

_with

protected final JSON _with(int features)

Internal mutant factory method used for constructing

with

@Deprecated
public JSON with(JsonFactory f)

Deprecated. Since 2.11 should not try changing underlying stream factory but create a new instance if necessary: method will be removed from 3.0 at latest

Mutant factory method for constructing new instance with specified JsonFactory if different from currently configured one (if not, return this as-is)

Parameters:

f - Jackson core format factory to use for low-level decoding/encoding

Returns:

New instance with specified factory (if not same as currently configured); this otherwise.

with

@Deprecated
public JSON with(TreeCodec c)

Deprecated. Since 2.11 should try using builder (see builder() and create properly configured instance

Mutant factory for constructing an instance with specified TreeCodec, and returning new instance (or, if there would be no change, this instance).

Parameters:

c - Tree codec to use for reading/writing of tree representation

Returns:

New instance with specified codec (if not same as currently configured); this otherwise.

with

@Deprecated
public JSON with(JSONReader r)

Deprecated. Since 2.11 should try using builder (see builder() and create properly configured instance

Mutant factory for constructing an instance with specified JSONReader, and returning new instance (or, if there would be no change, this instance).

Parameters:

r - Customized JSONReader to use instead of standard one

Returns:

New instance with specified JSONReader (if not same as currently configured); this otherwise.

with

@Deprecated
public JSON with(JSONWriter w)

Deprecated. Since 2.11 should try using builder (see builder() and create properly configured instance

Mutant factory for constructing an instance with specified JSONWriter, and returning new instance (or, if there would be no change, this instance).

Parameters:

w - Customized JSONWriter to use instead of standard one

Returns:

New instance with specified JSONWriter (if not same as currently configured); this otherwise.

with

public JSON with(MapBuilder b)

Mutant factory for constructing an instance with specified MapBuilder, and returning new instance (or, if there would be no change, this instance).

with

public JSON with(CollectionBuilder b)

Mutant factory for constructing an instance with specified CollectionBuilder, and returning new instance (or, if there would be no change, this instance).

with

@Deprecated
public JSON with(ReaderWriterProvider rwp)

Deprecated. Since 2.11 should register using JacksonJrExtension

Mutant factory for constructing an instance with specified ReaderWriterProvider, and returning new instance (or, if there would be no change, this instance).

_with

protected JSON _with(int features,
                     JsonFactory jsonF,
                     TreeCodec trees,
                     JSONReader reader,
                     JSONWriter writer,
                     PrettyPrinter pp)

getTreeCodec

public TreeCodec getTreeCodec()

getStreamingFactory

public JsonFactory getStreamingFactory()

isEnabled

public final boolean isEnabled(JSON.Feature f)

createParser

public JsonParser createParser(Object source)
                        throws IOException,
                               JSONObjectException

Factory method for opening a JsonParser to read content from one of following supported sources

• InputStream
• Reader
• byte[]
• char[]
• String/CharSequence
• URL
• File

Rules regarding closing of the underlying source follow rules that JsonFactory has for its createParser method.

Throws:

IOException

JSONObjectException

Since:

2.10

asString

public String asString(Object value)
                throws IOException,
                       JSONObjectException

Throws:

IOException

JSONObjectException

asBytes

public byte[] asBytes(Object value)
               throws IOException,
                      JSONObjectException

Throws:

IOException

JSONObjectException

write

public void write(Object value,
                  JsonGenerator gen)
           throws IOException,
                  JSONObjectException

Throws:

IOException

JSONObjectException

write

public void write(Object value,
                  OutputStream out)
           throws IOException,
                  JSONObjectException

Throws:

IOException

JSONObjectException

write

public void write(Object value,
                  Writer w)
           throws IOException,
                  JSONObjectException

Throws:

IOException

JSONObjectException

write

public void write(Object value,
                  File f)
           throws IOException,
                  JSONObjectException

Throws:

IOException

JSONObjectException

composeUsing

public JSONComposer<OutputStream> composeUsing(JsonGenerator gen)
                                        throws IOException,
                                               JSONObjectException

Throws:

IOException

JSONObjectException

composeTo

public JSONComposer<OutputStream> composeTo(OutputStream out)
                                     throws IOException,
                                            JSONObjectException

Throws:

IOException

JSONObjectException

composeTo

public JSONComposer<OutputStream> composeTo(Writer w)
                                     throws IOException,
                                            JSONObjectException

Throws:

IOException

JSONObjectException

composeTo

public JSONComposer<OutputStream> composeTo(File f)
                                     throws IOException,
                                            JSONObjectException

Throws:

IOException

JSONObjectException

composeString

public JSONComposer<String> composeString()
                                   throws IOException,
                                          JSONObjectException

Throws:

IOException

JSONObjectException

composeBytes

public JSONComposer<byte[]> composeBytes()
                                  throws IOException,
                                         JSONObjectException

Throws:

IOException

JSONObjectException

composeList

public CollectionComposer<?,List<Object>> composeList()

composeCollection

public <C extends Collection<Object>> CollectionComposer<?,C> composeCollection(C collection)

composeMap

public MapComposer<?> composeMap()

composeMap

public MapComposer<?> composeMap(Map<String,Object> map)

listFrom

public List<Object> listFrom(Object source)
                      throws IOException,
                             JSONObjectException

Throws:

IOException

JSONObjectException

listOfFrom

public <T> List<T> listOfFrom(Class<T> type,
                              Object source)
                       throws IOException,
                              JSONObjectException

Throws:

IOException

JSONObjectException

arrayFrom

public Object[] arrayFrom(Object source)
                   throws IOException,
                          JSONObjectException

Throws:

IOException

JSONObjectException

arrayOfFrom

public <T> T[] arrayOfFrom(Class<T> type,
                           Object source)
                    throws IOException,
                           JSONObjectException

Throws:

IOException

JSONObjectException

mapFrom

public Map<String,Object> mapFrom(Object source)
                           throws IOException,
                                  JSONObjectException

Throws:

IOException

JSONObjectException

mapOfFrom

public <T> Map<String,T> mapOfFrom(Class<T> type,
                                   Object source)
                            throws IOException,
                                   JSONObjectException

Read method for reading a Map of type (usually POJO) values.

Throws:

IOException

JSONObjectException

Since:

2.10

beanFrom

public <T> T beanFrom(Class<T> type,
                      Object source)
               throws IOException,
                      JSONObjectException

Throws:

IOException

JSONObjectException

anyFrom

public Object anyFrom(Object source)
               throws IOException

Read method that will take given JSON Source (of one of supported types), read contents and map it to one of simple mappings (Map for JSON Objects, List for JSON Arrays, String for JSON Strings, null for JSON null, Boolean for JSON booleans and Number for JSON numbers.

Supported source types include:

• InputStream
• Reader
• File
• URL
• String
• byte[]
• char[]

Throws:

IOException

treeFrom

public <T extends TreeNode> T treeFrom(Object source)
                                throws IOException,
                                       JSONObjectException

Method for reading content as a JSON Tree (of type that configured TreeCodec, see with(TreeCodec)) supports.

Throws:

IOException

JSONObjectException

Since:

2.8

beanSequenceFrom

public <T> ValueIterator<T> beanSequenceFrom(Class<T> type,
                                             Object source)
                                      throws IOException,
                                             JSONObjectException

Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound to specific Bean (POJO) type.

Throws:

IOException

JSONObjectException

Since:

2.10

anySequenceFrom

public ValueIterator<Object> anySequenceFrom(Object source)
                                      throws IOException,
                                             JSONObjectException

Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as "Simple" type: Map, List, String, Number or Boolean.

Throws:

IOException

JSONObjectException

Since:

2.10

treeSequenceFrom

public <T extends TreeNode> ValueIterator<T> treeSequenceFrom(Object source)
                                                       throws IOException,
                                                              JSONObjectException

Method for creating ValueIterator for reading streaming JSON content (specifically line-delimited and concatenated variants); individual values are bound as JSON Trees(of type that configured TreeCodec, see with(TreeCodec)) supports.

Throws:

IOException

JSONObjectException

createArrayNode

public <T extends TreeNode> T createArrayNode()

Convenience method, equivalent to:

   getTreeCodec().createArrayNode();

Note that for call to succeed a TreeCodec must have been configured with this instance using with(TreeCodec) method.

Since:

2.8

createObjectNode

public <T extends TreeNode> T createObjectNode()

Convenience method, equivalent to:

   getTreeCodec().createObjectNode();

Note that for call to succeed a TreeCodec must have been configured with this instance using with(TreeCodec) method.

Since:

2.8

_writeAndClose

protected final void _writeAndClose(Object value,
                                    JsonGenerator g)
                             throws IOException

Throws:

IOException

_writerForOperation

protected JSONWriter _writerForOperation(JsonGenerator gen)

_readerForOperation

protected JSONReader _readerForOperation(JsonParser p)

_parser

protected JsonParser _parser(Object source)
                      throws IOException,
                             JSONObjectException

Throws:

IOException

JSONObjectException

_initForReading

protected JsonParser _initForReading(JsonParser p)
                              throws IOException

Throws:

IOException

_config

protected JsonGenerator _config(JsonGenerator g)

_config

protected JsonParser _config(JsonParser p)

_closeWithError

protected <T> T _closeWithError(Closeable cl,
                                Exception e)
                         throws IOException

Throws:

IOException

_close

protected void _close(Closeable cl)

_throw

protected <T> T _throw(Exception e)
                throws IOException

Throws:

IOException

_noTreeCodec

protected void _noTreeCodec(String msg)