Package oracle.nosql.driver.values

Class FieldValue

  • All Implemented Interfaces:
    java.lang.Comparable<FieldValue>
    Direct Known Subclasses:
    ArrayValue, BinaryValue, BooleanValue, DoubleValue, IntegerValue, JsonNullValue, LongValue, MapValue, NullValue, NumberValue, StringValue, TimestampValue
    public abstract class FieldValue
extends java.lang.Object
implements java.lang.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 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​(java.io.InputStream jsonInput, JsonOptions options)
      Constructs a new FieldValue instance based on JSON read from the InputStream provided.
      static FieldValue createFromJson​(java.io.Reader jsonInput, JsonOptions options)
      Constructs a new FieldValue instance based on JSON read from the Reader provided.
      static FieldValue createFromJson​(java.lang.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
      double getDouble()
      Returns a double value for the field if the value is a DoubleValue
      int getInt()
      Returns an integer value for the field if the value is an IntegerValue
      long getLong()
      Returns a long value for the field if the value is a LongValue or IntegerValue
      java.math.BigDecimal getNumber()
      Returns a BigDecimal value for the field if the value is numeric
      int getSerializedSize()
      Returns the serialized size of this value.
      java.lang.String getString()
      Returns a String value for the field if the value is a StringValue
      java.sql.Timestamp getTimestamp()
      Returns a TimestampValue as a Timestamp value.
      abstract FieldValue.Type getType()
      Returns the type of the object
      boolean isAtomic()
      Returns whether this is an atomic value, that is, not an array or map value.
      boolean isJsonNull()
      Returns whether this is a json null value.
      boolean isNull()
      Returns whether this is an SQL NULL value.
      boolean isNumeric()
      Returns whether this is a numeric value (integer, long, double, or number) value.
      java.lang.String toJson()
      Returns a JSON representation of the value using a default configuration for output format.
      java.lang.String toJson​(JsonOptions options)
      Returns a JSON representation of the value using the options, if specified.
      java.lang.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 is an IntegerValue
        Returns:
        an integer value
        Throws:
        java.lang.ClassCastException - if this is not an IntegerValue

      • getLong

        public long getLong()
        Returns a long value for the field if the value is a LongValue or IntegerValue
        Returns:
        a long value
        Throws:
        java.lang.ClassCastException - if the value cannot be cast to long without loss of precision

      • getDouble

        public double getDouble()
        Returns a double value for the field if the value is a DoubleValue
        Returns:
        a double value
        Throws:
        java.lang.ClassCastException - if this is not a DoubleValue

      • getNumber

        public java.math.BigDecimal getNumber()
        Returns a BigDecimal value for the field if the value is numeric
        Returns:
        a number value
        Throws:
        java.lang.ClassCastException - if this is not numeric

      • 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:
        java.lang.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:
        java.lang.ClassCastException - if this is not a BinaryValue

      • getBoolean

        public boolean getBoolean()
        Returns a boolean value for the field if the value is a boolean
        Returns:
        the boolean value
        Throws:
        java.lang.ClassCastException - if this is not a BooleanValue

      • getString

        public java.lang.String getString()
        Returns a String value for the field if the value is a StringValue
        Returns:
        a String value
        Throws:
        java.lang.ClassCastException - if this is not a StringValue

      • getTimestamp

        public java.sql.Timestamp getTimestamp()
        Returns a TimestampValue as a Timestamp value.
        Returns:
        a Timestamp value
        Throws:
        java.lang.ClassCastException - if this is not a Timestamp

      • asInteger

        public IntegerValue asInteger()
        Casts the object to IntegerValue.
        Returns:
        an IntegerValue
        Throws:
        java.lang.ClassCastException - if this is not an IntegerValue

      • asString

        public StringValue asString()
        Casts to StringValue.
        Returns:
        a StringValue
        Throws:
        java.lang.ClassCastException - if this is not a StringValue

      • asLong

        public LongValue asLong()
        Casts the object to LongValue.
        Returns:
        a LongValue
        Throws:
        java.lang.ClassCastException - if this is not a LongValue

      • asNumber

        public NumberValue asNumber()
        Casts the object to NumberValue.
        Returns:
        a NumberValue
        Throws:
        java.lang.ClassCastException - if this is not a NumberValue

      • asBoolean

        public BooleanValue asBoolean()
        Casts the object to BooleanValue.
        Returns:
        a BooleanValue
        Throws:
        java.lang.ClassCastException - if this is not a BooleanValue

      • asArray

        public ArrayValue asArray()
        Casts the object to ArrayValue.
        Returns:
        a ArrayValue
        Throws:
        java.lang.ClassCastException - if this is not a ArrayValue

      • asBinary

        public BinaryValue asBinary()
        Casts the object to BinaryValue.
        Returns:
        a BinaryValue
        Throws:
        java.lang.ClassCastException - if this is not a BinaryValue

      • asMap

        public MapValue asMap()
        Casts the object to MapValue.
        Returns:
        a MapValue
        Throws:
        java.lang.ClassCastException - if this is not a MapValue

      • asDouble

        public DoubleValue asDouble()
        Casts to DoubleValue.
        Returns:
        a DoubleValue
        Throws:
        java.lang.ClassCastException - if this is not a DoubleValue

      • asJsonNull

        public JsonNullValue asJsonNull()
        Casts to JsonNullValue.
        Returns:
        a JsonNullValue
        Throws:
        java.lang.ClassCastException - if this is not a JsonNullValue

      • asNull

        public NullValue asNull()
        Casts to NullValue.
        Returns:
        a NullValue
        Throws:
        java.lang.ClassCastException - if this is not a NullValue

      • 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:
        Whether this is an SQL NULL value.

      • isJsonNull

        public boolean isJsonNull()
        Returns whether this is a json null value.
        Returns:
        Whether this is a json null value.

      • toJson

        public java.lang.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 java.lang.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 java.lang.String toString()
        Returns a String representation of the value, consistent with representation as JSON strings.
        Overrides:
        toString in class java.lang.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​(java.lang.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​(java.io.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​(java.io.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