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