# 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 (e.g. via `NoSQLHandle.put(oracle.nosql.driver.ops.PutRequest)`) 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.

- Interface Summary
  Interface | Description
  --- | ---
  FieldValueEventHandler | FieldValueEventHandler is an event-driven interface that allows multiple implementations of serializers and deserializers for a `FieldValue`.

- Class Summary
  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.
  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.

- Enum Summary
  Enum | Description
  --- | ---
  FieldValue.Type | The type of a field.