Package oracle.sql

Class VECTOR

java.lang.Object

oracle.sql.Datum

oracle.sql.VECTOR

All Implemented Interfaces:

Serializable

public final class VECTOR
extends Datum

VECTOR Class

The VECTOR class provides conversions between the Oracle VECTOR data type and Java classes:

• double[]
• float[]
• long[]
• int[]
• short[]
• byte[]
• boolean[]
• VECTOR.SparseDoubleArray
• VECTOR.SparseFloatArray
• VECTOR.SparseByteArray
• String

Instances of the oracle.sql.VECTOR class may be passed to the setObject methods of PreparedStatement, and instances may be returned by the getObject methods of ResultSet and CallableStatement.

Creating a VECTOR

Static factory methods convert a Java array into a VECTOR of a specific dimension type:

• ofFloat64Values(Object)
• ofFloat32Values(Object)
• ofInt8Values(Object)
• ofBinaryValues(Object)

Accessing Meta Data

The dimension type of a VECTOR can be obtained from getType(), the number of dimensions can be obtained from getVectorLength(), and the SPARSE encoding format can be checked for with isSparse().

Since:

23.4

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	VECTOR.SparseArray	A representation of SPARSE VECTOR data in Oracle Database.
static interface	VECTOR.SparseByteArray	A byte-valued representation of SPARSE VECTOR data in Oracle Database.
static interface	VECTOR.SparseDoubleArray	A double-valued representation of SPARSE VECTOR data in Oracle Database.
static interface	VECTOR.SparseFloatArray	A float-valued representation of SPARSE VECTOR data in Oracle Database.

Field Summary

Fields inherited from class oracle.sql.Datum

ojiOracleDatumWithConnection, targetDatum

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object object)	Checks if this VECTOR is equal to another VECTOR.
static VECTOR	fromData(byte[] data)	For most use cases, an of...Values method should be used when creating a VECTOR object, not this method.
OracleType	getType()	Returns the type of this VECTOR, which is one of the following:
int	getVectorLength()	Returns the number of values in this VECTOR (ie: The dimension count).
int	hashCode()	Returns a hash code computed from the type and values of this VECTOR.
boolean	isConvertibleTo(Class<?> cls)	Determines if datum object can be converted to a particular class
boolean	isSparse()	Returns true if this VECTOR has a SPARSE encoding.
Object	makeJdbcArray(int arraySize)	Returns a JDBC array representation of the datum
static VECTOR	ofBinaryValues(Object object)	Converts an Object into a VECTOR of the BINARY dimension type.
static VECTOR	ofFloat32Values(Object object)	Converts an Object into a VECTOR of the FLOAT32 dimension type.
static VECTOR	ofFloat64Values(Object object)	Converts an Object into a VECTOR of the FLOAT64 dimension type.
static VECTOR	ofInt8Values(Object object)	Converts an Object into a VECTOR of the INT8 dimension type.
Class<?>	preferredArrayClass()	Returns the preferred array class for this VECTOR.
String	stringValue()	Converts this VECTOR into String.
boolean[]	toBooleanArray()	Converts this VECTOR into an array of booleans.
static boolean[]	toBooleanArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into an array of booleans.
byte[]	toByteArray()	Converts this VECTOR into an array of bytes.
static byte[]	toByteArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into an array of bytes.
<T> T	toClass(Class<T> type)	Convert this datum to an instance of the specified type if possible.
double[]	toDoubleArray()	Converts this VECTOR into an array of doubles.
static double[]	toDoubleArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into an array of doubles.
float[]	toFloatArray()	Converts this VECTOR into an array of floats.
static float[]	toFloatArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into an array of floats.
int[]	toIntArray()	Converts this VECTOR into an array of ints.
static int[]	toIntArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into an array of ints.
Object	toJdbc()	Returns the JDBC representation of the datum object
long[]	toLongArray()	Converts this VECTOR into an array of longs.
static long[]	toLongArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into an array of longs.
short[]	toShortArray()	Converts this VECTOR into an array of shorts.
static short[]	toShortArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into an array of shorts.
VECTOR.SparseByteArray	toSparseByteArray()	Converts this VECTOR into a SparseByteArray.
VECTOR.SparseByteArray	toSparseByteArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into a SparseByteArray.
VECTOR.SparseDoubleArray	toSparseDoubleArray()	Converts this VECTOR into a SparseDoubleArray.
VECTOR.SparseDoubleArray	toSparseDoubleArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into a SparseDoubleArray.
VECTOR.SparseFloatArray	toSparseFloatArray()	Converts this VECTOR into a SparseFloatArray.
VECTOR.SparseFloatArray	toSparseFloatArray(byte[] data)	Converts Oracle's internal encoding of a VECTOR into a SparseFloatArray.
String	toString()

