com.pivotal.gemfirexd.internal.client.am

## Class Blob

- java.lang.Object
- - com.pivotal.gemfirexd.internal.client.am.Lob
  - - com.pivotal.gemfirexd.internal.client.am.Blob

All Implemented Interfaces:
  UnitOfWorkListener, Blob

    public class Blob
    extends Lob
    implements Blob

### Field Summary

### Fields inherited from class com.pivotal.gemfirexd.internal.client.am.Lob

`agent_, ASCII_STREAM, BINARY_STREAM, BINARY_STRING, CHARACTER_STREAM, columnName, dataType_, INVALID_LOCATOR, isValid_, LOB_OBJECT_LENGTH_UNKNOWN_YET, LOCATOR, locator_, locatorProcs_, STRING, UNICODE_STREAM`

### Constructor Summary

Constructors
Constructor and Description
`Blob(Agent agent, InputStream binaryStream, int length, String columnName)`
`Blob(Agent agent, InputStream binaryStream, String columnName)` Create a new `Blob` from a stream with unknown length.
`Blob(Agent agent, int locator, String columnName)` Create a `Blob` object for a Blob value stored on the server and indentified by `locator`.
`Blob(byte[] binaryString, Agent agent, int dataOffset, String columnName)`

### Method Summary

Methods
`protected long` `binaryStringPosition(byte[] pattern, long start)`
`void` `free()` This method frees the `Blob` object and releases the resources that it holds.
`InputStream` `getBinaryStream()`
`InputStream` `getBinaryStream(long pos, long length)` Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length.
`byte[]` `getBinaryString()`
`byte[]` `getBytes(long pos, int length)` Returns as an array of bytes part or all of the `BLOB` value that this `Blob` object designates.
`boolean` `isBinaryStream()`
`boolean` `isBinaryString()`
`protected boolean` `isSubString(byte[] pattern, int index)`
`long` `length()`
`protected void` `materializeStream()` Materialize the stream used for input to the database.
`long` `position(Blob pattern, long start)`
`long` `position(byte[] pattern, long start)`
`OutputStream` `setBinaryStream(long pos)`
`int` `setBytes(long pos, byte[] bytes)`
`int` `setBytes(long pos, byte[] bytes, int offset, int len)`
`int` `setBytesX(long pos, byte[] bytes, int offset, int len)`
`void` `truncate(long len)`

### Methods inherited from class com.pivotal.gemfirexd.internal.client.am.Lob

`checkPosAndLength, checkValidity, completeLocalCommit, completeLocalRollback, finalize, getAgent, getLocator, incrementUpdateCount, isLayerBStreamingPossible, isLengthObtained, isLocator, listenToUnitOfWork, materializeStream, willBeLayerBStreamed`

### Methods inherited from class java.lang.Object

