# Package oracle.dbtools.plugin.api.json

JavaScript Object Notation (JSON) APIs for reading and writing JSON character streams.

### Usage

#### Reading a stream

JSON can be read from a character stream using the `JSONStreams.jsonReader(Readable)` method.

     @Provides
     class SomePlugin implements SomeService {
      @Inject SomePlugin(JSONStreams json) {
       this.json = json;
      }

      @Override
      public void someMethod(java.io.Reader stream) {
       final JSONReader reader = json.jsonReader(stream);
       while ( reader.hasNext() ) {
        JSONToken token = reader.next();
        switch(token.type()) {
         //process JSON tokens here
         ...
        }
       }

       private final JSONStreams json;
      }

#### Reading from a String

JSON can be read from any `CharSequence` including the `String` class using the `JSONStreams.jsonReader(CharSequence)` method.

       final JSONStreams json = ... ;
       String text = ...; // contents of text is a JSON document
       final JSONReader reader = json.jsonReader(text);
       while ( reader.hasNext() ) {
        JSONToken token = reader.next();
        switch(token.type()) {
         //process JSON tokens here
         ...
        }
       }

#### Writing JSON

JSON can be written to any `Appendable` instance, including `StringBuilder` and all sub-classes of `Writer`,using the `JSONStreams.jsonWriter(Appendable)` method.

       final JSONStreams json = ... ;
       StringBuilder text = new StringBuilder();
       final JSONWriter writer = json.jsonWriter(text);
       writer.startObject().property("foo","bar").endObject();
       System.out.println(text); // emits: {"foo":"bar"}

#### Embedding JSON

To embed one JSON document as the value of a property in another document, the embedded JSON must be parsed into `JSONToken` instances using `JSONReader` and then appended to a `JSONWriter` instance

      JSONStreams json = ...;
      String embedded = "{\"a\":\"b\"}";
      JSONReader reader = json.jsonReader(embedded);
      StringBuilder output = new StringBuilder();
      JSONWriter writer = json.jsonWriter(output);
      writer.startObject();
      writer.propertyName("c");
      // append the nested content
      while (reader.hasNext()) {
       writer.append(reader.next());
      }
      writer.endObject();
      System.out.println(output); // emits: {"c":{"a":"b"}}

Author:
  cdivilly

- Interface Summary
  Interface | Description
  --- | ---
  JSONReader | Reads a stream of `JSONToken` instances from an underlying character stream, using the `Iterator` pattern.
  JSONStreams | Service for generating readable and writable JSON streams from character streams.
  JSONToken | A token in a JSON character stream.
  JSONWriter | Writes JSON content to a character stream.

- Enum Summary
  Enum | Description
  --- | ---
  JSONToken.Type | Enumerates the different kinds of tokens that occur in a JSON stream

- Exception Summary
  Exception | Description
  --- | ---
  JSONIOException | An unchecked exception raised whenever a checked `IOException` is encountered on the underlying stream that the JSON API is operating on.