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>`, `Iterable<Map.Entry<String,FieldValue>>`

public class MapValue extends FieldValue implements Iterable<Map.Entry<String,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.

MapValue does not support put of Java null values. If a "null" JSON value is desired it is possible to put a `NullValue` instance using "put(fieldName, NullValue.getInstance())"

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

  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)`
  `boolean`
  `contains(String name)`
  Returns true if the specified field exists in the map
  `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()`
  `Iterator<Map.Entry<String,FieldValue>>`
  `iterator()`
  Returns an iterator over the entry set.
  `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`

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

  `forEach, spliterator`

- ## Constructor Details

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

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

  - ### iterator

    public Iterator<Map.Entry<String,FieldValue>> iterator()
    Returns an iterator over the entry set.
    Specified by:
      `iterator` in interface `Iterable<Map.Entry<String,FieldValue>>`
    Returns:
      the iterator
    Since:
      5.4

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

  - ### contains

    public boolean contains(String name)
    Returns true if the specified field exists in the map
    Parameters:
      `name` - the name of the field
    Returns:
      true if the field exists, false if not
    Since:
      5.4

  - ### 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)
    Specified by:
      `compareTo` in interface `Comparable<FieldValue>`

  - ### equals

    public boolean equals(Object other)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`