Package oracle.nosql.driver.values

## Class FieldValue

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

- All Implemented Interfaces:
    `Comparable<FieldValue>`
  Direct Known Subclasses:
    `ArrayValue`, `BinaryValue`, `BooleanValue`, `DoubleValue`, `IntegerValue`, `JsonNullValue`, `LongValue`, `MapValue`, `NullValue`, `NumberValue`, `StringValue`, `TimestampValue`

      public abstract class FieldValue
      extends Object
      implements Comparable<FieldValue>

  FieldValue is the base class of all data items in the Oracle NoSQL Database Cloud system. Each data item is an instance of FieldValue allowing access to its type and its value as well as additional utility methods that operate on FieldValue.

  FieldValue instances are typed, based on the `FieldValue.Type` enumeration. The type system is similar to that of JSON with extensions. It is a subset of the database types in Oracle NoSQL Database in that these objects do not inherently conform to a fixed schema and some of the database types, such as RECORD and ENUM, require a schema. The mappings of types is described here and is not reproduced in this documentation.

  FieldValue instances used for put operations are not validated against the target table schema in the driver. Validation happens where the table schema is available. If an instance does not match the target table an exception is thrown.

  Returned FieldValue instances always conform to a table schema, or to the shape implied by a query projection.

  FieldValue instances are created in several ways:

  - From JSON input. In this path the JSON is parsed and mapped to correspondings types.
  - Construction. Applications can construct instances manually, adding and setting fields and types as needed. This mechanism can be more efficient than parsing from JSON and it gives the application more control over the types used when the mapping from JSON may not be precise.
  - Returned by operations on a table. These instances are created internally by operations that return data and will have the schema implied by the table or query.

  There are special cases for handling types that are not in the JSON type system when creating a FieldValue instance from JSON. These are described in the documentation for `createFromJson(java.lang.String, oracle.nosql.driver.values.JsonOptions)`.

  Numeric values are an extension to JSON which has only a single numeric type, Number. For this reason the system is generous in mapping numeric types among one another and will allow any lossless mapping without error. Mappings default to the most efficient valid format.

  FieldValue has convenience interfaces to return values of atomic types such as number, string, and boolean. These interfaces will allow implicit type coercions (e.g. integer to long) as long as the coercion is lossless; otherwise ClassCastException is thrown. The determination of lossless is based on both type and actual value. For example a long can return an integer value as long as the value of the long is a valid integer value. String coercions always work for atomic types but an atomic type value cannot always be returned from a string. MapValue, ArrayValue, and BinaryValue cannot be coerced. BooleanValue can only be coerced to and from StringValue. If a coercion that can result in loss of information is desired it should be done manually by the application.

  FieldValue instances are not thread-safe. On input, they should not be reused until the operation that uses them has returned.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `FieldValue.Type` | The type of a field.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FieldValue()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ArrayValue` | `asArray()` | Casts the object to ArrayValue.
    `BinaryValue` | `asBinary()` | Casts the object to BinaryValue.
    `BooleanValue` | `asBoolean()` | Casts the object to BooleanValue.
    `DoubleValue` | `asDouble()` | Casts to DoubleValue.
    `IntegerValue` | `asInteger()` | Casts the object to IntegerValue.
    `JsonNullValue` | `asJsonNull()` | Casts to JsonNullValue.
    `LongValue` | `asLong()` | Casts the object to LongValue.
    `MapValue` | `asMap()` | Casts the object to MapValue.
    `NullValue` | `asNull()` | Casts to NullValue.
    `NumberValue` | `asNumber()` | Casts the object to NumberValue.
    `StringValue` | `asString()` | Casts to StringValue.
    `TimestampValue` | `asTimestamp()` | Casts the object to TimestampValue.
    `double` | `castAsDouble()` | Casts a numeric value to double, possibly with loss of information about magnitude, precision or sign.
    `static FieldValue` | `createFromJson​(InputStream jsonInput, JsonOptions options)` | Constructs a new FieldValue instance based on JSON read from the InputStream provided.
    `static FieldValue` | `createFromJson​(Reader jsonInput, JsonOptions options)` | Constructs a new FieldValue instance based on JSON read from the Reader provided.
    `static FieldValue` | `createFromJson​(String jsonInput, JsonOptions options)` | Constructs a new FieldValue instance based on the JSON string provided.
    `byte[]` | `getBinary()` | Returns a binary byte array value for the field if the value is binary
    `boolean` | `getBoolean()` | Returns a boolean value for the field if the value is a boolean or a string.
    `double` | `getDouble()` | Returns a double value for the field if the value can be represented as a valid double without loss of information.
    `int` | `getInt()` | Returns an integer value for the field if the value can be represented as a valid integer without loss of information.
    `long` | `getLong()` | Returns a long value for the field if the value can be represented as a valid long without loss of information.
    `BigDecimal` | `getNumber()` | Returns a BigDecimal value for the field if the value can be represented as a valid BigDecimal without loss of information.
    `int` | `getSerializedSize()` | Returns the serialized size of this value.
    `String` | `getString()` | Returns a String value for the field.
    `Timestamp` | `getTimestamp()` | Returns a TimestampValue as a `Timestamp` value.
    `abstract FieldValue.Type` | `getType()` | Returns the type of the object
    `boolean` | `isAnyNull()` | Returns whether this is either a JSON null or a SQL NULL value.
    `boolean` | `isArray()` | Returns whether this is an ArrayValue
    `boolean` | `isAtomic()` | Returns whether this is an atomic value, that is, not an array or map value.
    `boolean` | `isBinary()` | Returns whether this is an BinaryValue
    `boolean` | `isBoolean()` | Returns whether this is an BooleanValue
    `boolean` | `isDouble()` | Returns whether this is an DoubleValue
    `boolean` | `isInteger()` | Returns whether this is an IntegerValue
    `boolean` | `isJsonNull()` | Returns whether this is a json null value.
    `boolean` | `isLong()` | Returns whether this is an LongValue
    `boolean` | `isMap()` | Returns whether this is an MapValue
    `boolean` | `isNull()` | Returns whether this is an SQL NULL value.
    `boolean` | `isNumber()` | Returns whether this is an NumberValue
    `boolean` | `isNumeric()` | Returns whether this is a numeric value (integer, long, double, or number) value.
    `boolean` | `isString()` | Returns whether this is an StringValue
    `boolean` | `isTimestamp()` | Returns whether this is an TimestampValue
    `String` | `toJson()` | Returns a JSON representation of the value using a default configuration for output format.
    `String` | `toJson​(JsonOptions options)` | Returns a JSON representation of the value using the options, if specified.
    `String` | `toString()` | Returns a String representation of the value, consistent with representation as JSON strings.

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

- - ### Constructor Detail

    - #### FieldValue

          public FieldValue()

  - ### Method Detail

    - #### getType

          public abstract FieldValue.Type getType()

      Returns the type of the object
      Returns:
        the type

    - #### getInt

          public int getInt()

      Returns an integer value for the field if the value can be represented as a valid integer without loss of information. Numbers are coerced using Java rules and strings are parsed according to Java rules.
      Returns:
        an integer value
      Throws:
        `ClassCastException` - if the coercion cannot be performed based on the type of the value
        `ArithmeticException` - if a numeric coercion would lose information
        `NumberFormatException` - if the underlying type is a StringValue and it cannot be coerced

    - #### getLong

          public long getLong()

      Returns a long value for the field if the value can be represented as a valid long without loss of information. Numbers are coerced using Java rules and strings are parsed according to Java rules.
      Returns:
        a long value
      Throws:
        `ClassCastException` - if the coercion cannot be performed without loss of information
        `NumberFormatException` - if the underlying type is a StringValue and it cannot be coerced

    - #### getDouble

          public double getDouble()

      Returns a double value for the field if the value can be represented as a valid double without loss of information. Numbers are coerced using Java rules and strings are parsed according to Java rules.
      Returns:
        a double value
      Throws:
        `ClassCastException` - if the coercion cannot be performed without loss of information
        `NumberFormatException` - if the underlying type is a StringValue and it cannot be coerced

    - #### getNumber

          public BigDecimal getNumber()

      Returns a BigDecimal value for the field if the value can be represented as a valid BigDecimal without loss of information. Numbers are coerced using Java rules and strings are parsed according to Java rules.
      Returns:
        a BigDecimal value
      Throws:
        `ClassCastException` - if the coercion cannot be performed without loss of information
        `NumberFormatException` - if the underlying type is a StringValue and it cannot be coerced

    - #### castAsDouble

          public double castAsDouble()

      Casts a numeric value to double, possibly with loss of information about magnitude, precision or sign.
      Returns:
        a double value
      Throws:
        `ClassCastException` - if this value is not numeric

    - #### getBinary

          public byte[] getBinary()

      Returns a binary byte array value for the field if the value is binary
      Returns:
        a byte array
      Throws:
        `ClassCastException` - if this is not a BinaryValue

    - #### getBoolean

          public boolean getBoolean()

      Returns a boolean value for the field if the value is a boolean or a string. If it is a StringValue the rules used for Java Boolean.parseBoolean() are applied.
      Returns:
        the boolean value
      Throws:
        `ClassCastException` - if this is not a BooleanValue or StringValue

    - #### getString

          public String getString()

      Returns a String value for the field. The String value cannot be created for MapValue, ArrayValue and BinaryValue. String values that are coerced use Java rules for representation.
      Returns:
        a String value
      Throws:
        `ClassCastException` - if this cannot be represented as a String

    - #### getTimestamp

          public Timestamp getTimestamp()

      Returns a TimestampValue as a `Timestamp` value.
      Returns:
        a Timestamp value
      Throws:
        `ClassCastException` - if this is not a TimestampValue

    - #### asInteger

          public IntegerValue asInteger()

      Casts the object to IntegerValue.
      Returns:
        an IntegerValue
      Throws:
        `ClassCastException` - if this is not an IntegerValue

    - #### asString

          public StringValue asString()

      Casts to StringValue.
      Returns:
        a StringValue
      Throws:
        `ClassCastException` - if this is not a StringValue

    - #### asLong

          public LongValue asLong()

      Casts the object to LongValue.
      Returns:
        a LongValue
      Throws:
        `ClassCastException` - if this is not a LongValue

    - #### asNumber

          public NumberValue asNumber()

      Casts the object to NumberValue.
      Returns:
        a NumberValue
      Throws:
        `ClassCastException` - if this is not a NumberValue

    - #### asTimestamp

          public TimestampValue asTimestamp()

      Casts the object to TimestampValue. This method accepts objects of type `FieldValue.Type.TIMESTAMP`, `FieldValue.Type.STRING`, `FieldValue.Type.INTEGER` and `FieldValue.Type.LONG`. In the case of `FieldValue.Type.STRING` the value is parsed as an ISO8601 timestamp value and if valid, accepted. In the numeric cases the value is interpreted as milliseconds since the Epoch, "1970-01-01T00:00:00".
      Returns:
        a TimestampValue
      Throws:
        `ClassCastException` - if this is not a TimestampValue

    - #### asBoolean

          public BooleanValue asBoolean()

      Casts the object to BooleanValue.
      Returns:
        a BooleanValue
      Throws:
        `ClassCastException` - if this is not a BooleanValue

    - #### asArray

          public ArrayValue asArray()

      Casts the object to ArrayValue.
      Returns:
        a ArrayValue
      Throws:
        `ClassCastException` - if this is not a ArrayValue

    - #### asBinary

          public BinaryValue asBinary()

      Casts the object to BinaryValue.
      Returns:
        a BinaryValue
      Throws:
        `ClassCastException` - if this is not a BinaryValue

    - #### asMap

          public MapValue asMap()

      Casts the object to MapValue.
      Returns:
        a MapValue
      Throws:
        `ClassCastException` - if this is not a MapValue

    - #### asDouble

          public DoubleValue asDouble()

      Casts to DoubleValue.
      Returns:
        a DoubleValue
      Throws:
        `ClassCastException` - if this is not a DoubleValue

    - #### asJsonNull

          public JsonNullValue asJsonNull()

      Casts to JsonNullValue.
      Returns:
        a JsonNullValue
      Throws:
        `ClassCastException` - if this is not a JsonNullValue

    - #### asNull

          public NullValue asNull()

      Casts to NullValue.
      Returns:
        a NullValue
      Throws:
        `ClassCastException` - if this is not a NullValue

    - #### isInteger

          public boolean isInteger()

      Returns whether this is an IntegerValue
      Returns:
        true if this FieldValue is of type IntegerValue, false otherwise

    - #### isLong

          public boolean isLong()

      Returns whether this is an LongValue
      Returns:
        true if this FieldValue is of type LongValue, false otherwise

    - #### isDouble

          public boolean isDouble()

      Returns whether this is an DoubleValue
      Returns:
        true if this FieldValue is of type DoubleValue, false otherwise

    - #### isNumber

          public boolean isNumber()

      Returns whether this is an NumberValue
      Returns:
        true if this FieldValue is of type NumberValue, false otherwise

    - #### isBinary

          public boolean isBinary()

      Returns whether this is an BinaryValue
      Returns:
        true if this FieldValue is of type BinaryValue, false otherwise

    - #### isBoolean

          public boolean isBoolean()

      Returns whether this is an BooleanValue
      Returns:
        true if this FieldValue is of type BooleanValue, false otherwise

    - #### isArray

          public boolean isArray()

      Returns whether this is an ArrayValue
      Returns:
        true if this FieldValue is of type ArrayValue, false otherwise

    - #### isMap

          public boolean isMap()

      Returns whether this is an MapValue
      Returns:
        true if this FieldValue is of type MapValue, false otherwise

    - #### isString

          public boolean isString()

      Returns whether this is an StringValue
      Returns:
        true if this FieldValue is of type StringValue, false otherwise

    - #### isTimestamp

          public boolean isTimestamp()

      Returns whether this is an TimestampValue
      Returns:
        true if this FieldValue is of type TimestampValue, false otherwise

    - #### isAtomic

          public boolean isAtomic()

      Returns whether this is an atomic value, that is, not an array or map value.
      Returns:
        Whether this is an atomic value.

    - #### isNumeric

          public boolean isNumeric()

      Returns whether this is a numeric value (integer, long, double, or number) value.
      Returns:
        Whether this is a numeri value.

    - #### isNull

          public boolean isNull()

      Returns whether this is an SQL NULL value.
      Returns:
        true if this FieldValue is of type NullValue, false otherwise

    - #### isJsonNull

          public boolean isJsonNull()

      Returns whether this is a json null value.
      Returns:
        true if this FieldValue is of type JsonNullValue, false otherwise

    - #### isAnyNull

          public boolean isAnyNull()

      Returns whether this is either a JSON null or a SQL NULL value.
      Returns:
        true if this FieldValue is of type NullValue or JsonNullValue, false otherwise

    - #### toJson

          public String toJson()

      Returns a JSON representation of the value using a default configuration for output format.
      Returns:
        the JSON representation of this value.

    - #### toJson

          public String toJson​(JsonOptions options)

      Returns a JSON representation of the value using the options, if specified.
      Parameters:
        `options` - configurable options used to affect the JSON output format of some data types. May be null.
      Returns:
        the JSON representation of this value.

    - #### toString

          public String toString()

      Returns a String representation of the value, consistent with representation as JSON strings.
      Overrides:
        `toString` in class `Object`
      Returns:
        the String value

    - #### getSerializedSize

          public int getSerializedSize()

      Returns the serialized size of this value. This value can be used to estimate amount of throughput used by a sample value. This size will always be larger than the actual space consumed because the server serializes in a more compact format.
      Returns:
        the size, in bytes, used by the serialized format of this value.

    - #### createFromJson

          public static FieldValue createFromJson​(String jsonInput,
                                                  JsonOptions options)

      Constructs a new FieldValue instance based on the JSON string provided.

      Two of the types in the driver type system are not part of the JSON data model -- TIMESTAMP and BINARY -- and will never be created using this method. If a table schema includes these types, as well as the ENUM type supported by Oracle NoSQL Database, they should be input as follows:

      - BINARY should be a Base64-encoded String
      - TIMESTAMP may be either a long value representing milliseconds since January 1, 1970, or a String value that is in a valid ISO 8601 formatted string.
      - ENUM should be a String that matches one of the valid enumeration values
      If one of these types is to be used inside a JSON data type, there is no schema in the database server and the type cannot be inferred by the system and interpretation is left to the application.
      Parameters:
        `jsonInput` - a JSON formatted String
        `options` - configurable options used to affect the JSON output format of some data types. May be null.
      Returns:
        a new FieldValue instance representing the JSON string
      Throws:
        `JsonParseException` - if the string is not valid JSON

    - #### createFromJson

          public static FieldValue createFromJson​(Reader jsonInput,
                                                  JsonOptions options)

      Constructs a new FieldValue instance based on JSON read from the Reader provided.
      Parameters:
        `jsonInput` - a Reader containing JSON
        `options` - configurable options used to affect the JSON output format of some data types. May be null.
      Returns:
        a new FieldValue instance representing the JSON string
      Throws:
        `JsonParseException` - if the input is not valid JSON

    - #### createFromJson

          public static FieldValue createFromJson​(InputStream jsonInput,
                                                  JsonOptions options)

      Constructs a new FieldValue instance based on JSON read from the InputStream provided.
      Parameters:
        `jsonInput` - an InputStream containing JSON
        `options` - configurable options used to affect the JSON output format of some data types. May be null.
      Returns:
        a new FieldValue instance representing the JSON string
      Throws:
        `JsonParseException` - if the input is not valid JSON