org.codehaus.jackson
Class JsonFactory

java.lang.Object
  extended by org.codehaus.jackson.JsonFactory
Direct Known Subclasses:
MappingJsonFactory

public class JsonFactory
extends java.lang.Object

JsonFactory is the main factory class of Jackson package. It is used for constructing streaming parser (aka readers, deserializers) and generators (aka writers, serializers).

Factory instances are thread-safe and reusable after configuration (if any). Typically applications and services use only a single globally shared factory instance, unless they need differently configured factories.

Creation of a factory instance is a light-weight operation, and since there is no need for pluggable alternative implementations (as there is no "standard" json processor API to implement), the default constructor is used for constructing factory instances.

Author:
Tatu Saloranta

Field Summary
protected  ObjectCodec _objectCodec
          Object that implements conversion functionality between Java objects and Json content.
protected  BytesToNameCanonicalizer _rootByteSymbols
          Alternative to the basic symbol table, some stream-based parsers use different name canonicalization method.
protected  CharsToNameCanonicalizer _rootCharSymbols
          Each factory comes equipped with a shared root symbol table.
 
Constructor Summary
JsonFactory()
          Default constructor used to create factory instances.
JsonFactory(ObjectCodec oc)
           
 
Method Summary
protected  IOContext _createContext(java.lang.Object srcRef, boolean resourceManaged)
          Method used by the factory to create parsing context for parser instances.
protected  BufferRecycler _getBufferRecycler()
          Method used by factory to create buffer recycler instances for parsers and generators.
protected static java.io.InputStream _optimizedStreamFromURL(java.net.URL url)
          Helper methods used for constructing an optimal stream for parsers to use, when input is to be read from an URL.
 JsonGenerator createJsonGenerator(java.io.File f, JsonEncoding enc)
          Method for constructing json generator for writing json content to specified file, overwriting contents it might have (or creating it if such file does not yet exist).
 JsonGenerator createJsonGenerator(java.io.OutputStream out, JsonEncoding enc)
          Method for constructing json generator for writing json content using specified output stream.
 JsonGenerator createJsonGenerator(java.io.Writer out)
          Method for constructing json generator for writing json content using specified Writer.
 JsonParser createJsonParser(byte[] data)
           
 JsonParser createJsonParser(byte[] data, int offset, int len)
           
 JsonParser createJsonParser(java.io.File f)
          Method for constructing json parser instance to parse contents of specified file.
 JsonParser createJsonParser(java.io.InputStream in)
          Method for constructing json parser instance to parse the contents accessed via specified input stream.
 JsonParser createJsonParser(java.io.Reader r)
          Method for constructing json parser instance to parse the contents accessed via specified Reader.
 JsonParser createJsonParser(java.lang.String content)
           
 JsonParser createJsonParser(java.net.URL url)
          Method for constructing json parser instance to parse contents of resource reference by given URL.
 void disableGeneratorFeature(JsonGenerator.Feature f)
          Method for disabling specified generator features (check JsonGenerator.Feature for list of features)
 void disableParserFeature(JsonParser.Feature f)
          Method for disabling specified parser features (check JsonParser.Feature for list of features)
 void enableGeneratorFeature(JsonGenerator.Feature f)
          Method for enabling specified generator features (check JsonGenerator.Feature for list of features)
 void enableParserFeature(JsonParser.Feature f)
          Method for enabling specified parser features (check JsonParser.Feature for list of features)
 ObjectCodec getCodec()
           
 boolean isGeneratorFeatureEnabled(JsonGenerator.Feature f)
           
 boolean isParserFeatureEnabled(JsonParser.Feature f)
           
 void setCodec(ObjectCodec oc)
           
 void setGeneratorFeature(JsonGenerator.Feature f, boolean state)
           
 void setParserFeature(JsonParser.Feature f, boolean state)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_rootCharSymbols

protected CharsToNameCanonicalizer _rootCharSymbols
Each factory comes equipped with a shared root symbol table. It should not be linked back to the original blueprint, to avoid contents from leaking between factories.


_rootByteSymbols

protected BytesToNameCanonicalizer _rootByteSymbols
Alternative to the basic symbol table, some stream-based parsers use different name canonicalization method.

TODO: should clean up this; looks messy having 2 alternatives with not very clear differences.


_objectCodec

protected ObjectCodec _objectCodec
Object that implements conversion functionality between Java objects and Json content. For base JsonFactory implementation usually not set by default, but can be explicitly set. Sub-classes (like @link org.codehaus.jackson.map.MappingJsonFactory} usually provide an implementation.

Constructor Detail

JsonFactory

public JsonFactory()
Default constructor used to create factory instances. Creation of a factory instance is a light-weight operation, but it is still a good idea to reuse limited number of factory instances (and quite often just a single instance): factories are used as context for storing some reused processing objects (such as symbol tables parsers use) and this reuse only works within context of a single factory instance.


JsonFactory

public JsonFactory(ObjectCodec oc)
Method Detail

enableParserFeature

public final void enableParserFeature(JsonParser.Feature f)
Method for enabling specified parser features (check JsonParser.Feature for list of features)


disableParserFeature

public final void disableParserFeature(JsonParser.Feature f)
Method for disabling specified parser features (check JsonParser.Feature for list of features)


setParserFeature

public final void setParserFeature(JsonParser.Feature f,
                                   boolean state)

isParserFeatureEnabled

public final boolean isParserFeatureEnabled(JsonParser.Feature f)

enableGeneratorFeature

public final void enableGeneratorFeature(JsonGenerator.Feature f)
Method for enabling specified generator features (check JsonGenerator.Feature for list of features)


