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.