# Package oracle.nosql.driver.values

package oracle.nosql.driver.values
The classes in this package are used to represent and manipulate data in the Oracle NoSQL Database. A table is defined using a fixed schema that describes the data that table will hold. All data classes in this package are instances of `FieldValue`. There is a well-defined mapping between a table row and instances of `FieldValue`. For example a row is mapped to a `MapValue`, which is a simple map of `FieldValue` instances, keyed by a string.

The classes in this package do not have access to the table schema, which means applications must be written knowing the schema. On input the constructed data is validated against the table schema and if it does not conform and exception is thrown.

The mappings between driver types and database types
Database Type | Class
--- | ---
ARRAY | `ArrayValue`
BINARY | `BinaryValue`
BOOLEAN | `BooleanValue`
DOUBLE | `DoubleValue`
ENUM | `StringValue`
FIXED_BINARY | `BinaryValue`
INTEGER | `IntegerValue`
LONG | `LongValue`
MAP | `MapValue`
RECORD | `MapValue`
STRING | `StringValue`
TIMESTAMP | `TimestampValue`
NUMBER | `NumberValue`

Note that there are several database types that do not have direct equivalents. These are the types that require schema for their definition:

- ENUM. Enumerations require a schema. When an application fetches a row with an enumeration its value will be mapped to StringValue. On input, a StringValue must be created to represent an ENUM
- FIXED_BINARY. This is a specialization of binary that uses a fixed number of bytes. It is mapped to BinaryValue that is validated on input.
- RECORD. This is a fixed-schema map. In this package it is represented as a MapValue, which is more flexible, but is validated on input.

The database types of MAP and ARRAY are fixed-type in that they contain a single type, for example a MAP of INTEGER. `MapValue` and `ArrayValue` are not fixed-type. On input the types of the elements of these collections must match the schema.

JSON Mappings

ArrayValue are not fixed-type. On input the types of the elements of these collections must match the schema.

JSON Mappings

JSON is commonly used as a format for data and there are also well-defined mappings between JSON types and `FieldValue` instances in this package. It is a common pattern to construct a row (MapValue) from JSON and generate JSON from a row. Methods on these classes make this pattern easy to use.

Because the data model supported in this package is richer than JSON it is necessary to define potentially ambiguous mappings as well as provide the ability to affect mappings that are flexible. The following table defines the mappings from JSON types to instances of `FieldValue`.

Mappings from JSON to driver types
JSON Type | Class
--- | ---
ARRAY | `ArrayValue`
BOOLEAN | `BooleanValue`
NUMBER | One of the numeric values
OBJECT | `MapValue`
STRING | `StringValue`

There are several situations that require further descriptions. First, JSON has only a single numeric type. By default JSON numbers will be mapped to the most appropriate numeric type (IntegerValue, LongValue, DoubleValue, NumberValue). For example if the number is a valid Java integer it will be an IntegerValue. If it is a valid Java long it is mapped to LongValue. Floating point numbers are generally mapped to DoubleValue. If the JSON numeric cannot fit in a long or double then it is mapped to NumberValue which an hold any numeric value, but at some additional cost.

There is optional configuration that allows applications to control these numeric mappings in the following ways:

- Default numeric mappings (best fit) on input
- Map all numbers into NumberValue on input
- On output, represent Timestamp as a String
- On output, represent Timestamp as a long

`FieldValue` instances are not thread-safe and are not intended to be shared.

- Related Packages
  Package
  Description
  oracle.nosql.driver
  Contains the public API for using the Oracle NoSQL Database as well as configuration and common parameter classes used in database operations.
  oracle.nosql.driver.iam
  This package contains the public API for managing security for the Oracle NoSQL Database Cloud using Oracle Cloud Infrastructure Identity and Access Management (IAM).
  oracle.nosql.driver.kv
  This package contains classes that are specific to using the driver on-premises and not applicable to the Cloud Service.
  oracle.nosql.driver.ops
  Contains the input and response classes used for Oracle NoSQL Database operations.
- Class
  Description
  ArrayValue
  ArrayValue represents an array of `FieldValue` instances.
  BinaryValue
  A `FieldValue` instance representing a binary value.
  BooleanValue
  A `FieldValue` instance representing a boolean value.
  DoubleValue
  A `FieldValue` instance representing a double value.
  FieldValue
  FieldValue is the base class of all data items in the Oracle NoSQL Database Cloud system.
  FieldValue.Type
  The type of a field.
  IntegerValue
  A `FieldValue` instance representing an integer value.
  JsonNullValue
  A `FieldValue` instance representing an explicit JSON null value in a JSON object or array.
  JsonOptions
  JsonOptions allows applications to configure how JSON is parsed on input and generated on output.
  JsonReader
  JsonReader reads a file or string that has JSON objects in it that may represent rows and makes them available using the Iterable interface.
  LongValue
  A `FieldValue` instance representing a long value.
  MapValue
  MapValue represents a row in a NoSQL Database table.
  NullValue
  A `FieldValue` instance representing a null or missing value in a fully-typed schema.
  NumberValue
  A `FieldValue` instance representing an arbitrary-precision numeric value.
  StringValue
  A `FieldValue` instance representing a string value.
  TimestampValue
  A `FieldValue` instance representing a timestamp value.