Methods inherited from class oracle.sql.Datum

asciiStreamValue, bigDecimalValue, binaryStreamValue, booleanValue, bytesEqual, bytesHashCode, byteValue, characterStreamValue, compareBytes, dateValue, doubleValue, floatValue, getBytes, getConnectionDuringExceptionHandling, getLength, getStream, intValue, isNull, longValue, setBytes, setShareBytes, shareBytes, stringValue, timestampValue, timestampValue, timeValue, timeValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

fromData

public static VECTOR fromData(byte[] data)

For most use cases, an of...Values method should be used when creating a VECTOR object, not this method.

Creates a VECTOR from Oracle's internal encoding of a VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

A VECTOR that contains the encoded values. Not null.

Throws:

NullPointerException - If data is null

ofFloat64Values

public static VECTOR ofFloat64Values(Object object)
                              throws SQLException

Converts an Object into a VECTOR of the FLOAT64 dimension type. The object may be an instance of any class listed in the "Java to SQL Conversions" section of the JavaDoc for OracleType.VECTOR_FLOAT64. Lossy conversions specified in that JavaDoc also apply to this method.

Parameters:

object - Object containing values of a VECTOR. Not null.

Returns:

A VECTOR that contains the values. Not null.

Throws:

NullPointerException - If the object is null.

SQLException - If the object can not be converted into a VECTOR, for instance because its class is not recognized, or because the number of values exceeds the maximum length of a VECTOR.

ofFloat32Values

public static VECTOR ofFloat32Values(Object object)
                              throws SQLException

Converts an Object into a VECTOR of the FLOAT32 dimension type. The object may be an instance of any class listed in the "Java to SQL Conversions" section of the JavaDoc for OracleType.VECTOR_FLOAT32. Lossy conversions specified in that JavaDoc also apply to this method.

Parameters:

object - Object containing values of a VECTOR. Not null.

Returns:

A VECTOR that contains the values. Not null.

Throws:

NullPointerException - If the object is null.

SQLException - If the object can not be converted into a VECTOR, for instance because its class is not recognized, or because the number of values exceeds the maximum length of a VECTOR.

ofInt8Values

public static VECTOR ofInt8Values(Object object)
                           throws SQLException

Converts an Object into a VECTOR of the INT8 dimension type. The object may be an instance of any class listed in the "Java to SQL Conversions" section of the JavaDoc for OracleType.VECTOR_INT8. Lossy conversions specified in that JavaDoc also apply to this method.

Parameters:

object - Object containing values of a VECTOR. Not null.

Returns:

A VECTOR that contains the values. Not null.

Throws:

NullPointerException - If the object is null.

SQLException - If the object can not be converted into a VECTOR, for instance because its class is not recognized, or because the number of values exceeds the maximum length of a VECTOR.

ofBinaryValues

public static VECTOR ofBinaryValues(Object object)
                             throws SQLException

Converts an Object into a VECTOR of the BINARY dimension type. The object may be an instance of any class listed in the "Java to SQL Conversions" section of the JavaDoc for OracleType.VECTOR_BINARY.

Parameters:

object - Object containing values of a VECTOR. Not null.

Returns:

A VECTOR that contains the values. Not null.

Throws:

NullPointerException - If the object is null.

SQLException - If the object can not be converted into a VECTOR, for instance because its class is not recognized, or because the number of values exceeds the maximum length of a VECTOR.

getType

public OracleType getType()
                   throws SQLException

Returns the type of this VECTOR, which is one of the following:

• OracleType.VECTOR_FLOAT64
• OracleType.VECTOR_FLOAT32
• OracleType.VECTOR_INT8
• OracleType.VECTOR_BINARY

This method will not return OracleType.VECTOR, which is only applicable to columns and parameters. Individual VECTOR values always have a specific dimension type of FLOAT64, FLOAT32, INT8, or BINARY.

Returns:

The type of this VECTOR. Not null.

Throws:

SQLException - If the data this VECTOR was created with is not recognized as the binary encoding of a VECTOR.

toDoubleArray

public double[] toDoubleArray()
                       throws SQLException

Converts this VECTOR into an array of doubles.

This is a lossless conversion. The array returned by this method contains double values which store the same information as this VECTOR.

