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 TypeClass
ARRAYArrayValue
BINARYBinaryValue
BOOLEAN BooleanValue
DOUBLE DoubleValue
ENUMStringValue
FIXED_BINARY BinaryValue
INTEGER IntegerValue
LONGLongValue
MAPMapValue
RECORDMapValue
STRINGStringValue
TIMESTAMP TimestampValue
NUMBERNumberValue

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 TypeClass
ARRAYArrayValue
BOOLEAN BooleanValue
NUMBEROne of the numeric values
OBJECTMapValue
STRINGStringValue

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.

  • Class
    Description
    ArrayValue represents an array of FieldValue instances.
    A FieldValue instance representing a binary value.
    A FieldValue instance representing a boolean value.
    A FieldValue instance representing a double value.
    FieldValue is the base class of all data items in the Oracle NoSQL Database Cloud system.
    The type of a field.
    A FieldValue instance representing an integer value.
    A FieldValue instance representing an explicit JSON null value in a JSON object or array.
    JsonOptions allows applications to configure how JSON is parsed on input and generated on output.
    JsonReader reads a file or string that has JSON objects in it that may represent rows and makes them available using the Iterable interface.
    A FieldValue instance representing a long value.
    MapValue represents a row in a NoSQL Database table.
    A FieldValue instance representing a null or missing value in a fully-typed schema.
    A FieldValue instance representing an arbitrary-precision numeric value.
    A FieldValue instance representing a string value.
    A FieldValue instance representing a timestamp value.