SmileFactory (Jackson JSON Processor)
Date: 2013-07-14

org.codehaus.jackson.smile

## Class SmileFactory

- java.lang.Object
- - org.codehaus.jackson.JsonFactory
  - - org.codehaus.jackson.smile.SmileFactory

- All Implemented Interfaces:
    Versioned

      public class SmileFactory
      extends JsonFactory

  Factory used for constructing `SmileParser` and `SmileGenerator` instances; both of which handle Smile encoded data.

  Extends `JsonFactory` mostly so that users can actually use it in place of regular non-Smile factory instances.

  Note on using non-byte-based sources/targets (char based, like `Reader` and `Writer`): these can not be used for Smile-format documents, and thus will either downgrade to textual JSON (when parsing), or throw exception (when trying to create generator).

  Since:
    1.6
  Author:
    tatu

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_cfgDelegateToTextual` Whether non-supported methods (ones trying to output using char-based targets like `Writer`, for example) should be delegated to regular Jackson JSON processing (if set to true); or throw `UnsupportedOperationException` (if set to false)
    `protected int` | `_smileGeneratorFeatures`
    `protected int` | `_smileParserFeatures`
    `static String` | `FORMAT_NAME_SMILE` Name used to identify Smile format.

    - ### Fields inherited from class org.codehaus.jackson.JsonFactory

      `_characterEscapes, _generatorFeatures, _inputDecorator, _objectCodec, _outputDecorator, _parserFeatures, _recyclerRef, _rootByteSymbols, _rootCharSymbols, FORMAT_NAME_JSON`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SmileFactory()` Default constructor used to create factory instances.
    `SmileFactory(ObjectCodec oc)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected SmileGenerator` | `_createJsonGenerator(OutputStream out, IOContext ctxt)`
    `protected JsonGenerator` | `_createJsonGenerator(Writer out, IOContext ctxt)` Overridable factory method that actually instantiates desired generator.
    `protected SmileParser` | `_createJsonParser(byte[] data, int offset, int len, IOContext ctxt)` Overridable factory method that actually instantiates desired parser.
    `protected SmileParser` | `_createJsonParser(InputStream in, IOContext ctxt)` Overridable factory method that actually instantiates desired parser.
    `protected JsonParser` | `_createJsonParser(Reader r, IOContext ctxt)` Overridable factory method that actually instantiates desired parser.
    `protected Writer` | `_createWriter(OutputStream out, JsonEncoding enc, IOContext ctxt)`
    `SmileFactory` | `configure(SmileGenerator.Feature f, boolean state)` Method for enabling or disabling specified generator feature (check `JsonGenerator.Feature` for list of features)
    `SmileFactory` | `configure(SmileParser.Feature f, boolean state)` Method for enabling or disabling specified parser feature (check `SmileParser.Feature` for list of features)
    `SmileGenerator` | `createJsonGenerator(OutputStream out)` Since Smile format always uses UTF-8 internally, no encoding need to be passed to this method.
    `SmileGenerator` | `createJsonGenerator(OutputStream out, JsonEncoding enc)` note: co-variant return type
    `SmileParser` | `createJsonParser(byte[] data)` Method for constructing parser for parsing the contents of given byte array.
    `SmileParser` | `createJsonParser(byte[] data, int offset, int len)` Method for constructing parser for parsing the contents of given byte array.
    `SmileParser` | `createJsonParser(File f)` Method for constructing JSON parser instance to parse contents of specified file.
    `SmileParser` | `createJsonParser(InputStream in)` Method for constructing JSON parser instance to parse the contents accessed via specified input stream.
    `SmileParser` | `createJsonParser(URL url)` Method for constructing JSON parser instance to parse contents of resource reference by given URL.
    `void` | `delegateToTextual(boolean state)`
    `SmileFactory` | `disable(SmileGenerator.Feature f)` Method for disabling specified generator feature (check `JsonGenerator.Feature` for list of features)
    `SmileFactory` | `disable(SmileParser.Feature f)` Method for disabling specified parser features (check `SmileParser.Feature` for list of features)
    `SmileFactory` | `enable(SmileGenerator.Feature f)` Method for enabling specified generator features (check `JsonGenerator.Feature` for list of features)
    `SmileFactory` | `enable(SmileParser.Feature f)` Method for enabling specified parser feature (check `SmileParser.Feature` for list of features)
    `String` | `getFormatName()` Method that returns short textual id identifying format this factory supports.
    `MatchStrength` | `hasFormat(InputAccessor acc)` Sub-classes need to override this method (as of 1.8)
    `boolean` | `isEnabled(SmileGenerator.Feature f)` Check whether specified generator feature is enabled.
    `boolean` | `isEnabled(SmileParser.Feature f)` Checked whether specified parser feature is enabled.

    - ### Methods inherited from class org.codehaus.jackson.JsonFactory

      `_createContext, _createUTF8JsonGenerator, _getBufferRecycler, _optimizedStreamFromURL, configure, configure, createJsonGenerator, createJsonGenerator, createJsonParser, createJsonParser, disable, disable, disableGeneratorFeature, disableParserFeature, enable, enable, enableGeneratorFeature, enableParserFeature, getCharacterEscapes, getCodec, getInputDecorator, getOutputDecorator, hasJSONFormat, isEnabled, isEnabled, isGeneratorFeatureEnabled, isParserFeatureEnabled, setCharacterEscapes, setCodec, setGeneratorFeature, setInputDecorator, setOutputDecorator, setParserFeature, version`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### FORMAT_NAME_SMILE

          public static final String FORMAT_NAME_SMILE

      Name used to identify Smile format. (and returned by `getFormatName()`
      See Also:
        Constant Field Values

    - #### _cfgDelegateToTextual

          protected boolean _cfgDelegateToTextual

      Whether non-supported methods (ones trying to output using char-based targets like `Writer`, for example) should be delegated to regular Jackson JSON processing (if set to true); or throw `UnsupportedOperationException` (if set to false)

    - #### _smileParserFeatures

          protected int _smileParserFeatures

    - #### _smileGeneratorFeatures

          protected int _smileGeneratorFeatures

  - ### Constructor Detail

    - #### SmileFactory

          public SmileFactory()

      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.

    - #### SmileFactory

          public SmileFactory(ObjectCodec oc)

  - ### Method Detail

    - #### delegateToTextual

          public void delegateToTextual(boolean state)

    - #### getFormatName

          public String getFormatName()

      Description copied from class: `JsonFactory`
      Method that returns short textual id identifying format this factory supports.

      Note: sub-classes should override this method; default implementation will return null for all sub-classes

      Overrides:
        `getFormatName` in class `JsonFactory`

    - #### hasFormat

          public MatchStrength hasFormat(InputAccessor acc)
                                  throws IOException

      Sub-classes need to override this method (as of 1.8)
      Overrides:
        `hasFormat` in class `JsonFactory`
      Throws:
        `IOException`

    - #### configure

          public final SmileFactory configure(SmileParser.Feature f,
                               boolean state)

      Method for enabling or disabling specified parser feature (check `SmileParser.Feature` for list of features)

    - #### enable

          public SmileFactory enable(SmileParser.Feature f)

      Method for enabling specified parser feature (check `SmileParser.Feature` for list of features)

    - #### disable

          public SmileFactory disable(SmileParser.Feature f)

      Method for disabling specified parser features (check `SmileParser.Feature` for list of features)

    - #### isEnabled

          public final boolean isEnabled(SmileParser.Feature f)

      Checked whether specified parser feature is enabled.

    - #### configure

          public final SmileFactory configure(SmileGenerator.Feature f,
                               boolean state)

      Method for enabling or disabling specified generator feature (check `JsonGenerator.Feature` for list of features)
      Since:
        1.2

    - #### enable

          public SmileFactory enable(SmileGenerator.Feature f)

      Method for enabling specified generator features (check `JsonGenerator.Feature` for list of features)

    - #### disable

          public SmileFactory disable(SmileGenerator.Feature f)

      Method for disabling specified generator feature (check `JsonGenerator.Feature` for list of features)

    - #### isEnabled

          public final boolean isEnabled(SmileGenerator.Feature f)

      Check whether specified generator feature is enabled.

    - #### createJsonParser

          public SmileParser createJsonParser(File f)
                                       throws IOException,
                                              JsonParseException

      Description copied from class: `JsonFactory`
      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.

      Overrides:
        `createJsonParser` in class `JsonFactory`
      Parameters:
        `f` - File that contains JSON content to parse
      Throws:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

          public SmileParser createJsonParser(URL url)
                                       throws IOException,
                                              JsonParseException

      Description copied from class: `JsonFactory`
      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.

      Overrides:
        `createJsonParser` in class `JsonFactory`
      Parameters:
        `url` - URL pointing to resource that contains JSON content to parse
      Throws:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

          public SmileParser createJsonParser(InputStream in)
                                       throws IOException,
                                              JsonParseException

      Description copied from class: `JsonFactory`
      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.

      Overrides:
        `createJsonParser` in class `JsonFactory`
      Parameters:
        `in` - InputStream to use for reading JSON content to parse
      Throws:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

          public SmileParser createJsonParser(byte[] data)
                                       throws IOException,
                                              JsonParseException

      Description copied from class: `JsonFactory`
      Method for constructing parser for parsing the contents of given byte array.
      Overrides:
        `createJsonParser` in class `JsonFactory`
      Throws:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

          public SmileParser createJsonParser(byte[] data,
                                     int offset,
                                     int len)
                                       throws IOException,
                                              JsonParseException

      Description copied from class: `JsonFactory`
      Method for constructing parser for parsing the contents of given byte array.
      Overrides:
        `createJsonParser` in class `JsonFactory`
      Parameters:
        `data` - Buffer that contains data to parse
        `offset` - Offset of the first data byte within buffer
        `len` - Length of contents to parse within buffer
      Throws:
        `IOException`
        `JsonParseException`

    - #### createJsonGenerator

          public SmileGenerator createJsonGenerator(OutputStream out,
                                           JsonEncoding enc)
                                             throws IOException

      note: co-variant return type

      Overrides:
        `createJsonGenerator` in class `JsonFactory`
      Parameters:
        `out` - OutputStream to use for writing JSON content
        `enc` - Character encoding to use
      Throws:
        `IOException`

    - #### createJsonGenerator

          public SmileGenerator createJsonGenerator(OutputStream out)
                                             throws IOException

      Since Smile format always uses UTF-8 internally, no encoding need to be passed to this method.
      Overrides:
        `createJsonGenerator` in class `JsonFactory`
      Throws:
        `IOException`

    - #### _createJsonParser

          protected SmileParser _createJsonParser(InputStream in,
                                      IOContext ctxt)
                                           throws IOException,
                                                  JsonParseException

      Overridable factory method that actually instantiates desired parser.
      Overrides:
        `_createJsonParser` in class `JsonFactory`
      Throws:
        `IOException`
        `JsonParseException`

    - #### _createJsonParser

          protected JsonParser _createJsonParser(Reader r,
                                     IOContext ctxt)
                                          throws IOException,
                                                 JsonParseException

      Overridable factory method that actually instantiates desired parser.
      Overrides:
        `_createJsonParser` in class `JsonFactory`
      Throws:
        `IOException`
        `JsonParseException`

    - #### _createJsonParser

          protected SmileParser _createJsonParser(byte[] data,
                                      int offset,
                                      int len,
                                      IOContext ctxt)
                                           throws IOException,
                                                  JsonParseException

      Overridable factory method that actually instantiates desired parser.
      Overrides:
        `_createJsonParser` in class `JsonFactory`
      Throws:
        `IOException`
        `JsonParseException`

    - #### _createJsonGenerator

          protected JsonGenerator _createJsonGenerator(Writer out,
                                           IOContext ctxt)
                                                throws IOException

      Overridable factory method that actually instantiates desired generator.
      Overrides:
        `_createJsonGenerator` in class `JsonFactory`
      Throws:
        `IOException`

    - #### _createWriter

          protected Writer _createWriter(OutputStream out,
                             JsonEncoding enc,
                             IOContext ctxt)
                                  throws IOException

      Overrides:
        `_createWriter` in class `JsonFactory`
      Throws:
        `IOException`

    - #### _createJsonGenerator

          protected SmileGenerator _createJsonGenerator(OutputStream out,
                                            IOContext ctxt)
                                                 throws IOException

      Throws:
        `IOException`