Returns:

An array containing the values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toDoubleArray

public static double[] toDoubleArray(byte[] data)
                              throws SQLException

Converts Oracle's internal encoding of a VECTOR into an array of doubles.

This method performs a lossless conversion. The array returned by this method contains double values which store the same information as the given VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

An array containing the values (ie: "dimensions") of a VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

NullPointerException - If data is null.

toFloatArray

public float[] toFloatArray()
                     throws SQLException

Converts this VECTOR into an array of floats.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Returns:

An array containing the values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toFloatArray

public static float[] toFloatArray(byte[] data)
                            throws SQLException

Converts Oracle's internal encoding of a VECTOR into an array of floats.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

An array containing the values (ie: "dimensions") of a VECTOR. Not null.

Throws:

NullPointerException - If data is null.

SQLException - If the dimension type can not be converted to the returned type.

toLongArray

public long[] toLongArray()
                   throws SQLException

Converts this VECTOR into an array of longs.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Returns:

An array containing the values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toLongArray

public static long[] toLongArray(byte[] data)
                          throws SQLException

Converts Oracle's internal encoding of a VECTOR into an array of longs.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

An array containing the values (ie: "dimensions") of a VECTOR. Not null.

Throws:

NullPointerException - If data is null.

SQLException - If the dimension type can not be converted to the returned type.

toIntArray

public int[] toIntArray()
                 throws SQLException

Converts this VECTOR into an array of ints.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Returns:

An array containing the values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toIntArray

public static int[] toIntArray(byte[] data)
                        throws SQLException

Converts Oracle's internal encoding of a VECTOR into an array of ints.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

An array containing the values (ie: "dimensions") of a VECTOR. Not null.

Throws:

NullPointerException - If data is null.

SQLException - If the dimension type can not be converted to the returned type.

toShortArray

public short[] toShortArray()
                     throws SQLException

Converts this VECTOR into an array of shorts.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Returns:

An array containing the values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toShortArray

public static short[] toShortArray(byte[] data)
                            throws SQLException

Converts Oracle's internal encoding of a VECTOR into an array of shorts.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

An array containing the values (ie: "dimensions") of a VECTOR. Not null.

Throws:

NullPointerException - If data is null.

SQLException - If the dimension type can not be converted to the returned type.

toByteArray

public byte[] toByteArray()
                   throws SQLException

Converts this VECTOR into an array of bytes.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

If the type of this VECTOR is OracleType.VECTOR_BINARY, each byte returned by this method is 8 dimensions packed as bits in MSB order.

Returns:

An array containing the values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toByteArray

public static byte[] toByteArray(byte[] data)
                          throws SQLException

Converts Oracle's internal encoding of a VECTOR into an array of bytes.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

If the type of this VECTOR is OracleType.VECTOR_BINARY, each byte returned by this method contains up to 8 dimensions, packed as bits in MSB order. The last byte may contain less than 8 dimensions if the length of this VECTOR is not a multiple of 8.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

An array containing the values (ie: "dimensions") of a VECTOR. Not null.

Throws:

NullPointerException - If data is null.

SQLException - If the dimension type can not be converted to the returned type.

toBooleanArray

public boolean[] toBooleanArray()
                         throws SQLException

Converts this VECTOR into an array of booleans.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Returns:

An array containing the values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the data this VECTOR was created with is not recognized as the binary encoding of a VECTOR.

toBooleanArray

public static boolean[] toBooleanArray(byte[] data)
                                throws SQLException

Converts Oracle's internal encoding of a VECTOR into an array of booleans.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

An array containing the values (ie: "dimensions") of a VECTOR. Not null.

Throws:

NullPointerException - If data is null.

SQLException - If the dimension type can not be converted to the returned type.

stringValue

public String stringValue()
                   throws SQLException

Converts this VECTOR into String.

This method returns a VARCHAR literal representation of this VECTOR, as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Overrides:

stringValue in class Datum

Returns:

The VARCHAR literal representation of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toString

public String toString()

Overrides:

toString in class Object

hashCode

public int hashCode()

Returns a hash code computed from the type and values of this VECTOR.

Overrides:

hashCode in class Object

Returns:

A hash code for this VECTOR.

equals

public boolean equals(Object object)

Checks if this VECTOR is equal to another VECTOR. This method considers two vectors to be equal if both have the same type, and contain the same values (ie: "dimensions").

This method returns false if the data that either VECTOR was created with is not recognized as the binary encoding of a VECTOR.

Overrides:

equals in class Datum

