Package oracle.sql

## Class Datum

- java.lang.Object
- - oracle.sql.Datum

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `BINARY_DOUBLE`, `BINARY_FLOAT`, `CHAR`, `DATE`, `DatumWithConnection`, `INTERVALDS`, `INTERVALYM`, `NUMBER`, `OracleJsonDatum`, `RAW`, `ROWID`, `TIMESTAMP`, `TIMESTAMPLTZ`, `TIMESTAMPTZ`

    public abstract class Datum
    extends Object
    implements Serializable

The root of Oracle native datatype hierarchy.

Each subclass represents one of the native kernel datatypes.

In order to allow for possible optimization of data copying between SQL and Java, instances of subclasses are immutable.

Since:
  JDK1(Oracle)
See Also:
  Serialized Form

### Field Summary

Fields
`protected oracle.jdbc.internal.OracleDatumWithConnection` `ojiOracleDatumWithConnection`
`protected Datum` `targetDatum`

### Constructor Summary

Constructors
`Datum()` Creates an empty datum
`Datum​(byte[] newData)` Create a new datum with the given byte array as representation.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`InputStream` `asciiStreamValue()` Convert to an ascii stream representation of the datum object
`BigDecimal` `bigDecimalValue()` Convert to a BigDecimal representation of the datum object
`InputStream` `binaryStreamValue()` Convert to a binary stream representation of the datum object
`boolean` `booleanValue()` Convert to a boolean representation of the datum object
`protected boolean` `bytesEqual​(Datum other)`
`int` `bytesHashCode()`
`byte` `byteValue()` Convert to a byte representation of the datum object
`Reader` `characterStreamValue()` Convert to a character stream representation of the datum object
`static int` `compareBytes​(byte[] m, byte[] n)` Do an unsigned compare on byte arrays m and n
`Date` `dateValue()` Convert to a Date representation of the datum object
`double` `doubleValue()` Convert to a double representation of the datum object
`boolean` `equals​(Object obj)` Test any object for equality with an Datum.
`float` `floatValue()` Convert to a float representation of the datum object
`byte[]` `getBytes()` Create a new Java byte array containing a copy of the RDBMS data.
`protected oracle.jdbc.internal.OracleConnection` `getConnectionDuringExceptionHandling()`
`long` `getLength()` Retreive the length of a datum.
`InputStream` `getStream()` Create an input stream so the raw data may be read.
`int` `intValue()` Convert to a integer representation of the datum object
`abstract boolean` `isConvertibleTo​(Class<?> cls)` Determines if datum object can be converted to a particular class
`boolean` `isNull()` Test if this Datum is empty
`long` `longValue()` Convert to a long representation of the datum object
`abstract Object` `makeJdbcArray​(int arraySize)` Returns a JDBC array representation of the datum
`void` `setBytes​(byte[] array)` Sets datum value using a byte array.
`void` `setShareBytes​(byte[] array)` Sets datum value using a byte array.
`byte[]` `shareBytes()` Retrieve the data bytes.
`String` `stringValue()` Convert to a String representation of the datum object
`String` `stringValue​(Connection conn)` Some Datum subclass such as TIMESTAMPTZ will override this default implementation which simply ignores the the connection.
`Timestamp` `timestampValue()` Convert to a Timestamp representation of the datum object
`Timestamp` `timestampValue​(Calendar cal)`
`Time` `timeValue()` Convert to a Time representation of the datum object
`Time` `timeValue​(Calendar cal)`
`<T> T` `toClass​(Class<T> type)` Convert this datum to an instance of the specified type if possible.
`abstract Object` `toJdbc()` Returns the JDBC representation of the datum object

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### targetDatum

    protected Datum targetDatum

#### ojiOracleDatumWithConnection

    protected oracle.jdbc.internal.OracleDatumWithConnection ojiOracleDatumWithConnection

### Constructor Detail

#### Datum

    public Datum()

Creates an empty datum

#### Datum

    public Datum​(byte[] newData)

Create a new datum with the given byte array as representation. Subclasses use this to initialize the `data` array.

Parameters:
  `newData` - byte array to be stored in the datum

### Method Detail

#### equals

    public boolean equals​(Object obj)

Test any object for equality with an Datum. Datums are equal if they are of the same class and their bytes are the same.

Overrides:
  `equals` in class `Object`
Parameters:
  `obj` - object to compare `this` with
Returns:
  true if the class of `this` is the same as the class of `obj` and the byte representation of `this` is the same as the byte representation of `obj`.

#### bytesHashCode

    public int bytesHashCode()

Returns:
  hash code for the bytes data stored in this Datum object

#### shareBytes

    public byte[] shareBytes()

Retrieve the data bytes.

Used by java code in subclasses to access the data bytes. If the bytes are not yet a Java array, this may cause them to be copied into one.

Returns:
  a shared pointer to the datum's data bytes.

#### getLength

    public long getLength()

Retreive the length of a datum.

Returns:
  The length of the datum in bytes.

#### setBytes

    public void setBytes​(byte[] array)

Sets datum value using a byte array. The byte array is copied.

Parameters:
  `array` - byte array used to set the datum value

#### setShareBytes

    public void setShareBytes​(byte[] array)

Sets datum value using a byte array. The byte array is referenced.

Parameters:
  `array` - byte array used to set the datum value

#### getBytes

    public byte[] getBytes()