disableGeneratorFeature

public final void disableGeneratorFeature(JsonGenerator.Feature f)
Method for disabling specified generator features (check JsonGenerator.Feature for list of features)


setGeneratorFeature

public final void setGeneratorFeature(JsonGenerator.Feature f,
                                      boolean state)

isGeneratorFeatureEnabled

public final boolean isGeneratorFeatureEnabled(JsonGenerator.Feature f)

setCodec

public void setCodec(ObjectCodec oc)

getCodec

public ObjectCodec getCodec()

createJsonParser

public final JsonParser createJsonParser(java.io.File f)
                                  throws java.io.IOException,
                                         JsonParseException
Method for constructing json parser instance to parse contents of specified file. Encoding is auto-detected from contents according to json specification recommended mechanism.

Underlying input stream (needed for reading contents) will be owned (and managed, i.e. closed as need be) by the parser, since caller has no access to it.

Parameters:
f - File that contains JSON content to parse
Throws:
java.io.IOException
JsonParseException

createJsonParser

public final JsonParser createJsonParser(java.net.URL url)
                                  throws java.io.IOException,
                                         JsonParseException
Method for constructing json parser instance to parse contents of resource reference by given URL. Encoding is auto-detected from contents according to json specification recommended mechanism.

Underlying input stream (needed for reading contents) will be owned (and managed, i.e. closed as need be) by the parser, since caller has no access to it.

Parameters:
url - URL pointing to resource that contains JSON content to parse
Throws:
java.io.IOException
JsonParseException

createJsonParser

public final JsonParser createJsonParser(java.io.InputStream in)
                                  throws java.io.IOException,
                                         JsonParseException
Method for constructing json parser instance to parse the contents accessed via specified input stream.

The input stream will not be owned by the parser, it will still be managed (i.e. closed if end-of-stream is reacher, or parser close method called) if (and only if) JsonParser.Feature.AUTO_CLOSE_SOURCE is enabled.

Note: no encoding argument is taken since it can always be auto-detected as suggested by Json RFC.

Parameters:
in - InputStream to use for reading JSON content to parse
Throws:
java.io.IOException
JsonParseException

createJsonParser

public final JsonParser createJsonParser(java.io.Reader r)
                                  throws java.io.IOException,
                                         JsonParseException
Method for constructing json parser instance to parse the contents accessed via specified Reader.

The read stream will not be owned by the parser, it will still be managed (i.e. closed if end-of-stream is reacher, or parser close method called) if (and only if) JsonParser.Feature.AUTO_CLOSE_SOURCE is enabled.

Parameters:
r - Reader to use for reading JSON content to parse
Throws:
java.io.IOException
JsonParseException

createJsonParser

public final JsonParser createJsonParser(byte[] data)
                                  throws java.io.IOException,
                                         JsonParseException
Throws:
java.io.IOException
JsonParseException

createJsonParser

public final JsonParser createJsonParser(byte[] data,
                                         int offset,
                                         int len)
                                  throws java.io.IOException,
                                         JsonParseException
Throws:
java.io.IOException
JsonParseException

createJsonParser

public final JsonParser createJsonParser(java.lang.String content)
                                  throws java.io.IOException,
                                         JsonParseException
Throws:
java.io.IOException
JsonParseException

createJsonGenerator

public final JsonGenerator createJsonGenerator(java.io.OutputStream out,
                                               JsonEncoding enc)
                                        throws java.io.IOException
Method for constructing json generator for writing json content using specified output stream. Encoding to use must be specified, and needs to be one of available types (as per JSON specification).

Underlying stream is NOT owned by the generator constructed, so that generator will NOT close the output stream when JsonGenerator.close() is called (unless auto-closing feature, JsonGenerator.Feature.AUTO_CLOSE_TARGET is enabled). Using application needs to close it explicitly if this is the case.

Parameters:
out - OutputStream to use for writing json content
enc - Character encoding to use
Throws:
java.io.IOException

createJsonGenerator

public final JsonGenerator createJsonGenerator(java.io.Writer out)
                                        throws java.io.IOException
Method for constructing json generator for writing json content using specified Writer.

Underlying stream is NOT owned by the generator constructed, so that generator will NOT close the Reader when JsonGenerator.close() is called (unless auto-closing feature, JsonGenerator.Feature.AUTO_CLOSE_TARGET is enabled). Using application needs to close it explicitly.

Parameters:
out - Writer to use for writing json content
Throws:
java.io.IOException

createJsonGenerator

public final JsonGenerator createJsonGenerator(java.io.File f,
                                               JsonEncoding enc)
                                        throws java.io.IOException
Method for constructing json generator for writing json content to specified file, overwriting contents it might have (or creating it if such file does not yet exist). Encoding to use must be specified, and needs to be one of available types (as per JSON specification).

Underlying stream is owned by the generator constructed, i.e. generator will handle closing of file when JsonGenerator.close() is called.

Parameters:
f - File to write contents to
enc - Character encoding to use
Throws:
java.io.IOException

_createContext

protected final IOContext _createContext(java.lang.Object srcRef,
                                         boolean resourceManaged)
Method used by the factory to create parsing context for parser instances.


_getBufferRecycler

protected final BufferRecycler _getBufferRecycler()
Method used by factory to create buffer recycler instances for parsers and generators.


_optimizedStreamFromURL

protected static final java.io.InputStream _optimizedStreamFromURL(java.net.URL url)
                                                            throws java.io.IOException
Helper methods used for constructing an optimal stream for parsers to use, when input is to be read from an URL. This helps when reading file content via URL.

Throws:
java.io.IOException