Package org.apache.derby.iapi.types

Class SQLBinary

  • All Implemented Interfaces:
    java.io.Externalizable, java.io.Serializable, java.lang.Comparable, Formatable, Storable, StreamStorable, TypedFormat, BitDataValue, ConcatableDataValue, DataValueDescriptor, Orderable, VariableSizeDataValue
    Direct Known Subclasses:
    SQLBit, SQLBlob
    abstract class SQLBinary
extends DataType
implements BitDataValue
    SQLBinary is the abstract class for the binary datatypes.
    • 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.
    is one of N styles.

    • (5.x format zero) 4 byte Java format integer value 0 - either is 0 bytes/bits or an unknown number of bytes.
    • (5.x format bits) 4 byte Java format integer value >0 (positive) - number of bits in raw data, number of bytes in is the minimum number of bytes required to store the number of bits.
    • (Derby format) 1 byte encoded length (0 <= L <= 31) - number of bytes of raw data - encoded = 0x80 & L
    • (Derby format) 3 byte encoded length (32 <= L < 64k) - number of bytes of raw data - encoded = 0xA0
    • (Derby format) 5 byte encoded length (64k <= L < 2G) - number of bytes of raw data - encoded = 0xC0
    • (future) to be determined L >= 2G - encoded 0xE0 (0xE0 is an esacape to allow any number of arbitary encodings in the future).

    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 Detail

      • 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:
        Constant Field Values

      • _blobValue

        java.sql.Blob _blobValue

      • dataValue

        byte[] dataValue

      • stream

        java.io.InputStream stream
        Value 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 streamValueLength
        Length 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 Detail

      • SQLBinary

        SQLBinary()
        Create a binary value set to NULL

      • SQLBinary

        SQLBinary​(byte[] val)

      • SQLBinary

        SQLBinary​(java.sql.Blob val)

    • Method Detail

      • 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 interface DataValueDescriptor
        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 interface DataValueDescriptor
        Overrides:
        setValue in class DataType
        Parameters:
        theValue - The byte value to set this DataValueDescriptor to

      • setValue

        public final void setValue​(java.sql.Blob 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 interface BitDataValue
        Specified by:
        setValue in interface DataValueDescriptor
        Overrides:
        setValue in class DataType
        Parameters:
        theValue - The Blob value to set this DataValueDescriptor to

      • getBytes

        public final byte[] getBytes()
                      throws StandardException
        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 interface DataValueDescriptor
        Overrides:
        getBytes in class DataType
        Returns:
        The Binary value as a byte[].
        Throws:
        StandardException - Thrown on error

      • isNull

        public final boolean isNull()
        see if the Bit value is null.
        Specified by:
        isNull in interface Storable
        Returns:
        true if the value is null and false otherwise.
        See Also:
        Storable.isNull()

      • writeExternal

        public final void writeExternal​(java.io.ObjectOutput out)
                         throws java.io.IOException
        Write the value out from the byte array (not called if null) using the 8.1 encoding.
        Specified by:
        writeExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException - io exception

      • writeBlob

        private void writeBlob​(java.io.ObjectOutput out)
                throws java.io.IOException
        Serialize a blob using the 8.1 encoding. Not called if null.
        Throws:
        java.io.IOException - io exception

      • writeLength

        private void writeLength​(java.io.ObjectOutput out,
                         int len)
                  throws java.io.IOException
        Write the length if using the 8.1 encoding.
        Throws:
        java.io.IOException - io exception

      • readExternal

        public final void readExternal​(java.io.ObjectInput in)
                        throws java.io.IOException
        delegated to bit
        Specified by:
        readExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException - io exception
        java.lang.ClassNotFoundException - class not found

      • readBinaryLength

        private static int readBinaryLength​(java.io.ObjectInput in)
                             throws java.io.IOException
        Read the encoded length of the value from the on-disk format.
        Throws:
        java.io.IOException
        See Also:
        SQLBinary

      • readFromStream

        private void readFromStream​(java.io.InputStream in)
                     throws java.io.IOException
        Read the value from an input stream. The length encoded in the input stream has already been read and determined to be unknown.
        Throws:
        java.io.IOException

      • 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 interface DataValueDescriptor
        Overrides:
        compare in class DataType
        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

        public final int compare​(DataValueDescriptor other)
                  throws StandardException
        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 interface DataValueDescriptor
        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

      • cloneValue

        public DataValueDescriptor cloneValue​(boolean forceMaterialization)
        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 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.

        Specified by:
        cloneValue in interface DataValueDescriptor
        Parameters:
        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
        Returns:
        A clone of the DataValueDescriptor with the same initial value as this.
        See Also:
        DataValueDescriptor.cloneValue(boolean)

      • returnStream

        public final java.io.InputStream returnStream()
        Description copied from interface: StreamStorable
        Return the on-disk stream state of the object.
        Specified by:
        returnStream in interface StreamStorable

      • setStream

        public final void setStream​(java.io.InputStream newStream)
        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 interface StreamStorable

      • objectNull

        boolean objectNull​(java.lang.Object o)

      • setValue

        public final void setValue​(java.io.InputStream theStream,
                           int valueLength)
        Set the value from the stream which is in the on-disk format.
        Specified by:
        setValue in interface DataValueDescriptor
        Overrides:
        setValue in class DataType
        Parameters:
        theStream - On disk format of the stream
        valueLength - length of the logical value in bytes, or DataValueDescriptor.UNKNOWN_LOGICAL_LENGTH

      • setFrom

        protected final void setFrom​(DataValueDescriptor theValue)
                      throws StandardException
        Description copied from class: DataType
        Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.
        Overrides:
        setFrom in class DataType
        Parameters:
        theValue - The DataValueDescriptor that holds the value to which we want to set this DataValueDescriptor's value.
        Throws:
        StandardException

      • toString

        public final java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • compare

        private static int compare​(byte[] left,
                           byte[] right)

      • setInto

        public void setInto​(java.sql.PreparedStatement ps,
                    int position)
             throws java.sql.SQLException,
                    StandardException
        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 interface DataValueDescriptor
        Overrides:
        setInto in class DataType
        Throws:
        java.sql.SQLException - thrown by the PreparedStatement object
        StandardException - thrown by me accessing my value.

      • truncate

        void truncate​(int sourceWidth,
              int desiredWidth,
              boolean warn)
       throws StandardException
        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 if warn is false)
        desiredWidth - the desired width in bytes
        warn - whether or not to generate a truncation warning
        Throws:
        StandardException