Package oracle.nosql.driver.values

## Class MapValue

- java.lang.Object
- - oracle.nosql.driver.values.FieldValue
  - - oracle.nosql.driver.values.MapValue

- All Implemented Interfaces:
    `Comparable<FieldValue>`

      public class MapValue
      extends FieldValue

  MapValue represents a row in a NoSQL Database table. A top-level row is always a MapValue instance that contains `FieldValue` objects which may be atomic types or embedded MapValue or `ArrayValue` instances, creating a structured row.

  MapValue is also used to represent key values used in get operations as well as nested maps or records within a row.

  Field names in a MapValue follow the same rules as Java `Map`, meaning that they are case-sensitive string values with no duplicates. On input MapValues of any structure can be created, but when put into a table they must conform to the schema of the target table or an exception will be thrown. Note that in the context of a RECORD field in a table schema field names are treated as case-insensitive. If a MapValue represents JSON, field names are case-sensitive.

  When a MapValue is received on output the value will always conform to the schema of the table from which the value was received or the implied schema of a query projection.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class oracle.nosql.driver.values.FieldValue

      `FieldValue.Type`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MapValue()` | Creates an empty MapValue instance
    `MapValue​(boolean keepInsertionOrder, int size)` | Creates an empty MapValue instance
    `MapValue​(int size)` | Creates an empty MapValue instance using the specified initial capacity

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `MapValue` | `addAll​(Iterator<Map.Entry<String,​FieldValue>> iter)` | Inserts all of the entries in the specified iterator into the map.
    `MapValue` | `addAll​(Stream<Map.Entry<String,​FieldValue>> stream)` | Inserts all of the entries in the specified stream into the map.
    `int` | `compareTo​(FieldValue other)` |
    `void` | `convertEmptyToNull()` |
    `Set<Map.Entry<String,​FieldValue>>` | `entrySet()` | Returns a `Set` of entries based on the underlying map that holds the values.
    `boolean` | `equals​(Object other)` |
    `FieldValue` | `get​(String name)` | Returns the field the specified name, or null if the field does not exist.
    `byte[]` | `getBinary​(String name)` | Gets the named field as a binary value
    `boolean` | `getBoolean​(String name)` | Gets the named field as a boolean
    `double` | `getDouble​(String name)` | Gets the named field as a double
    `int` | `getInt​(String name)` | Gets the named field as an integer
    `long` | `getLong​(String name)` | Gets the named field as a long
    `Map<String,​FieldValue>` | `getMap()` | Returns a live `Map` of the MapValue state.
    `BigDecimal` | `getNumber​(String name)` | Gets the named field as a BigDecimal
    `String` | `getString​(String name)` | Gets the named field as a String
    `Timestamp` | `getTimestamp​(String name)` | Gets the named field as a long timestamp representing the milliseconds since January 1, 1970
    `FieldValue.Type` | `getType()` | Returns the type of the object
    `FieldValue.Type` | `getType​(String name)` | Returns the type of the field with the specified name, or null if the field does not exist.
    `int` | `hashCode()` |
    `MapValue` | `put​(String name, boolean value)` | Sets the named field as a BooleanValue.
    `MapValue` | `put​(String name, byte[] value)` | Sets the named field as a BinaryValue.
    `MapValue` | `put​(String name, double value)` | Sets the named field as a DoubleValue.
    `MapValue` | `put​(String name, int value)` | Sets the named field as an IntegerValue.
    `MapValue` | `put​(String name, long value)` | Sets the named field as a LongValue.
    `MapValue` | `put​(String name, String value)` | Sets the named field as a StringValue.
    `MapValue` | `put​(String name, BigDecimal value)` | Sets the named field as a NumberValue.
    `MapValue` | `put​(String name, Timestamp value)` | Sets the named field as a TimestampValue.
    `MapValue` | `put​(String name, FieldValue value)` | Sets the named field.
    `MapValue` | `putFromJson​(String name, String jsonString, JsonOptions options)` | Sets the named field based on the JSON string provided.
    `FieldValue` | `remove​(String name)` | Removes the named field if it exists.
    `int` | `size()` | Returns the number of entries in the map.
    `Collection<FieldValue>` | `values()` | Returns a `Collection` of `FieldValue` instances contained in this map.

    - ### Methods inherited from class oracle.nosql.driver.values.FieldValue

      `asArray, asBinary, asBoolean, asDouble, asInteger, asJsonNull, asLong, asMap, asNull, asNumber, asString, asTimestamp, castAsDouble, createFromJson, createFromJson, createFromJson, getBinary, getBoolean, getDouble, getInt, getLong, getNumber, getSerializedSize, getString, getTimestamp, isAnyNull, isArray, isAtomic, isBinary, isBoolean, isDouble, isInteger, isJsonNull, isLong, isMap, isNull, isNumber, isNumeric, isString, isTimestamp, toJson, toJson, toString`

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### MapValue

          public MapValue()

      Creates an empty MapValue instance

    - #### MapValue

          public MapValue​(boolean keepInsertionOrder,
                          int size)

      Creates an empty MapValue instance
      Parameters:
        `keepInsertionOrder` - if true a map is created that maintains insertion order. This is the default for get and query results.
        `size` - the initial capacity of the map

    - #### MapValue

          public MapValue​(int size)

      Creates an empty MapValue instance using the specified initial capacity
      Parameters:
        `size` - the initial capacity

  - ### Method Detail

    - #### getType

          public FieldValue.Type getType()

      Description copied from class: `FieldValue`
      Returns the type of the object
      Specified by:
        `getType` in class `FieldValue`
      Returns:
        the type

    - #### getMap

          public Map<String,​FieldValue> getMap()

      Returns a live `Map` of the MapValue state.
      Returns:
        the map

    - #### entrySet

          public Set<Map.Entry<String,​FieldValue>> entrySet()

      Returns a `Set` of entries based on the underlying map that holds the values.
      Returns:
        the set

    - #### size

          public int size()

      Returns the number of entries in the map.
      Returns:
        the size

    - #### values

          public Collection<FieldValue> values()

      Returns a `Collection` of `FieldValue` instances contained in this map.
      Returns:
        the values

    - #### addAll

          public MapValue addAll​(Iterator<Map.Entry<String,​FieldValue>> iter)

      Inserts all of the entries in the specified iterator into the map.
      Parameters:
        `iter` - the iterator
      Returns:
        this

    - #### addAll

          public MapValue addAll​(Stream<Map.Entry<String,​FieldValue>> stream)

      Inserts all of the entries in the specified stream into the map.
      Parameters:
        `stream` - the stream
      Returns:
        this

    - #### getType

          public FieldValue.Type getType​(String name)

      Returns the type of the field with the specified name, or null if the field does not exist.
      Parameters:
        `name` - the name of the field
      Returns:
        the type of the field, or null if it does not exist.

    - #### get

          public FieldValue get​(String name)

      Returns the field the specified name, or null if the field does not exist.
      Parameters:
        `name` - the name of the field
      Returns:
        the field, or null if it does not exist.

    - #### put

          public MapValue put​(String name,
                              FieldValue value)

      Sets the named field. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              int value)

      Sets the named field as an IntegerValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              long value)

      Sets the named field as a LongValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              double value)

      Sets the named field as a DoubleValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              BigDecimal value)

      Sets the named field as a NumberValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              String value)

      Sets the named field as a StringValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              boolean value)

      Sets the named field as a BooleanValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              byte[] value)

      Sets the named field as a BinaryValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### put

          public MapValue put​(String name,
                              Timestamp value)

      Sets the named field as a TimestampValue. Any existing entry is silently overwritten.
      Parameters:
        `name` - the name of the field
        `value` - the value to set
      Returns:
        this

    - #### putFromJson

          public MapValue putFromJson​(String name,
                                      String jsonString,
                                      JsonOptions options)

      Sets the named field based on the JSON string provided. Any existing entry is silently overridden. The type of the field created is inferred from the JSON.
      Parameters:
        `name` - the name of the field
        `jsonString` - a JSON formatted String
        `options` - configurable options used to affect the JSON output format of some data types. May be null.
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if the string is not valid JSON

    - #### remove

          public FieldValue remove​(String name)

      Removes the named field if it exists.
      Parameters:
        `name` - the name of the field
      Returns:
        the previous value if it existed, otherwise null

    - #### getInt

          public int getInt​(String name)

      Gets the named field as an integer
      Parameters:
        `name` - the name of the field
      Returns:
        the integer value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### getLong

          public long getLong​(String name)

      Gets the named field as a long
      Parameters:
        `name` - the name of the field
      Returns:
        the long value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### getDouble

          public double getDouble​(String name)

      Gets the named field as a double
      Parameters:
        `name` - the name of the field
      Returns:
        the double value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### getNumber

          public BigDecimal getNumber​(String name)

      Gets the named field as a BigDecimal
      Parameters:
        `name` - the name of the field
      Returns:
        the BigDecimal value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### getString

          public String getString​(String name)

      Gets the named field as a String
      Parameters:
        `name` - the name of the field
      Returns:
        the String value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### getBoolean

          public boolean getBoolean​(String name)

      Gets the named field as a boolean
      Parameters:
        `name` - the name of the field
      Returns:
        the boolean value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### getBinary

          public byte[] getBinary​(String name)

      Gets the named field as a binary value
      Parameters:
        `name` - the name of the field
      Returns:
        the binary value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### getTimestamp

          public Timestamp getTimestamp​(String name)

      Gets the named field as a long timestamp representing the milliseconds since January 1, 1970
      Parameters:
        `name` - the name of the field
      Returns:
        the timestamp value
      Throws:
        `IllegalArgumentException` - if the field does not exist.
        `ClassCastException` - if the field cannot be cast to the required type

    - #### compareTo

          public int compareTo​(FieldValue other)

    - #### equals

          public boolean equals​(Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### convertEmptyToNull

          public void convertEmptyToNull()