Class SQLBinary
- All Implemented Interfaces:
Externalizable
,Serializable
,Comparable
,Formatable
,Storable
,StreamStorable
,TypedFormat
,BitDataValue
,ConcatableDataValue
,DataValueDescriptor
,Orderable
,VariableSizeDataValue
- CHAR FOR BIT DATA
- VARCHAR FOR BIT DATA
- LONG VARCHAR
- BLOB
Format :
Length is encoded to support Cloudscape 5.x databases where the length was stored as the number of bits.
The first bit of the first byte indicates if the format is an old (Cloudscape 5.x) style or a new Derby style.
Derby then uses the next two bits to indicate how the length is encoded.
When the value was written from a byte array the Derby encoded byte
length format was always used from Derby 10.0 onwards (ie. all open
source versions).
When the value was written from a stream (e.g. PreparedStatement.setBinaryStream)
then the Cloudscape '5.x format zero' was used by 10.0 and 10.1.
The was due to the class RawToBinaryFormatStream always writing
four zero bytes for the length before the data.
The Cloudscape '5.x format bits' format I think was never used by Derby.
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) Blob
private static final int
(package private) byte[]
private static final int
(package private) static final byte
(package private) InputStream
Value as a stream, this stream represents the on-disk format of the value.(package private) int
Length of the value in bytes when this value is set as a stream.Fields inherited from interface org.apache.derby.iapi.types.DataValueDescriptor
UNKNOWN_LOGICAL_LENGTH
Fields inherited from interface org.apache.derby.iapi.types.Orderable
ORDER_OP_EQUALS, ORDER_OP_GREATEROREQUALS, ORDER_OP_GREATERTHAN, ORDER_OP_LESSOREQUALS, ORDER_OP_LESSTHAN
Fields inherited from interface org.apache.derby.iapi.types.VariableSizeDataValue
IGNORE_PRECISION
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal NumberDataValue
charLength
(NumberDataValue result) This method implements the char_length function for bit.final void
checkHostVariable
(int declaredLength) Host variables are rejected if their length is bigger than the declared length, regardless of if the trailing bytes are the pad character.final DataValueDescriptor
Shallow clone a StreamStorable without objectifying.cloneValue
(boolean forceMaterialization) Clone this DataValueDescriptor.private static int
compare
(byte[] left, byte[] right) final boolean
compare
(int op, DataValueDescriptor other, boolean orderedNulls, boolean unknownRV) Compare this Orderable with a given Orderable for the purpose of qualification and sorting.final int
compare
(DataValueDescriptor other) Compare this Orderable with a given Orderable for the purpose of index positioning.final BitDataValue
concatenate
(BitDataValue left, BitDataValue right, BitDataValue result) The SQL concatenation '||' operator.final BooleanDataValue
equals
(DataValueDescriptor left, DataValueDescriptor right) The = operator as called from the language module, as opposed to the storage module.int
Estimate the memory usage in bytes of the data value and the overhead of the class.private int
final byte[]
getBytes()
Gets the value in the data value descriptor as a byte[].final int
length in bytes(package private) abstract int
Return max memory usage for a SQL Binaryfinal InputStream
Gets the value in the data stream descriptor as an InputStream.final String
Used by JDBC -- string should not contain SQL92 formatting.final String
Gets a trace representation for debugging.(package private) byte[]
getValue()
final BooleanDataValue
greaterOrEquals
(DataValueDescriptor left, DataValueDescriptor right) The >= operator as called from the language module, as opposed to the storage module.final BooleanDataValue
greaterThan
(DataValueDescriptor left, DataValueDescriptor right) The > operator as called from the language module, as opposed to the storage module.final int
hashCode()
final boolean
isNull()
see if the Bit value is null.final BooleanDataValue
lessOrEquals
(DataValueDescriptor left, DataValueDescriptor right) The <= operator as called from the language module, as opposed to the storage module.final BooleanDataValue
lessThan
(DataValueDescriptor left, DataValueDescriptor right) The < operator as called from the language module, as opposed to the storage module.final void
Set the value by reading the stream and converting it to an object form.final BooleanDataValue
notEquals
(DataValueDescriptor left, DataValueDescriptor right) The <> operator as called from the language module, as opposed to the storage module.(package private) boolean
objectNull
(Object o) private static int
Read the encoded length of the value from the on-disk format.final void
delegated to bitprivate void
Read the value from an input stream.final void
Restore this object to its (SQL)null value.final InputStream
Return the on-disk stream state of the object.protected final void
setFrom
(DataValueDescriptor theValue) Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.void
setInto
(PreparedStatement ps, int position) Adding this method to ensure that super class' setInto method doesn't get called that leads to the violation of JDBC spec( untyped nulls ) when batching is turned on.final void
setStream
(InputStream newStream) Set me to the value represented by this stream.final void
setValue
(byte[] theValue) Set the value of this DataValueDescriptor.final void
setValue
(InputStream theStream, int valueLength) Set the value from the stream which is in the on-disk format.final void
Set the value of this DataValueDescriptor.final ConcatableDataValue
substring
(NumberDataValue start, NumberDataValue length, ConcatableDataValue result, int maxLen) The SQL substr() function.private void
final String
toString()
(package private) void
truncate
(int sourceWidth, int desiredWidth, boolean warn) Truncate this value to the desired width by removing bytes at the end of the byte sequence.private void
writeBlob
(ObjectOutput out) Serialize a blob using the 8.1 encoding.final void
Write the value out from the byte array (not called if null) using the 8.1 encoding.private void
writeLength
(ObjectOutput out, int len) Write the length if using the 8.1 encoding.Methods inherited from class org.apache.derby.iapi.types.DataType
coalesce, compare, compare, compareTo, dataTypeConversion, equals, flip, genericSetObject, getBoolean, getByte, getDate, getDouble, getFloat, getInt, getLong, getObject, getShort, getTime, getTimestamp, getTypeName, hasStream, in, invalidFormat, isNotNull, isNullOp, normalize, outOfRange, readExternalFromArray, recycle, setBigDecimal, setInto, setObject, setObjectForCast, setToNull, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, throwLangSetMismatch, throwLangSetMismatch, typePrecedence, typeToBigDecimal
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.derby.iapi.types.DataValueDescriptor
coalesce, compare, compare, getBoolean, getByte, getDate, getDouble, getFloat, getInt, getLong, getNewNull, getObject, getShort, getTime, getTimestamp, getTypeName, hasStream, in, isNotNull, isNullOp, normalize, readExternalFromArray, recycle, setBigDecimal, setInto, setObjectForCast, setToNull, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValueFromResultSet, typePrecedence, typeToBigDecimal
Methods inherited from interface org.apache.derby.iapi.services.io.TypedFormat
getTypeFormatId
Methods inherited from interface org.apache.derby.iapi.types.VariableSizeDataValue
setWidth
-
Field Details
-
PAD
static final byte PAD- See Also:
-
BASE_MEMORY_USAGE
private static final int BASE_MEMORY_USAGE -
LEN_OF_BUFFER_TO_WRITE_BLOB
private static final int LEN_OF_BUFFER_TO_WRITE_BLOB- See Also:
-
_blobValue
Blob _blobValue -
dataValue
byte[] dataValue -
stream
InputStream streamValue as a stream, this stream represents the on-disk format of the value. That is it has length information encoded in the first fe bytes. -
streamValueLength
int streamValueLengthLength of the value in bytes when this value is set as a stream. Represents the length of the value itself and not the length of the stream which contains this length encoded as the first few bytes. If the value of the stream is unknown then this will be set to -1. If this value is not set as a stream then this value should be ignored.
-
-
Constructor Details
-
SQLBinary
SQLBinary()Create a binary value set to NULL -
SQLBinary
SQLBinary(byte[] val) -
SQLBinary
SQLBinary(Blob val)
-
-
Method Details
-
estimateMemoryUsage
public int estimateMemoryUsage()Description copied from interface:DataValueDescriptor
Estimate the memory usage in bytes of the data value and the overhead of the class.- Specified by:
estimateMemoryUsage
in interfaceDataValueDescriptor
- Returns:
- the estimated memory usage
-
getMaxMemoryUsage
abstract int getMaxMemoryUsage()Return max memory usage for a SQL Binary -
setValue
public final void setValue(byte[] theValue) Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The byte value to set this DataValueDescriptor to
-
setValue
Description copied from class:DataType
Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override- Specified by:
setValue
in interfaceBitDataValue
- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theValue
- The Blob value to set this DataValueDescriptor to
-
getString
Used by JDBC -- string should not contain SQL92 formatting.- Specified by:
getString
in interfaceDataValueDescriptor
- Returns:
- The data value as a String.
- Throws:
StandardException
- Thrown on error
-
getStream
Description copied from class:DataType
Gets the value in the data stream descriptor as an InputStream. Throws an exception if the data value is not receivable as a stream.- Specified by:
getStream
in interfaceDataValueDescriptor
- Overrides:
getStream
in classDataType
- Returns:
- The data value as an InputStream.
- Throws:
StandardException
- Thrown on error- See Also:
-
getBytes
Description copied from class:DataType
Gets the value in the data value descriptor as a byte[]. Throws an exception if the data value is not receivable as a Binary or Varbinary.- Specified by:
getBytes
in interfaceDataValueDescriptor
- Overrides:
getBytes
in classDataType
- Returns:
- The Binary value as a byte[].
- Throws:
StandardException
- Thrown on error
-
getValue
- Throws:
StandardException
-
getLength
length in bytes- Specified by:
getLength
in interfaceDataValueDescriptor
- Returns:
- The length of the data value
- Throws:
StandardException
- Thrown on error
-
throwStreamingIOException
- Throws:
StandardException
-
isNull
public final boolean isNull()see if the Bit value is null. -
writeExternal
Write the value out from the byte array (not called if null) using the 8.1 encoding.- Specified by:
writeExternal
in interfaceExternalizable
- Throws:
IOException
- io exception
-
writeBlob
Serialize a blob using the 8.1 encoding. Not called if null.- Throws:
IOException
- io exception
-
writeLength
Write the length if using the 8.1 encoding.- Throws:
IOException
- io exception
-
readExternal
delegated to bit- Specified by:
readExternal
in interfaceExternalizable
- Throws:
IOException
- io exceptionClassNotFoundException
- class not found
-
readBinaryLength
Read the encoded length of the value from the on-disk format.- Throws:
IOException
- See Also:
-
readFromStream
Read the value from an input stream. The length encoded in the input stream has already been read and determined to be unknown.- Throws:
IOException
-
restoreToNull
public final void restoreToNull()Description copied from interface:Storable
Restore this object to its (SQL)null value.- Specified by:
restoreToNull
in interfaceStorable
- See Also:
-
compare
public final boolean compare(int op, DataValueDescriptor other, boolean orderedNulls, boolean unknownRV) throws StandardException Description copied from interface:DataValueDescriptor
Compare this Orderable with a given Orderable for the purpose of qualification and sorting. The caller gets to determine how nulls should be treated - they can either be ordered values or unknown values.- Specified by:
compare
in interfaceDataValueDescriptor
- Overrides:
compare
in classDataType
- Parameters:
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.- Returns:
- true if the comparison is true (duh!)
- Throws:
StandardException
- thrown on error
-
compare
Description copied from interface:DataValueDescriptor
Compare this Orderable with a given Orderable for the purpose of index positioning. This method treats nulls as ordered values - that is, it treats SQL null as equal to null and greater than all other values.- Specified by:
compare
in interfaceDataValueDescriptor
- Parameters:
other
- The Orderable to compare this one to.- Returns:
- <0 - this Orderable is less than other. 0 - this Orderable equals other. >0 - this Orderable is greater than other. The code should not explicitly look for -1, or 1.
- Throws:
StandardException
- thrown on error
-
cloneHolder
Shallow clone a StreamStorable without objectifying. This is used to avoid unnecessary objectifying of a stream object. Beetle 4896- Specified by:
cloneHolder
in interfaceDataValueDescriptor
- Overrides:
cloneHolder
in classDataType
- Returns:
- A shallow clone.
-
cloneValue
Description copied from interface:DataValueDescriptor
Clone this DataValueDescriptor. Results in a new object that has the same value as this but can be modified independently.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 ifforceMaterialization
is set tofalse
. An example is if you need to access the value you just read usingcloneValue
after the current transaction has ended, or after the source result set has been closed.- Specified by:
cloneValue
in interfaceDataValueDescriptor
- Parameters:
forceMaterialization
- any streams representing the data value will be materialized iftrue
, the data value will be kept as a stream if possible iffalse
- Returns:
- A clone of the
DataValueDescriptor
with the same initial value as this. - See Also:
-
returnStream
Description copied from interface:StreamStorable
Return the on-disk stream state of the object.- Specified by:
returnStream
in interfaceStreamStorable
-
setStream
Set me to the value represented by this stream. The format of the stream is the on-disk format described in this class's javadoc. That is the length is encoded in the first few bytes of the stream.- Specified by:
setStream
in interfaceStreamStorable
-
loadStream
Description copied from interface:StreamStorable
Set the value by reading the stream and converting it to an object form.- Specified by:
loadStream
in interfaceStreamStorable
- Throws:
StandardException
- on error
-
objectNull
-
setValue
Set the value from the stream which is in the on-disk format.- Specified by:
setValue
in interfaceDataValueDescriptor
- Overrides:
setValue
in classDataType
- Parameters:
theStream
- On disk format of the streamvalueLength
- length of the logical value in bytes, orDataValueDescriptor.UNKNOWN_LOGICAL_LENGTH
-
setFrom
Description copied from class:DataType
Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.- Overrides:
setFrom
in classDataType
- Parameters:
theValue
- The DataValueDescriptor that holds the value to which we want to set this DataValueDescriptor's value.- Throws:
StandardException
-
equals
public final BooleanDataValue equals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The = operator as called from the language module, as opposed to the storage module.- Specified by:
equals
in interfaceDataValueDescriptor
- Overrides:
equals
in classDataType
- Parameters:
left
- The value on the left side of the =right
- The value on the right side of the = is not.- Returns:
- A SQL boolean value telling whether the two parameters are equal
- Throws:
StandardException
- Thrown on error
-
notEquals
public final BooleanDataValue notEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The <> operator as called from the language module, as opposed to the storage module.- Specified by:
notEquals
in interfaceDataValueDescriptor
- Overrides:
notEquals
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the two parameters are not equal
- Throws:
StandardException
- Thrown on error
-
lessThan
public final BooleanDataValue lessThan(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The < operator as called from the language module, as opposed to the storage module.- Specified by:
lessThan
in interfaceDataValueDescriptor
- Overrides:
lessThan
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the first operand is less than the second operand
- Throws:
StandardException
- Thrown on error
-
greaterThan
public final BooleanDataValue greaterThan(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The > operator as called from the language module, as opposed to the storage module.- Specified by:
greaterThan
in interfaceDataValueDescriptor
- Overrides:
greaterThan
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the first operand is greater than the second operand
- Throws:
StandardException
- Thrown on error
-
lessOrEquals
public final BooleanDataValue lessOrEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The <= operator as called from the language module, as opposed to the storage module.- Specified by:
lessOrEquals
in interfaceDataValueDescriptor
- Overrides:
lessOrEquals
in classDataType
- Parameters:
left
- The value on the left side of the operatorright
- The value on the right side of the operator- Returns:
- A SQL boolean value telling whether the first operand is less than or equal to the second operand
- Throws:
StandardException
- Thrown on error
-
greaterOrEquals
public final BooleanDataValue greaterOrEquals(DataValueDescriptor left, DataValueDescriptor right) throws StandardException The >= operator as called from the language module, as opposed to the storage module.- Specified by:
greaterOrEquals
in interfaceDataValueDescriptor
- Overrides:
greaterOrEquals
in classDataType
- Parameters:
left
- The value on the left side of the >=right
- The value on the right side of the >=- Returns:
- A SQL boolean value telling whether the first operand is greater than or equal to the second operand
- Throws:
StandardException
- Thrown on error
-
charLength
This method implements the char_length function for bit.- Specified by:
charLength
in interfaceConcatableDataValue
- Parameters:
result
- The result of a previous call to this method, null if not called yet- Returns:
- A SQLInteger containing the length of the char value
- Throws:
StandardException
- Thrown on error- See Also:
-
concatenate
public final BitDataValue concatenate(BitDataValue left, BitDataValue right, BitDataValue result) throws StandardException Description copied from interface:BitDataValue
The SQL concatenation '||' operator.- Specified by:
concatenate
in interfaceBitDataValue
- Parameters:
left
- String on the left hand side of '||'right
- String on the right hand side of '||'result
- The result of a previous call to this method, null if not called yet.- Returns:
- A ConcatableDataValue containing the result of the '||'
- Throws:
StandardException
- Thrown on error- See Also:
-
substring
public final ConcatableDataValue substring(NumberDataValue start, NumberDataValue length, ConcatableDataValue result, int maxLen) throws StandardException The SQL substr() function.- Specified by:
substring
in interfaceConcatableDataValue
- Parameters:
start
- Start of substrlength
- Length of substrresult
- The result of a previous call to this method, null if not called yet.maxLen
- Maximum length of the result- Returns:
- A ConcatableDataValue containing the result of the substr()
- Throws:
StandardException
- Thrown on error
-
checkHostVariable
Host variables are rejected if their length is bigger than the declared length, regardless of if the trailing bytes are the pad character.- Specified by:
checkHostVariable
in interfaceDataValueDescriptor
- Overrides:
checkHostVariable
in classDataType
- Throws:
StandardException
- Variable is too big.
-
toString
-
hashCode
public final int hashCode() -
compare
private static int compare(byte[] left, byte[] right) -
setInto
Adding this method to ensure that super class' setInto method doesn't get called that leads to the violation of JDBC spec( untyped nulls ) when batching is turned on.- Specified by:
setInto
in interfaceDataValueDescriptor
- Overrides:
setInto
in classDataType
- Throws:
SQLException
- thrown by the PreparedStatement objectStandardException
- thrown by me accessing my value.
-
getTraceString
Gets a trace representation for debugging.- Specified by:
getTraceString
in interfaceDataValueDescriptor
- Overrides:
getTraceString
in classDataType
- Returns:
- a trace representation of this SQL DataType.
- Throws:
StandardException
- if getting the data value fails.- See Also:
-
getBlobLength
- Throws:
StandardException
-
truncate
Truncate this value to the desired width by removing bytes at the end of the byte sequence.- Parameters:
sourceWidth
- the original width in bytes (only used for diagnostics, ignored ifwarn
isfalse
)desiredWidth
- the desired width in byteswarn
- whether or not to generate a truncation warning- Throws:
StandardException
-