`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### Blob

    public Blob(byte[] binaryString,
        Agent agent,
        int dataOffset,
        String columnName)

#### Blob

    public Blob(Agent agent,
        InputStream binaryStream,
        int length,
        String columnName)

#### Blob

    public Blob(Agent agent,
        InputStream binaryStream,
        String columnName)

Create a new `Blob` from a stream with unknown length. Important: This constructor is a temporary solution for implementing lengthless overloads in the JDBC4 API. Before a proper solution can be implemented, we need to enable streaming without having to know the stream length in the DRDA protocol. See Jira DERBY-1471 and DERBY-1417 for more details. Shortcomings: This constructor will cause the whole stream to be materialized to determine its length. If the stream is big enough, the client will fail with an OutOfMemoryError. Since this is a temporary solution, state checking is not added to all methods as it would clutter up the class severely. After using the constructor, the `length`-method must be called, which will materialize the stream and determine the length. Do not pass a Blob object created with this constructor to the user!

Parameters:
  `agent` -
  `binaryStream` - the stream to get data from

#### Blob

    public Blob(Agent agent,
        int locator,
        String columnName)

Create a `Blob` object for a Blob value stored on the server and indentified by `locator`.

Parameters:
  `agent` - context for this Blob object (incl. connection)
  `locator` - reference id to Blob value on server

### Method Detail

#### length

    public long length()
                throws SQLException

Specified by:
  `length` in interface `Blob`
Specified by:
  `length` in class `Lob`
Throws:
  `SQLException`

#### getBytes

    public byte[] getBytes(long pos,
                  int length)
                    throws SQLException

Returns as an array of bytes part or all of the `BLOB` value that this `Blob` object designates. The byte array contains up to `length` consecutive bytes starting at position `pos`. The starting position must be between 1 and the length of the BLOB plus 1. This allows for zero-length BLOB values, from which only zero-length byte arrays can be returned. If a larger length is requested than there are bytes available, characters from the start position to the end of the BLOB are returned.

Specified by:
  `getBytes` in interface `Blob`
Parameters:
  `pos` - the ordinal position of the first byte in the `BLOB` value to be extracted; the first byte is at position 1
  `length` - is the number of consecutive bytes to be copied
Returns:
  a byte array containing up to `length` consecutive bytes from the `BLOB` value designated by this `Blob` object, starting with the byte at position `startPos`.
Throws:
  `SQLException` - if there is an error accessing the `BLOB` NOTE: If the starting position is the length of the BLOB plus 1, zero bytess are returned regardless of the length requested.

#### getBinaryStream

    public InputStream getBinaryStream()
                                throws SQLException

Specified by:
  `getBinaryStream` in interface `Blob`
Throws:
  `SQLException`

#### position

    public long position(byte[] pattern,
                long start)
                  throws SQLException

Specified by:
  `position` in interface `Blob`
Throws:
  `SQLException`

#### position

    public long position(Blob pattern,
                long start)
                  throws SQLException

Specified by:
  `position` in interface `Blob`
Throws:
  `SQLException`

#### setBytes

    public int setBytes(long pos,
               byte[] bytes)
                 throws SQLException

Specified by:
  `setBytes` in interface `Blob`
Throws:
  `SQLException`

#### setBytes

    public int setBytes(long pos,
               byte[] bytes,
               int offset,
               int len)
                 throws SQLException

Specified by:
  `setBytes` in interface `Blob`
Throws:
  `SQLException`

#### setBytesX

    public int setBytesX(long pos,
                byte[] bytes,
                int offset,
                int len)
                  throws SqlException

Throws:
  `SqlException`

#### setBinaryStream

    public OutputStream setBinaryStream(long pos)
                                 throws SQLException

Specified by:
  `setBinaryStream` in interface `Blob`
Throws:
  `SQLException`

#### truncate

    public void truncate(long len)
                  throws SQLException

Specified by:
  `truncate` in interface `Blob`
Throws:
  `SQLException`

#### free

    public void free()
              throws SQLException

This method frees the `Blob` object and releases the resources that it holds. The object is invalid once the `free` method is called. If `free` is called multiple times, the subsequent calls to `free` are treated as a no-op.

Specified by:
  `free` in interface `Blob`
Throws:
  `SQLException` - if an error occurs releasing the Blob's resources

#### getBinaryStream

    public InputStream getBinaryStream(long pos,
                              long length)
                                throws SQLException

Returns an `InputStream` object that contains a partial `Blob` value, starting with the byte specified by pos, which is length bytes in length.

Specified by:
  `getBinaryStream` in interface `Blob`
Parameters:
  `pos` - the offset to the first byte of the partial value to be retrieved. The first byte in the `Blob` is at position 1.
  `length` - the length in bytes of the partial value to be retrieved
Returns:
  `InputStream` through which the partial `Blob` value can be read.
Throws:
  `SQLException` - if pos is less than 1 or if pos is greater than the number of bytes in the `Blob` or if pos + length is greater than the number of bytes in the `Blob`

#### isBinaryString

    public boolean isBinaryString()

#### isBinaryStream

    public boolean isBinaryStream()

#### getBinaryString

    public byte[] getBinaryString()

#### binaryStringPosition

    protected long binaryStringPosition(byte[] pattern,
                            long start)

#### isSubString

    protected boolean isSubString(byte[] pattern,
                      int index)

#### materializeStream

    protected void materializeStream()
                              throws SqlException

Materialize the stream used for input to the database.

Specified by:
  `materializeStream` in class `Lob`
Throws:
  `SqlException`