public interface DataValueDescriptor extends Storable, Orderable
This interface matches the getXXX methods on java.sql.ResultSet. This means everyone satisfies getString and getObject; all of the numeric types, within the limits of representation, satisfy all of the numeric getXXX methods; all of the character types satisfy all of the getXXX methods except getBytes and getBinaryStream; all of the binary types satisfy getBytes and all of the getXXXStream methods; Date satisfies getDate and getTimestamp; Time satisfies getTime; and Timestamp satisfies all of the date/time getXXX methods. The "preferred" method (one that will always work, I presume) is the one that matches the type most closely. See the comments below for "preferences". See the JDBC guide for details.
This interface does not include the getXXXStream methods.
The preferred methods for JDBC are:
CHAR and VARCHAR - getString()
BIT - getBoolean()
TINYINT - getByte()
SMALLINT - getShort()
INTEGER - getInt()
BIGINT - getLong()
REAL - getFloat()
FLOAT and DOUBLE - getDouble()
DECIMAL and NUMERIC - getBigDecimal()
BINARY and VARBINARY - getBytes()
DATE - getDate()
TIME - getTime()
TIMESTAMP - getTimestamp()
No JDBC type corresponds to getObject(). Use this for user-defined types or to get the JDBC types as java Objects. All primitive types will be wrapped in their corresponding Object type, i.e. int will be wrapped in an Integer.
getStream()
Modifier and Type | Field and Description |
---|---|
static int |
UNKNOWN_LOGICAL_LENGTH
Constant indicating that the logical length of a value (i.e. chars for
string types or bytes for binary types) is unknown.
|
ORDER_OP_EQUALS, ORDER_OP_GREATEROREQUALS, ORDER_OP_GREATERTHAN, ORDER_OP_LESSOREQUALS, ORDER_OP_LESSTHAN
Modifier and Type | Method and Description |
---|---|
void |
checkHostVariable(int declaredLength)
Check the value to seem if it conforms to the restrictions
imposed by DB2/JCC on host variables for this type.
|
DataValueDescriptor |
cloneHolder()
Get a shallow copy of this
codeDataValueDescriptor (DVD). |
DataValueDescriptor |
cloneValue(boolean forceMaterialization)
Clone this DataValueDescriptor.
|
DataValueDescriptor |
coalesce(DataValueDescriptor[] list,
DataValueDescriptor returnValue)
The SQL language COALESCE/VALUE function.
|
int |
compare(DataValueDescriptor other)
Compare this Orderable with a given Orderable for the purpose of
index positioning.
|
int |
compare(DataValueDescriptor other,
boolean nullsOrderedLow)
Compare this Orderable with another, with configurable null ordering.
|
boolean |
compare(int op,
DataValueDescriptor other,
boolean orderedNulls,
boolean unknownRV)
Compare this Orderable with a given Orderable for the purpose of
qualification and sorting.
|
boolean |
compare(int op,
DataValueDescriptor other,
boolean orderedNulls,
boolean nullsOrderedLow,
boolean unknownRV)
Compare this Orderable with another, with configurable null ordering.
|
BooleanDataValue |
equals(DataValueDescriptor left,
DataValueDescriptor right)
The SQL language = operator.
|
int |
estimateMemoryUsage()
Estimate the memory usage in bytes of the data value and the overhead of the class.
|
boolean |
getBoolean()
Gets the value in the data value descriptor as a boolean.
|
byte |
getByte()
Gets the value in the data value descriptor as a byte.
|
byte[] |
getBytes()
Gets the value in the data value descriptor as a byte array.
|
java.sql.Date |
getDate(java.util.Calendar cal)
Gets the value in the data value descriptor as a java.sql.Date.
|
double |
getDouble()
Gets the value in the data value descriptor as a double.
|
float |
getFloat()
Gets the value in the data value descriptor as a float.
|
int |
getInt()
Gets the value in the data value descriptor as an int.
|
int |
getLength()
Gets the length of the data value.
|
long |
getLong()
Gets the value in the data value descriptor as a long.
|
DataValueDescriptor |
getNewNull()
Get a new null value of the same type as this data value.
|
java.lang.Object |
getObject()
Gets the value in the data value descriptor as a Java Object.
|
short |
getShort()
Gets the value in the data value descriptor as a short.
|
java.io.InputStream |
getStream()
Gets the value in the data value descriptor as a stream of bytes.
|
java.lang.String |
getString()
Gets the value in the data value descriptor as a String.
|
java.sql.Time |
getTime(java.util.Calendar cal)
Gets the value in the data value descriptor as a java.sql.Time.
|
java.sql.Timestamp |
getTimestamp(java.util.Calendar cal)
Gets the value in the data value descriptor as a java.sql.Timestamp.
|
java.lang.String |
getTraceString()
Gets the value in the data value descriptor as a trace string.
|
java.lang.String |
getTypeName()
Get the SQL name of the datatype
|
BooleanDataValue |
greaterOrEquals(DataValueDescriptor left,
DataValueDescriptor right)
The SQL language >= operator.
|
BooleanDataValue |
greaterThan(DataValueDescriptor left,
DataValueDescriptor right)
The SQL language > operator.
|
boolean |
hasStream()
Tells if this data value is, or will be, represented by a stream.
|
BooleanDataValue |
in(DataValueDescriptor left,
DataValueDescriptor[] inList,
boolean orderedList)
The SQL language IN operator.
|
BooleanDataValue |
isNotNull()
The SQL "IS NOT NULL" operator.
|
BooleanDataValue |
isNullOp()
The SQL "IS NULL" operator.
|
BooleanDataValue |
lessOrEquals(DataValueDescriptor left,
DataValueDescriptor right)
The SQL language <= operator.
|
BooleanDataValue |
lessThan(DataValueDescriptor left,
DataValueDescriptor right)
The SQL language < operator.
|
void |
normalize(DataTypeDescriptor dtd,
DataValueDescriptor source)
Normalize the source value to this type described by this class
and the passed in DataTypeDescriptor.
|
BooleanDataValue |
notEquals(DataValueDescriptor left,
DataValueDescriptor right)
The SQL language <> operator.
|
void |
readExternalFromArray(ArrayInputStream ais)
Read the DataValueDescriptor from the stream.
|
DataValueDescriptor |
recycle()
Recycle this DataValueDescriptor if possible.
|
void |
setBigDecimal(java.math.BigDecimal bigDecimal)
Set this value from an application supplied java.math.BigDecimal.
|
void |
setInto(java.sql.PreparedStatement ps,
int position)
Set this value into a PreparedStatement.
|
void |
setInto(java.sql.ResultSet rs,
int position)
Set this value into a ResultSet for a subsequent ResultSet.insertRow
or ResultSet.updateRow.
|
void |
setObjectForCast(java.lang.Object value,
boolean instanceOfResultType,
java.lang.String resultTypeClassName)
Set this value from an Object.
|
void |
setToNull()
Set the value to SQL null.
|
void |
setValue(java.sql.Blob theValue)
Set the value of this DataValueDescriptor from a Blob.
|
void |
setValue(boolean theValue)
Set the value.
|
void |
setValue(byte theValue)
Set the value of this DataValueDescriptor to the given byte value
|
void |
setValue(byte[] theValue)
Set the value of this DataValueDescriptor.
|
void |
setValue(java.sql.Clob theValue)
Set the value of this DataValueDescriptor from a Clob.
|
void |
setValue(DataValueDescriptor theValue)
Set the value of this DataValueDescriptor from another.
|
void |
setValue(java.sql.Date theValue)
Set the value of this DataValueDescriptor.
|
void |
setValue(java.sql.Date theValue,
java.util.Calendar cal)
Set the value of this DataValueDescriptor.
|
void |
setValue(double theValue)
Set the value of this DataValueDescriptor to the given double value
|
void |
setValue(float theValue)
Set the value of this DataValueDescriptor to the given double value
|
void |
setValue(java.io.InputStream theStream,
int valueLength)
Set the value to be the contents of the stream.
|
void |
setValue(int theValue)
Set the value of this DataValueDescriptor to the given int value
|
void |
setValue(long theValue)
Set the value of this DataValueDescriptor to the given long value
|
void |
setValue(java.lang.Object theValue)
Set the value of this DataValueDescriptor to the given Object value
|
void |
setValue(short theValue)
Set the value of this DataValueDescriptor to the given short value
|
void |
setValue(java.lang.String theValue)
Set the value of this DataValueDescriptor.
|
void |
setValue(java.sql.Time theValue)
Set the value of this DataValueDescriptor.
|
void |
setValue(java.sql.Time theValue,
java.util.Calendar cal)
Set the value of this DataValueDescriptor.
|
void |
setValue(java.sql.Timestamp theValue)
Set the value of this DataValueDescriptor.
|
void |
setValue(java.sql.Timestamp theValue,
java.util.Calendar cal)
Set the value of this DataValueDescriptor.
|
void |
setValueFromResultSet(java.sql.ResultSet resultSet,
int colNumber,
boolean isNullable)
Set the value based on the value for the specified DataValueDescriptor
from the specified ResultSet.
|
int |
typePrecedence()
Each built-in type in JSQL has a precedence.
|
int |
typeToBigDecimal()
How should this value be obtained so that it can
be converted to a BigDecimal representation.
|
isNull, restoreToNull
getTypeFormatId
static final int UNKNOWN_LOGICAL_LENGTH
int getLength() throws StandardException
StandardException
- On errorjava.lang.String getString() throws StandardException
StandardException
- Thrown on errorjava.lang.String getTraceString() throws StandardException
StandardException
boolean getBoolean() throws StandardException
StandardException
- Thrown on errorbyte getByte() throws StandardException
StandardException
- Thrown on errorshort getShort() throws StandardException
StandardException
- Thrown on errorint getInt() throws StandardException
StandardException
- Thrown on errorlong getLong() throws StandardException
StandardException
- Thrown on errorfloat getFloat() throws StandardException
StandardException
- Thrown on errordouble getDouble() throws StandardException
StandardException
- Thrown on errorint typeToBigDecimal() throws StandardException
StandardException
- Conversion is not possiblebyte[] getBytes() throws StandardException
StandardException
- Thrown on errorjava.sql.Date getDate(java.util.Calendar cal) throws StandardException
cal
- calendar for object creationStandardException
- Thrown on errorjava.sql.Time getTime(java.util.Calendar cal) throws StandardException
cal
- calendar for object creationStandardException
- Thrown on errorjava.sql.Timestamp getTimestamp(java.util.Calendar cal) throws StandardException
cal
- calendar for object creationStandardException
- Thrown on errorjava.lang.Object getObject() throws StandardException
StandardException
- Thrown on errorjava.io.InputStream getStream() throws StandardException
Only data types that implement StreamStorable
will have stream
states, and the method hasStream
should be called to determine
if the value in question is, or will be, represented by a stream.
StandardException
- Throws an exception if the data value
cannot be received as a stream.hasStream()
,
StringDataValue.getStreamWithDescriptor()
boolean hasStream()
This method should be called to determine if the methods getStream
or DataValueDescriptor.getStreamWithDescriptor
can
be invoked.
true
if the value will be a stream, false
otherwise.getStream()
,
StringDataValue.getStreamWithDescriptor()
DataValueDescriptor cloneHolder()
codeDataValueDescriptor
(DVD).
The primary use of this method is to avoid materializing streams for data types like BLOB and CLOB.
In general the orginal DVD should be recycled or discarded when this method is invoked to ensure that changes to the original DVD don't affect the clone (or the other way around). Note that it is not safe to assume that a number of these clones can be used for read-only access to the same value.
Implementation note: The reason why the clones can't be guaranteed to work as "read clones" is that if the value is represented as a stream, the state of the stream will change on read operations. Since all the clones share the same stream, this may lead to wrong results, data corruption or crashes.
DataValueDescriptor cloneValue(boolean forceMaterialization)
Even though the objects can be modified independently regardless of the
value of forceMaterialization
, both the clone and the
original may be dependent on the store state if
forceMaterialization
is set to false
. An example is if
you need to access the value you just read using cloneValue
after the current transaction has ended, or after the source result set
has been closed.
forceMaterialization
- any streams representing the data value will
be materialized if true
, the data value will be kept as a
stream if possible if false
DataValueDescriptor
with the same initial
value as this.DataValueDescriptor recycle()
DataValueDescriptor getNewNull()
void setValueFromResultSet(java.sql.ResultSet resultSet, int colNumber, boolean isNullable) throws StandardException, java.sql.SQLException
resultSet
- The specified ResultSet.colNumber
- The 1-based column # into the resultSet.isNullable
- Whether or not the column is nullable
(No need to call wasNull() if not)StandardException
- Thrown on errorjava.sql.SQLException
- Error accessing the result setvoid setInto(java.sql.PreparedStatement ps, int position) throws java.sql.SQLException, StandardException
java.sql.SQLException
- thrown by the PreparedStatement objectStandardException
- thrown by me accessing my value.void setInto(java.sql.ResultSet rs, int position) throws java.sql.SQLException, StandardException
java.sql.SQLException
- thrown by the ResultSet objectStandardException
- thrown by me accessing my value.void setValue(int theValue) throws StandardException
theValue
- The value to set this DataValueDescriptor toStandardException
- Thrown on errorvoid setValue(double theValue) throws StandardException
theValue
- The value to set this DataValueDescriptor toStandardException
- Thrown on errorvoid setValue(float theValue) throws StandardException
theValue
- A Double containing the value to set this
DataValueDescriptor to. Null means set the value
to SQL null.StandardException
- Thrown on errorvoid setValue(short theValue) throws StandardException
theValue
- The value to set this DataValueDescriptor toStandardException
- Thrown on errorvoid setValue(long theValue) throws StandardException
theValue
- The value to set this DataValueDescriptor toStandardException
- Thrown on errorvoid setValue(byte theValue) throws StandardException
theValue
- The value to set this DataValueDescriptor toStandardException
void setValue(boolean theValue) throws StandardException
theValue
- Contains the boolean value to set this toStandardException
void setValue(java.lang.Object theValue) throws StandardException
theValue
- The value to set this DataValueDescriptor toStandardException
- Thrown on errorvoid setValue(byte[] theValue) throws StandardException
theValue
- The byte value to set this DataValueDescriptor toStandardException
void setBigDecimal(java.math.BigDecimal bigDecimal) throws StandardException
bigDecimal
- required to be a BigDecimal or null.StandardException
void setValue(java.lang.String theValue) throws StandardException
theValue
- The String value to set this DataValueDescriptor toStandardException
void setValue(java.sql.Blob theValue) throws StandardException
theValue
- The Blob value to set this DataValueDescriptor toStandardException
void setValue(java.sql.Clob theValue) throws StandardException
theValue
- The Clob value to set this DataValueDescriptor toStandardException
void setValue(java.sql.Time theValue) throws StandardException
theValue
- The Time value to set this DataValueDescriptor toStandardException
void setValue(java.sql.Time theValue, java.util.Calendar cal) throws StandardException
theValue
- The Time value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database time valueStandardException
void setValue(java.sql.Timestamp theValue) throws StandardException
theValue
- The Timestamp value to set this DataValueDescriptor toStandardException
void setValue(java.sql.Timestamp theValue, java.util.Calendar cal) throws StandardException
theValue
- The Timestamp value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database timestamp valueStandardException
void setValue(java.sql.Date theValue) throws StandardException
theValue
- The Date value to set this DataValueDescriptor toStandardException
void setValue(java.sql.Date theValue, java.util.Calendar cal) throws StandardException
theValue
- The Date value to set this DataValueDescriptor tocal
- The time zone from the calendar is used to construct the database date valueStandardException
void setValue(DataValueDescriptor theValue) throws StandardException
theValue
- The Date value to set this DataValueDescriptor toStandardException
void setToNull()
void normalize(DataTypeDescriptor dtd, DataValueDescriptor source) throws StandardException
StandardException
BooleanDataValue isNullOp()
BooleanDataValue isNotNull()
java.lang.String getTypeName()
void setObjectForCast(java.lang.Object value, boolean instanceOfResultType, java.lang.String resultTypeClassName) throws StandardException
value
- The new valueinstanceOfResultType
- Whether or not the new value
is an instanceof the result type.resultTypeClassName
- The class name of the resulting (declared) type
(for error messages only).StandardException
- Thrown on errorvoid readExternalFromArray(ArrayInputStream ais) throws java.io.IOException, java.lang.ClassNotFoundException
Initialize the data value by reading it's values from the ArrayInputStream. This interface is provided as a way to achieve possible performance enhancement when reading an array can be optimized over reading from a generic stream from readExternal().
ais
- The array stream positioned at the beginning of the
byte stream to read from.java.io.IOException
- Usual error is if you try to read
past limit on the stream.java.lang.ClassNotFoundException
- If a necessary class can not be
found while reading the object from
the stream.int typePrecedence()
BooleanDataValue equals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException
left
- The value on the left side of the operatorright
- The value on the right side of the operatorStandardException
- Thrown on errorBooleanDataValue notEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException
left
- The value on the left side of the operatorright
- The value on the right side of the operatorStandardException
- Thrown on errorBooleanDataValue lessThan(DataValueDescriptor left, DataValueDescriptor right) throws StandardException
left
- The value on the left side of the operatorright
- The value on the right side of the operatorStandardException
- Thrown on errorBooleanDataValue greaterThan(DataValueDescriptor left, DataValueDescriptor right) throws StandardException
left
- The value on the left side of the operatorright
- The value on the right side of the operatorStandardException
- Thrown on errorBooleanDataValue lessOrEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException
left
- The value on the left side of the operatorright
- The value on the right side of the operatorStandardException
- Thrown on errorBooleanDataValue greaterOrEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException
left
- The value on the left side of the operatorright
- The value on the right side of the operatorStandardException
- Thrown on errorDataValueDescriptor coalesce(DataValueDescriptor[] list, DataValueDescriptor returnValue) throws StandardException
list
- The list of the arguments. Function will return the first non-nullable argument if any.returnValue
- The return value is the correct datatype for this function.
The return value of this method is the type of the 2nd parameter.StandardException
- Thrown on errorBooleanDataValue in(DataValueDescriptor left, DataValueDescriptor[] inList, boolean orderedList) throws StandardException
left
- The value on the left side of the operatorinList
- The values in the IN listorderedList
- True means that the values in the IN list are ordered,
false means they are not.StandardException
- Thrown on errorint compare(DataValueDescriptor other) throws StandardException
other
- The Orderable to compare this one to.StandardException
- Thrown on errorint compare(DataValueDescriptor other, boolean nullsOrderedLow) throws StandardException
other
- The Orderable to compare this one to.
% @param nullsOrderedLow True if null should be lower than non-NULLStandardException
- Thrown on errorboolean compare(int op, DataValueDescriptor other, boolean orderedNulls, boolean unknownRV) throws StandardException
op
- Orderable.ORDER_OP_EQUALS means do an = comparison.
Orderable.ORDER_OP_LESSTHAN means compare this < other.
Orderable.ORDER_OP_LESSOREQUALS means compare this <= other.other
- The DataValueDescriptor to compare this one to.orderedNulls
- True means to treat nulls as ordered values,
that is, treat SQL null as equal to null, and less
than all other values.
False means to treat nulls as unknown values,
that is, the result of any comparison with a null
is the UNKNOWN truth value.unknownRV
- The return value to use if the result of the
comparison is the UNKNOWN truth value. In other
words, if orderedNulls is false, and a null is
involved in the comparison, return unknownRV.
This parameter is not used orderedNulls is true.StandardException
- Thrown on errorboolean compare(int op, DataValueDescriptor other, boolean orderedNulls, boolean nullsOrderedLow, boolean unknownRV) throws StandardException
op
- Orderable.ORDER_OP_EQUALS means do an = comparison.
Orderable.ORDER_OP_LESSTHAN means compare this < other.
Orderable.ORDER_OP_LESSOREQUALS means compare this <= other.other
- The DataValueDescriptor to compare this one to.orderedNulls
- True means to treat nulls as ordered values,
that is, treat SQL null as equal to null, and either greater or less
than all other values.
False means to treat nulls as unknown values,
that is, the result of any comparison with a null
is the UNKNOWN truth value.nullsOrderedLow
- True means NULL less than non-NULL,
false means NULL greater than non-NULL.
Only relevant if orderedNulls is true.unknownRV
- The return value to use if the result of the
comparison is the UNKNOWN truth value. In other
words, if orderedNulls is false, and a null is
involved in the comparison, return unknownRV.
This parameter is not used orderedNulls is true.StandardException
- Thrown on errorvoid setValue(java.io.InputStream theStream, int valueLength) throws StandardException
The reading of the stream may be delayed until execution time, and the format of the stream is required to be the format of this type.
Note that the logical length excludes any header bytes and marker bytes
(for instance the Derby specific EOF stream marker). Specifying the
logical length may improve performance in some cases, but specifying
that the length is unknown (UNKNOWN_LOGICAL_LENGTH
should
always leave the system in a functional state. Specifying an incorrect
length will cause errors.
theStream
- stream of correctly formatted datavalueLength
- logical length of the stream's value in units of this
type (e.g. chars for string types), or
UNKNOWN_LOGICAL_LENGTH
if the logical length is unknownStandardException
void checkHostVariable(int declaredLength) throws StandardException
StandardException
- Variable is too big.int estimateMemoryUsage()
Apache Derby V10.13 Internals - Copyright © 2004,2016 The Apache Software Foundation. All Rights Reserved.