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, 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

static boolean

TRACE

Constructor Summary

Datum()
Creates an empty datum

Datum(byte[] newData)
Create a new datum with the given byte array as representation.

Method Summary

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)
byte	byteValue() Convert to a byte representation of the datum object
Reader	characterStreamValue() Convert to a character stream representation of the datum object
protected 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

TRACE

public static final boolean TRACE

See Also:

Constant Field Values

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.

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, - if no String representation exists

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, - if no boolean representation exists

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, - if no integer representation exists

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, - if no long representation exists

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, - if no float representation exists

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, - if no double representation exists

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, - if no byte representation exists

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, - if no BigDecimal representation exists

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, - if no Date representation exists

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, - if no Time representation exists

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, - if no Timestamp representation exists

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, - if no character stream representation exists

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, - if no ascii stream representation exists

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, - if no binary stream representation exists

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 - Target class

Returns:

an instance of the target 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

protected 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()