Parameters:

object - object to compare this with

Returns:

true if the given object is an equal VECTOR, or false if not.

preferredArrayClass

public Class<?> preferredArrayClass()
                             throws SQLException

Returns the preferred array class for this VECTOR.

Returns:

The preferred array class. Not null.

Throws:

SQLException - If the data this VECTOR was created with is not recognized as the binary encoding of a VECTOR.

getVectorLength

public int getVectorLength()

Returns the number of values in this VECTOR (ie: The dimension count).

Returns:

The number of values in this VECTOR.

Throws:

IllegalStateException - If the data this VECTOR was created with is not recognized as the binary encoding of a VECTOR.

toClass

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

Description copied from class: Datum

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

Overrides:

toClass in class Datum

Parameters:

type - targetDatum class

Returns:

an instance of the targetDatum class corresponding to this datum.

Throws:

SQLException - if the conversion is not possible.

isConvertibleTo

public boolean isConvertibleTo(Class<?> cls)

Description copied from class: Datum

Determines if datum object can be converted to a particular class

Specified by:

isConvertibleTo in class Datum

Parameters:

cls - Class to convert to

Returns:

true, if conversion to cls is permitted false, if conversion to cls is not permitted

toJdbc

public Object toJdbc()
              throws SQLException

Returns the JDBC representation of the datum object

THE BEHAVIOR OF THIS METHOD MAY CHANGE IN A FUTURE RELEASE.

The behavior of this method may change if a future JDBC specification defines a mapping for VECTOR data. No such mapping is defined in JDBC 4.3, so this method is currently implemented to return this VECTOR.

Specified by:

toJdbc in class Datum

Returns:

an object containing the JDBC value

Throws:

SQLException - if conversion to JDBC representation results in an error

makeJdbcArray

public Object makeJdbcArray(int arraySize)

Returns a JDBC array representation of the datum

THE BEHAVIOR OF THIS METHOD MAY CHANGE IN A FUTURE RELEASE.

The behavior of this method may change if a future JDBC specification defines a mapping for VECTOR data. No such mapping is defined in JDBC 4.3, so this method is currently implemented to return an array with the component type of oracle.sql.VECTOR.

Specified by:

makeJdbcArray in class Datum

Parameters:

arraySize - size of the array

Returns:

an object containing the JDBC array value

isSparse

public boolean isSparse()
                 throws SQLException

Returns true if this VECTOR has a SPARSE encoding.

Returns:

true if the data has a SPARSE encoding, or false if not.

Throws:

SQLException - If the data this VECTOR was created with is not recognized as the binary encoding of a VECTOR.

toSparseDoubleArray

public VECTOR.SparseDoubleArray toSparseDoubleArray()
                                             throws SQLException

Converts this VECTOR into a SparseDoubleArray.

This is a lossless conversion. The array returned by this method contains double values which store the same information as this VECTOR.

Returns:

A sparse array containing the non-zero values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toSparseDoubleArray

public VECTOR.SparseDoubleArray toSparseDoubleArray(byte[] data)
                                             throws SQLException

Converts Oracle's internal encoding of a VECTOR into a SparseDoubleArray.

This is a lossless conversion. The array returned by this method contains double values which store the same information as this VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

A sparse array containing the non-zero values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toSparseFloatArray

public VECTOR.SparseFloatArray toSparseFloatArray()
                                           throws SQLException

Converts this VECTOR into a SparseFloatArray.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Returns:

A sparse array containing the non-zero values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toSparseFloatArray

public VECTOR.SparseFloatArray toSparseFloatArray(byte[] data)
                                           throws SQLException

Converts Oracle's internal encoding of a VECTOR into a SparseFloatArray.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

A sparse array containing the non-zero values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toSparseByteArray

public VECTOR.SparseByteArray toSparseByteArray()
                                         throws SQLException

Converts this VECTOR into a SparseByteArray.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Returns:

A sparse array containing the non-zero values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.

toSparseByteArray

public VECTOR.SparseByteArray toSparseByteArray(byte[] data)
                                         throws SQLException

Converts Oracle's internal encoding of a VECTOR into a SparseByteArray.

This method may perform lossy conversions as specified in the "SQL to Java Conversions" section of the JavaDoc for OracleType.VECTOR.

Parameters:

data - Oracle's internal encoding of a VECTOR. Not null.

Returns:

A sparse array containing the non-zero values (ie: "dimensions") of this VECTOR. Not null.

Throws:

SQLException - If the dimension type can not be converted to the returned type.