Package oracle.nosql.driver.values

# Class JsonReader

java.lang.Object
oracle.nosql.driver.values.JsonReader

All Implemented Interfaces:
  `AutoCloseable`, `Iterable<MapValue>`

public class JsonReader extends Object implements Iterable<MapValue>, AutoCloseable
JsonReader reads a file or string that has JSON objects in it that may represent rows and makes them available using the Iterable interface. The source of the JSON, either a File or String, is expected to contain one or more JSON objects, separated by white, or no space. While white space, or no space between objects is explicitly supported, the JSON parser is flexible and forgiving and will silently ignore and skip unexpected characters between JSON objects.

As an iteration proceeds it may return any number of valid MapValue instances before it encounters a problem in the input stream such as a bad object or unexpected end of file. It is up to the application to handle error conditions. There is no mechanism for restarting in the middle of a file or string. If a `JsonParseException` is thrown it will contain the location of the exception in the parse stream to help isolate problems.

An instance of this class can only be used to create a single iterator. This is to ensure that the Iterator can be closed explicitly by the caller. If an attempt is made to create an additional iterator IllegalArgumentException is thrown.

Instances of this class must be closed when done to free parser resources. It implements AutoCloseable to assist but in the event it is not called inside a try-with-resources block an explicit close() should be used.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JsonReader(File file, JsonOptions options)`
  Creates an iterator over JSON objects in the specified file.
  `JsonReader(InputStream input, JsonOptions options)`
  Creates an iterator over JSON objects provided by the InputStream.
  `JsonReader(Reader input, JsonOptions options)`
  Creates an iterator over JSON objects provided by the Reader.
  `JsonReader(String jsonString, JsonOptions options)`
  Creates an iterator over JSON objects in a string.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  `long`
  `getLocationOffset()`
  Returns the byte offset into the JSON being processed if available or -1 if not
  `Iterator<MapValue>`
  `iterator()`
  Returns an Iterator<MapValue> over the source provided.

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

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

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Constructor Details

  - ### JsonReader

    public JsonReader(File file, JsonOptions options)
    Creates an iterator over JSON objects in the specified file.
    Parameters:
      `file` - the file to be used
      `options` - if desired, this can be null

  - ### JsonReader

    public JsonReader(String jsonString, JsonOptions options)
    Creates an iterator over JSON objects in a string.
    Parameters:
      `jsonString` - the String to use
      `options` - if desired, this can be null

  - ### JsonReader

    public JsonReader(InputStream input, JsonOptions options)
    Creates an iterator over JSON objects provided by the InputStream. The caller is responsible for closing the InputStream if necessary.
    Parameters:
      `input` - the InputStream to use
      `options` - if desired, this can be null

  - ### JsonReader

    public JsonReader(Reader input, JsonOptions options)
    Creates an iterator over JSON objects provided by the Reader. The caller is responsible for closing the Reader if necessary.
    Parameters:
      `input` - the Reader to use
      `options` - if desired, this can be null

- ## Method Details

  - ### iterator

    public Iterator<MapValue> iterator()
    Returns an Iterator<MapValue> over the source provided. This method can only be called once for a given instance of JsonReader. An additional call will result in IllegalArgumentException being thrown.
    Specified by:
      `iterator` in interface `Iterable<MapValue>`
    Throws:
      `IllegalArgumentException` - if called twice

  - ### close

    public void close()
    Specified by:
      `close` in interface `AutoCloseable`

  - ### getLocationOffset

    public long getLocationOffset()
    Returns the byte offset into the JSON being processed if available or -1 if not
    Returns:
      the offset or -1 if not available in the underlying data being parsed