Create a new Java byte array containing a copy of the RDBMS data. No conversions of any kind are done.

For now, the data array is simply copied. When we are using moss to go directly to the buffer cache, this implementation will be overridden by a native method which will cons an array and copy the bytes into it.

Subclasses which handle very long datatypes which will not ordinarily be represented as Java array, should check for allocation failure and return nil if detected. They should however try to materialize the raw data no matter how long since users may actually need to materialize huge arrays.

Returns:
  A new copy of the data bytes or nil if the data could not be materialized because it was too long.

#### isNull

    public boolean isNull()

Test if this Datum is empty

Returns:
  a boolean

#### getStream

    public InputStream getStream()

Create an input stream so the raw data may be read.

This is the normal way to access long datatypes.

Returns:
  an input stream.

#### stringValue

    public String stringValue()
                       throws SQLException

Convert to a String representation of the datum object

Returns:
  String representation of the datum object
Throws:
  `SQLException`

#### stringValue

    public String stringValue​(Connection conn)
                       throws SQLException

Some Datum subclass such as TIMESTAMPTZ will override this default implementation which simply ignores the the connection.

Throws:
  `SQLException`

#### booleanValue

    public boolean booleanValue()
                         throws SQLException

Convert to a boolean representation of the datum object

Returns:
  boolean representation of the datum object
Throws:
  `SQLException`

#### intValue

    public int intValue()
                 throws SQLException

Convert to a integer representation of the datum object

Returns:
  integer representation of the datum object
Throws:
  `SQLException`

#### longValue

    public long longValue()
                   throws SQLException

Convert to a long representation of the datum object

Returns:
  long representation of the datum object
Throws:
  `SQLException`

#### floatValue

    public float floatValue()
                     throws SQLException

Convert to a float representation of the datum object

Returns:
  float representation of the datum object
Throws:
  `SQLException`

#### doubleValue

    public double doubleValue()
                       throws SQLException

Convert to a double representation of the datum object

Returns:
  double representation of the datum object
Throws:
  `SQLException`

#### byteValue

    public byte byteValue()
                   throws SQLException

Convert to a byte representation of the datum object

Returns:
  byte representation of the datum object
Throws:
  `SQLException`

#### bigDecimalValue

    public BigDecimal bigDecimalValue()
                               throws SQLException

Convert to a BigDecimal representation of the datum object

Returns:
  java.math.BigDecimal representation of the datum object
Throws:
  `SQLException`

#### dateValue

    public Date dateValue()
                   throws SQLException

Convert to a Date representation of the datum object

Returns:
  java.sql.Date representation of the datum object
Throws:
  `SQLException`

#### timeValue

    public Time timeValue()
                   throws SQLException

Convert to a Time representation of the datum object

Returns:
  java.sql.Time representation of the datum object
Throws:
  `SQLException`

#### timeValue

    public Time timeValue​(Calendar cal)
                   throws SQLException

Throws:
  `SQLException`

#### timestampValue

    public Timestamp timestampValue()
                             throws SQLException

Convert to a Timestamp representation of the datum object

Returns:
  java.sql.Timestamp representation of the datum object
Throws:
  `SQLException`

#### timestampValue

    public Timestamp timestampValue​(Calendar cal)
                             throws SQLException

Throws:
  `SQLException`

#### characterStreamValue

    public Reader characterStreamValue()
                                throws SQLException

Convert to a character stream representation of the datum object

Returns:
  character stream representation of the datum object
Throws:
  `SQLException`

#### asciiStreamValue

    public InputStream asciiStreamValue()
                                 throws SQLException

Convert to an ascii stream representation of the datum object

Returns:
  ascii stream representation of the datum object
Throws:
  `SQLException`

#### binaryStreamValue

    public InputStream binaryStreamValue()
                                  throws SQLException

Convert to a binary stream representation of the datum object

Returns:
  binary stream representation of the datum object
Throws:
  `SQLException`

#### isConvertibleTo

    public abstract boolean isConvertibleTo​(Class<?> cls)

Determines if datum object can be converted to a particular class

Parameters:
  `cls` - Class to convert to
Returns:
  true, if conversion to cls is permitted false, if conversion to cls is not permitted

#### toClass

    public <T> T toClass​(Class<T> type)
                  throws SQLException

Convert this datum to an instance of the specified type if possible.

Parameters:
  `type` - targetDatum class
Returns:
  an instance of the targetDatum class corresponding to this datum.
Throws:
  `SQLException` - if the conversion is not possible.

#### toJdbc

    public abstract Object toJdbc()
                           throws SQLException

Returns the JDBC representation of the datum object

Returns:
  an object containing the JDBC value
Throws:
  `SQLException` - if conversion to JDBC representation results in an error

#### makeJdbcArray

    public abstract Object makeJdbcArray​(int arraySize)

Returns a JDBC array representation of the datum

Parameters:
  `arraySize` - size of the array
Returns:
  an object containing the JDBC array value

#### compareBytes

    public static int compareBytes​(byte[] m,
                                   byte[] n)

Do an unsigned compare on byte arrays m and n

Parameters:
  `m` - input byte array
  `n` - input byte array
Returns:
  -1 if m < n, 0 if equal, 1 if m > n

#### bytesEqual

    protected boolean bytesEqual​(Datum other)

#### getConnectionDuringExceptionHandling

    protected oracle.jdbc.internal.OracleConnection getConnectionDuringExceptionHandling()