Package oracle.nosql.driver.values

## Interface FieldValueEventHandler

-     public interface FieldValueEventHandler

  FieldValueEventHandler is an event-driven interface that allows multiple implementations of serializers and deserializers for a `FieldValue`. The events correspond to the data model exposed by `FieldValue`.

  Events can be generated from `FieldValue` instances themselves, from a wire protocol, or from a generic program. Examples of uses include

  - Binary serializer for the wire protocol, capturing events generated from a `FieldValue` instances
  - Binary de-serializer for the wire protocol, capturing events generated from code that is reading the wire protocol
  - JSON serializer for `FieldValue` instances
  - JSON pretty-printfor `FieldValue` instances
  - Direct-from/to-object serializer or deserializer that operates on POJOs intead of `FieldValue`
  In addition to the interface this file includes static methods to generate events from a `FieldValue` instance. See `generate(oracle.nosql.driver.values.FieldValue, oracle.nosql.driver.values.FieldValueEventHandler)`.

  Example usage

         MapValue map = new MapValue();
         map.put(...);
         ...
         JsonSerializer js = new JsonSerializer(null);
         FieldValueEventHandler.generate(map, js);
         String json = js.toString();

  Functionally here is how the event handler is to be used. Look at the `generate(oracle.nosql.driver.values.FieldValue, oracle.nosql.driver.values.FieldValueEventHandler)` method for implementation details. There are no specific start/end events, although they could be added if deemed useful.

  Simple (atomic) field value events are just that, e.g.

         booleanValue(true);
         integerValue(6);

  Map values have startMap and endMap events that surround them. These methods have a size argument to let the event handler know the size of the map. It's possible that the size is not known but it's best to provide one if possible, and in some cases (protocol serialization) it's required. Map entries require key and value, where the value may be a nested map or array. To account for nesting the events are:

         startMap(1)
         startMapField(key) // pass the key String
         // an event that creates a value, including a nested map or array
         stringValue("a string")
         endMapField()
         endMap(1)

  Array values have startArray and endArray events that surround them. These methods have a size argument to let the event handler know the size of the array. It's possible that the size is not known but it's best to provide one if possible, and in some cases (protocol serialization) it's required. Array entry events are followed with endArrayField events. This simplifies implementations that need to know if they are working within an array. Here's an array example.

         startArray(2)
         startMap(msize) // nested map
         endMap(msize)   // map is empty
         endArrayField()
         stringValue("a string") // add string to the array
         endArrayField()
         endArray(2)

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `binaryValue​(byte[] byteArray)` | A binary value
    `void` | `booleanValue​(boolean value)` | A boolean value
    `void` | `doubleValue​(double value)` | A double value
    `void` | `emptyValue()` | An EmptyValue
    `void` | `endArray​(int size)` | End an ArrayValue.
    `void` | `endArrayField()` | End a field in an array.
    `void` | `endMap​(int size)` | End a MapValue.
    `void` | `endMapField()` | End a field in a map.
    `static void` | `generate​(FieldValue value, FieldValueEventHandler handler)` | Generates events from a `FieldValue` instance sending them to the `FieldValueEventHandler` provided.
    `static void` | `generateForArray​(ArrayValue array, FieldValueEventHandler handler)` | Generates events for `ArrayValue` sending them to the specified `FieldValueEventHandler`.
    `static void` | `generateForMap​(MapValue map, FieldValueEventHandler handler)` | Generates events for `MapValue` sending them to the specified `FieldValueEventHandler`.
    `void` | `integerValue​(int value)` | An integer value
    `void` | `jsonNullValue()` | A JsonNullValue
    `void` | `longValue​(long value)` | A long value
    `void` | `nullValue()` | A NullValue
    `void` | `numberValue​(BigDecimal value)` | A Number value.
    `void` | `startArray​(int size)` | Start an ArrayValue.
    `void` | `startMap​(int size)` | Start a MapValue.
    `void` | `startMapField​(String key)` | Start a field in a map.
    `void` | `stringValue​(String value)` | A String value
    `void` | `timestampValue​(TimestampValue timestamp)` | A Timestamp value

