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

org.codehaus.jackson

## Class JsonFactory

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

- All Implemented Interfaces:
    Versioned
  Direct Known Subclasses:
    MappingJsonFactory, SmileFactory

      public class JsonFactory
      extends Object
      implements Versioned

  The main factory class of Jackson package, used to configure and construct reader (aka parser, `JsonParser`) and writer (aka generator, `JsonGenerator`) instances.

  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. Factory reuse is important if efficiency matters; most recycling of expensive construct is done on per-factory basis.

  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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected CharacterEscapes` | `_characterEscapes` Definition of custom character escapes to use for generators created by this factory, if any.
    `protected int` | `_generatorFeatures` Currently enabled generator features.
    `protected InputDecorator` | `_inputDecorator` Optional helper object that may decorate input sources, to do additional processing on input during parsing.
    `protected ObjectCodec` | `_objectCodec` Object that implements conversion functionality between Java objects and JSON content.
    `protected OutputDecorator` | `_outputDecorator` Optional helper object that may decorate output object, to do additional processing on output during content generation.
    `protected int` | `_parserFeatures` Currently enabled parser features.
    `protected static ThreadLocal<SoftReference<BufferRecycler>>` | `_recyclerRef` This `ThreadLocal` contains a `SoftReference` to a `BufferRecycler` used to provide a low-cost buffer recycling between reader and writer instances.
    `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.
    `static String` | `FORMAT_NAME_JSON` Name used to identify JSON format (and returned by `getFormatName()`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected IOContext` | `_createContext(Object srcRef, boolean resourceManaged)` Overridable factory method that actually instantiates desired context object.
    `protected JsonGenerator` | `_createJsonGenerator(Writer out, IOContext ctxt)` Overridable factory method that actually instantiates generator for given `Writer` and context object.
    `protected JsonParser` | `_createJsonParser(byte[] data, int offset, int len, IOContext ctxt)` Overridable factory method that actually instantiates parser using given `Reader` object for reading content passed as raw byte array.
    `protected JsonParser` | `_createJsonParser(InputStream in, IOContext ctxt)` Overridable factory method that actually instantiates desired parser given `InputStream` and context object.
    `protected JsonParser` | `_createJsonParser(Reader r, IOContext ctxt)` Overridable factory method that actually instantiates parser using given `Reader` object for reading content.
    `protected JsonGenerator` | `_createUTF8JsonGenerator(OutputStream out, IOContext ctxt)` Overridable factory method that actually instantiates generator for given `OutputStream` and context object, using UTF-8 encoding.
    `protected Writer` | `_createWriter(OutputStream out, JsonEncoding enc, IOContext ctxt)`
    `BufferRecycler` | `_getBufferRecycler()` Method used by factory to create buffer recycler instances for parsers and generators.
    `protected InputStream` | `_optimizedStreamFromURL(URL url)` Helper methods used for constructing an optimal stream for parsers to use, when input is to be read from an URL.
    `JsonFactory` | `configure(JsonGenerator.Feature f, boolean state)` Method for enabling or disabling specified generator feature (check `JsonGenerator.Feature` for list of features)
    `JsonFactory` | `configure(JsonParser.Feature f, boolean state)` Method for enabling or disabling specified parser feature (check `JsonParser.Feature` for list of features)
    `JsonGenerator` | `createJsonGenerator(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(OutputStream out)` Convenience method for constructing generator that uses default encoding of the format (UTF-8 for JSON and most other data formats).
    `JsonGenerator` | `createJsonGenerator(OutputStream out, JsonEncoding enc)` Method for constructing JSON generator for writing JSON content using specified output stream.
    `JsonGenerator` | `createJsonGenerator(Writer out)` Method for constructing JSON generator for writing JSON content using specified Writer.
    `JsonParser` | `createJsonParser(byte[] data)` Method for constructing parser for parsing the contents of given byte array.
    `JsonParser` | `createJsonParser(byte[] data, int offset, int len)` Method for constructing parser for parsing the contents of given byte array.
    `JsonParser` | `createJsonParser(File f)` Method for constructing JSON parser instance to parse contents of specified file.
    `JsonParser` | `createJsonParser(InputStream in)` Method for constructing JSON parser instance to parse the contents accessed via specified input stream.
    `JsonParser` | `createJsonParser(Reader r)` Method for constructing parser for parsing the contents accessed via specified Reader.
    `JsonParser` | `createJsonParser(String content)` Method for constructing parser for parsing contens of given String.
    `JsonParser` | `createJsonParser(URL url)` Method for constructing JSON parser instance to parse contents of resource reference by given URL.
    `JsonFactory` | `disable(JsonGenerator.Feature f)` Method for disabling specified generator feature (check `JsonGenerator.Feature` for list of features)
    `JsonFactory` | `disable(JsonParser.Feature f)` Method for disabling specified parser features (check `JsonParser.Feature` for list of features)
    `void` | `disableGeneratorFeature(JsonGenerator.Feature f)` Deprecated. Use `disable(JsonGenerator.Feature)` instead
    `void` | `disableParserFeature(JsonParser.Feature f)` Deprecated. Use `disable(JsonParser.Feature)` instead
    `JsonFactory` | `enable(JsonGenerator.Feature f)` Method for enabling specified generator features (check `JsonGenerator.Feature` for list of features)
    `JsonFactory` | `enable(JsonParser.Feature f)` Method for enabling specified parser feature (check `JsonParser.Feature` for list of features)
    `void` | `enableGeneratorFeature(JsonGenerator.Feature f)` Deprecated. Use `enable(JsonGenerator.Feature)` instead
    `void` | `enableParserFeature(JsonParser.Feature f)` Deprecated. Use `enable(JsonParser.Feature)` instead
    `CharacterEscapes` | `getCharacterEscapes()` Method for accessing custom escapes factory uses for `JsonGenerator`s it creates.
    `ObjectCodec` | `getCodec()`
    `String` | `getFormatName()` Method that returns short textual id identifying format this factory supports.
    `InputDecorator` | `getInputDecorator()` Method for getting currently configured input decorator (if any; there is no default decorator).
    `OutputDecorator` | `getOutputDecorator()` Method for getting currently configured output decorator (if any; there is no default decorator).
    `MatchStrength` | `hasFormat(InputAccessor acc)`
    `protected MatchStrength` | `hasJSONFormat(InputAccessor acc)`
    `boolean` | `isEnabled(JsonGenerator.Feature f)` Check whether specified generator feature is enabled.
    `boolean` | `isEnabled(JsonParser.Feature f)` Checked whether specified parser feature is enabled.
    `boolean` | `isGeneratorFeatureEnabled(JsonGenerator.Feature f)` Deprecated. Use `isEnabled(JsonGenerator.Feature)` instead
    `boolean` | `isParserFeatureEnabled(JsonParser.Feature f)` Deprecated. Use `isEnabled(JsonParser.Feature)` instead
    `JsonFactory` | `setCharacterEscapes(CharacterEscapes esc)` Method for defining custom escapes factory uses for `JsonGenerator`s it creates.
    `JsonFactory` | `setCodec(ObjectCodec oc)` Method for associating a `ObjectCodec` (typically a `ObjectMapper`) with this factory (and more importantly, parsers and generators it constructs).
    `void` | `setGeneratorFeature(JsonGenerator.Feature f, boolean state)` Deprecated. Use `configure(JsonGenerator.Feature, boolean)` instead
    `JsonFactory` | `setInputDecorator(InputDecorator d)` Method for overriding currently configured input decorator
    `JsonFactory` | `setOutputDecorator(OutputDecorator d)` Method for overriding currently configured output decorator
    `void` | `setParserFeature(JsonParser.Feature f, boolean state)` Deprecated. Use `configure(JsonParser.Feature, boolean)` instead
    `Version` | `version()` Method called to detect version of the component that implements this interface; returned version should never be null, but may return specific "not available" instance (see `Version` for details).

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

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

- - ### Field Detail

    - #### FORMAT_NAME_JSON

          public static final String FORMAT_NAME_JSON

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

    - #### _recyclerRef

          protected static final ThreadLocal<SoftReference<BufferRecycler>> _recyclerRef

      This `ThreadLocal` contains a `SoftReference` to a `BufferRecycler` used to provide a low-cost buffer recycling between reader and writer instances.

    - #### _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.

    - #### _parserFeatures

          protected int _parserFeatures

      Currently enabled parser features.

    - #### _generatorFeatures

          protected int _generatorFeatures

      Currently enabled generator features.

    - #### _characterEscapes

          protected CharacterEscapes _characterEscapes

      Definition of custom character escapes to use for generators created by this factory, if any. If null, standard data format specific escapes are used.
      Since:
        1.8

    - #### _inputDecorator

          protected InputDecorator _inputDecorator

      Optional helper object that may decorate input sources, to do additional processing on input during parsing.
      Since:
        1.8

    - #### _outputDecorator

          protected OutputDecorator _outputDecorator

      Optional helper object that may decorate output object, to do additional processing on output during content generation.
      Since:
        1.8

  - ### 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

    - #### getFormatName

          public String getFormatName()

      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

      Since:
        1.8

    - #### hasFormat

          public MatchStrength hasFormat(InputAccessor acc)
                                  throws IOException

      Throws:
        `IOException`

    - #### hasJSONFormat

          protected MatchStrength hasJSONFormat(InputAccessor acc)
                                         throws IOException

      Throws:
        `IOException`

    - #### version

          public Version version()

      Description copied from interface: `Versioned`
      Method called to detect version of the component that implements this interface; returned version should never be null, but may return specific "not available" instance (see `Version` for details).
      Specified by:
        `version` in interface `Versioned`

    - #### configure

          public final JsonFactory configure(JsonParser.Feature f,
                              boolean state)

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

    - #### enable

          public JsonFactory enable(JsonParser.Feature f)

      Method for enabling specified parser feature (check `JsonParser.Feature` for list of features)
      Since:
        1.2

    - #### disable

          public JsonFactory disable(JsonParser.Feature f)

      Method for disabling specified parser features (check `JsonParser.Feature` for list of features)
      Since:
        1.2

    - #### isEnabled

          public final boolean isEnabled(JsonParser.Feature f)

      Checked whether specified parser feature is enabled.
      Since:
        1.2

    - #### enableParserFeature

          public final void enableParserFeature(JsonParser.Feature f)

      Deprecated. Use `enable(JsonParser.Feature)` instead

    - #### disableParserFeature

          public final void disableParserFeature(JsonParser.Feature f)

      Deprecated. Use `disable(JsonParser.Feature)` instead

    - #### setParserFeature

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

      Deprecated. Use `configure(JsonParser.Feature, boolean)` instead

    - #### isParserFeatureEnabled

          public final boolean isParserFeatureEnabled(JsonParser.Feature f)

      Deprecated. Use `isEnabled(JsonParser.Feature)` instead

    - #### getInputDecorator

          public InputDecorator getInputDecorator()

      Method for getting currently configured input decorator (if any; there is no default decorator).
      Since:
        1.8

    - #### setInputDecorator

          public JsonFactory setInputDecorator(InputDecorator d)

      Method for overriding currently configured input decorator
      Since:
        1.8

    - #### configure

          public final JsonFactory configure(JsonGenerator.Feature f,
                              boolean state)

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

    - #### enable

          public JsonFactory enable(JsonGenerator.Feature f)

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

    - #### disable

          public JsonFactory disable(JsonGenerator.Feature f)

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

    - #### isEnabled

          public final boolean isEnabled(JsonGenerator.Feature f)

      Check whether specified generator feature is enabled.
      Since:
        1.2

    - #### enableGeneratorFeature

          @Deprecated
          public final void enableGeneratorFeature(JsonGenerator.Feature f)

      Deprecated. Use `enable(JsonGenerator.Feature)` instead

    - #### disableGeneratorFeature

          @Deprecated
          public final void disableGeneratorFeature(JsonGenerator.Feature f)

      Deprecated. Use `disable(JsonGenerator.Feature)` instead

    - #### setGeneratorFeature

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

      Deprecated. Use `configure(JsonGenerator.Feature, boolean)` instead

    - #### isGeneratorFeatureEnabled

          @Deprecated
          public final boolean isGeneratorFeatureEnabled(JsonGenerator.Feature f)

      Deprecated. Use `isEnabled(JsonGenerator.Feature)` instead

    - #### getCharacterEscapes

          public CharacterEscapes getCharacterEscapes()

      Method for accessing custom escapes factory uses for `JsonGenerator`s it creates.
      Since:
        1.8

    - #### setCharacterEscapes

          public JsonFactory setCharacterEscapes(CharacterEscapes esc)

      Method for defining custom escapes factory uses for `JsonGenerator`s it creates.
      Since:
        1.8

    - #### getOutputDecorator

          public OutputDecorator getOutputDecorator()

      Method for getting currently configured output decorator (if any; there is no default decorator).
      Since:
        1.8

    - #### setOutputDecorator

          public JsonFactory setOutputDecorator(OutputDecorator d)

      Method for overriding currently configured output decorator
      Since:
        1.8

    - #### setCodec

          public JsonFactory setCodec(ObjectCodec oc)

      Method for associating a `ObjectCodec` (typically a `ObjectMapper`) with this factory (and more importantly, parsers and generators it constructs). This is needed to use data-binding methods of `JsonParser` and `JsonGenerator` instances.

    - #### getCodec

          public ObjectCodec getCodec()

    - #### createJsonParser

          public JsonParser createJsonParser(File f)
                                      throws 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:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

          public JsonParser createJsonParser(URL url)
                                      throws 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:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

          public JsonParser createJsonParser(InputStream in)
                                      throws 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:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

          public JsonParser createJsonParser(Reader r)
                                      throws IOException,
                                             JsonParseException

      Method for constructing parser for parsing 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:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

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

      Method for constructing parser for parsing the contents of given byte array.
      Throws:
        `IOException`
        `JsonParseException`

    - #### createJsonParser

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

      Method for constructing parser for parsing the contents of given byte array.
      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`

    - #### createJsonParser

          public JsonParser createJsonParser(String content)
                                      throws IOException,
                                             JsonParseException

      Method for constructing parser for parsing contens of given String.
      Throws:
        `IOException`
        `JsonParseException`

    - #### createJsonGenerator

          public JsonGenerator createJsonGenerator(OutputStream out,
                                          JsonEncoding enc)
                                            throws 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.

      Note: there are formats that use fixed encoding (like most binary data formats) and that ignore passed in encoding.

      Parameters:
        `out` - OutputStream to use for writing JSON content
        `enc` - Character encoding to use
      Throws:
        `IOException`

    - #### createJsonGenerator

          public JsonGenerator createJsonGenerator(Writer out)
                                            throws 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:
        `IOException`

    - #### createJsonGenerator

          public JsonGenerator createJsonGenerator(OutputStream out)
                                            throws IOException

      Convenience method for constructing generator that uses default encoding of the format (UTF-8 for JSON and most other data formats).

      Note: there are formats that use fixed encoding (like most binary data formats).

      Throws:
        `IOException`
      Since:
        1.8

    - #### createJsonGenerator

          public JsonGenerator createJsonGenerator(File f,
                                          JsonEncoding enc)
                                            throws 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:
        `IOException`

    - #### _createJsonParser

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

      Overridable factory method that actually instantiates desired parser given `InputStream` and context object.

      This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.

      Throws:
        `IOException`
        `JsonParseException`

    - #### _createJsonParser

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

      Overridable factory method that actually instantiates parser using given `Reader` object for reading content.

      This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.

      Throws:
        `IOException`
        `JsonParseException`

    - #### _createJsonParser

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

      Overridable factory method that actually instantiates parser using given `Reader` object for reading content passed as raw byte array.

      This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.

      Throws:
        `IOException`
        `JsonParseException`

    - #### _createJsonGenerator

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

      Overridable factory method that actually instantiates generator for given `Writer` and context object.

      This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.

      Throws:
        `IOException`

    - #### _createUTF8JsonGenerator

          protected JsonGenerator _createUTF8JsonGenerator(OutputStream out,
                                               IOContext ctxt)
                                                    throws IOException

      Overridable factory method that actually instantiates generator for given `OutputStream` and context object, using UTF-8 encoding.

      This method is specifically designed to remain compatible between minor versions so that sub-classes can count on it being called as expected. That is, it is part of official interface from sub-class perspective, although not a public method available to users of factory implementations.

      Throws:
        `IOException`

    - #### _createWriter

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

      Throws:
        `IOException`

    - #### _createContext

          protected IOContext _createContext(Object srcRef,
                                 boolean resourceManaged)

      Overridable factory method that actually instantiates desired context object.

    - #### _getBufferRecycler

          public BufferRecycler _getBufferRecycler()

      Method used by factory to create buffer recycler instances for parsers and generators.

      Note: only public to give access for `ObjectMapper`

    - #### _optimizedStreamFromURL

          protected InputStream _optimizedStreamFromURL(URL url)
                                                 throws 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:
        `IOException`