- - ### Method Detail

    - #### startMap

          void startMap​(int size)
                 throws IOException

      Start a MapValue. This method accepts the size of the map, but there are situations where the size may not be known. In this case -1 should be passed and it is up to the implementing class to decide if it can operate without a size and if not, throw IllegalArgumentException.
      Parameters:
        `size` - the number of entries in the map or -1 if not known.
      Throws:
        `IllegalArgumentException` - if the size is invalid or cannot be handled by the implementation.
        `IOException` - conditionally, based on implementation

    - #### startArray

          void startArray​(int size)
                   throws IOException

      Start an ArrayValue. This method accepts the size of the array, but there are situations where the size may not be known. In this case -1 should be passed and it is up to the implementing class to decide if it can operate without a size and if not, throw IllegalArgumentException.
      Parameters:
        `size` - the number of entries in the array or -1 if not known.
      Throws:
        `IllegalArgumentException` - if the size is invalid or cannot be handled by the implementation.
        `IOException` - conditionally, based on implementation

    - #### endMap

          void endMap​(int size)
               throws IOException

      End a MapValue.
      Parameters:
        `size` - the number of entries in the map or -1 if not known.
      Throws:
        `IOException` - conditionally, based on implementation

    - #### endArray

          void endArray​(int size)
                 throws IOException

      End an ArrayValue.
      Parameters:
        `size` - the number of entries in the array or -1 if not known.
      Throws:
        `IOException` - conditionally, based on implementation

    - #### startMapField

          void startMapField​(String key)
                      throws IOException

      Start a field in a map.
      Parameters:
        `key` - the key of the field.
      Throws:
        `IOException` - conditionally, based on implementation

    - #### endMapField

          void endMapField()
                    throws IOException

      End a field in a map.
      Throws:
        `IOException` - conditionally, based on implementation

    - #### endArrayField

          void endArrayField()
                      throws IOException

      End a field in an array. There is no corresponding start for array entries. This allows, for example, JSON serializers to insert array value separators without the complexity of tracking the entire event sequence.
      Throws:
        `IOException` - conditionally, based on implementation

    - #### booleanValue

          void booleanValue​(boolean value)
                     throws IOException

      A boolean value
      Parameters:
        `value` - the value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### binaryValue

          void binaryValue​(byte[] byteArray)
                    throws IOException

      A binary value
      Parameters:
        `byteArray` - the byte[] value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### stringValue

          void stringValue​(String value)
                    throws IOException

      A String value
      Parameters:
        `value` - the value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### integerValue

          void integerValue​(int value)
                     throws IOException

      An integer value
      Parameters:
        `value` - the value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### longValue

          void longValue​(long value)
                  throws IOException

      A long value
      Parameters:
        `value` - the value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### doubleValue

          void doubleValue​(double value)
                    throws IOException

      A double value
      Parameters:
        `value` - the value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### numberValue

          void numberValue​(BigDecimal value)
                    throws IOException

      A Number value.
      Parameters:
        `value` - the value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### timestampValue

          void timestampValue​(TimestampValue timestamp)
                       throws IOException

      A Timestamp value
      Parameters:
        `timestamp` - the value
      Throws:
        `IOException` - conditionally, based on implementation

    - #### jsonNullValue

          void jsonNullValue()
                      throws IOException

      A JsonNullValue
      Throws:
        `IOException` - conditionally, based on implementation

    - #### nullValue

          void nullValue()
                  throws IOException

      A NullValue
      Throws:
        `IOException` - conditionally, based on implementation

    - #### emptyValue

          void emptyValue()
                   throws IOException

      An EmptyValue
      Throws:
        `IOException` - conditionally, based on implementation

    - #### generate

          static void generate​(FieldValue value,
                               FieldValueEventHandler handler)
                        throws IOException

      Generates events from a `FieldValue` instance sending them to the `FieldValueEventHandler` provided.
      Parameters:
        `value` - the FieldValue used to generate events
        `handler` - the handler to use
      Throws:
        `IOException` - conditionally, based on implementation

    - #### generateForMap

          static void generateForMap​(MapValue map,
                                     FieldValueEventHandler handler)
                              throws IOException

      Generates events for `MapValue` sending them to the specified `FieldValueEventHandler`.
      Parameters:
        `map` - the MapValue to use
        `handler` - the handler to use
      Throws:
        `IOException` - conditionally, based on implementation

    - #### generateForArray

          static void generateForArray​(ArrayValue array,
                                       FieldValueEventHandler handler)
                                throws IOException

      Generates events for `ArrayValue` sending them to the specified `FieldValueEventHandler`.
      Parameters:
        `array` - the ArrayValue to use
        `handler` - the handler to use
      Throws:
        `IOException` - conditionally, based on implementation