# Blob

public interface **Blob** The representation (mapping) in
the Java^TM^ programming
language of an SQL
`BLOB` value. An SQL `BLOB` is a built-in type
that stores a Binary Large Object as a column value in a row of
a database table. By default drivers implement `Blob` using
an SQL `locator(BLOB)`, which means that a
`Blob` object contains a logical pointer to the
SQL `BLOB` data rather than the data itself.
A `Blob` object is valid for the duration of the
transaction in which is was created.

Methods in the interfaces `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/ResultSet.html`,
`https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/CallableStatement.html`, and `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/PreparedStatement.html`, such as
`getBlob` and `setBlob` allow a programmer to
access an SQL `BLOB` value.
The `Blob` interface provides methods for getting the
length of an SQL `BLOB` (Binary Large Object) value,
for materializing a `BLOB` value on the client, and for
determining the position of a pattern of bytes within a
`BLOB` value. In addition, this interface has methods for updating
a `BLOB` value.


All methods on the `Blob` interface must be fully implemented if the
JDBC driver supports the data type.

### Public Method Summary

|---|---|
| abstract void | [free](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#free())() This method frees the `Blob` object and releases the resources that it holds. |
| abstract [InputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/InputStream.html) | [getBinaryStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#getBinaryStream(long,%20long))(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. |
| abstract [InputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/InputStream.html) | [getBinaryStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#getBinaryStream())() Retrieves the `BLOB` value designated by this `Blob` instance as a stream. |
| abstract byte\[\] | [getBytes](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#getBytes(long,%20int))(long pos, int length) Retrieves all or part of the `BLOB` value that this `Blob` object represents, as an array of bytes. |
| abstract long | [length](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#length())() Returns the number of bytes in the `BLOB` value designated by this `Blob` object. |
| abstract long | [position](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#position(java.sql.Blob,%20long))([Blob](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html) pattern, long start) Retrieves the byte position in the `BLOB` value designated by this `Blob` object at which `pattern` begins. |
| abstract long | [position](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#position(byte[],%20long))(byte\[\] pattern, long start) Retrieves the byte position at which the specified byte array `pattern` begins within the `BLOB` value that this `Blob` object represents. |
| abstract [OutputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/OutputStream.html) | [setBinaryStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#setBinaryStream(long))(long pos) Retrieves a stream that can be used to write to the `BLOB` value that this `Blob` object represents. |
| abstract int | [setBytes](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#setBytes(long,%20byte[],%20int,%20int))(long pos, byte\[\] bytes, int offset, int len) Writes all or part of the given `byte` array to the `BLOB` value that this `Blob` object represents and returns the number of bytes written. |
| abstract int | [setBytes](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#setBytes(long,%20byte[]))(long pos, byte\[\] bytes) Writes the given array of bytes to the `BLOB` value that this `Blob` object represents, starting at position `pos`, and returns the number of bytes written. |
| abstract void | [truncate](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#truncate(long))(long len) Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length. |

## Public Methods

#### public abstract void
**free**
()

This method frees the `Blob` object and releases the resources that
it holds. The object is invalid once the `free`
method is called.


After `free` has been called, any attempt to invoke a
method other than `free` will result in a `SQLException`
being thrown. If `free` is called multiple times, the subsequent
calls to `free` are treated as a no-op.

<br />

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if an error occurs releasing the Blob's resources |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract [InputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/InputStream.html)
**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.

##### 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | 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` |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract [InputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/InputStream.html)
**getBinaryStream**
()

Retrieves the `BLOB` value designated by this
`Blob` instance as a stream.

##### Returns

- a stream containing the `BLOB` data

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` value |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#setBinaryStream(long)`

#### public abstract byte\[\]
**getBytes**
(long pos, int length)

Retrieves all or part of the `BLOB`
value that this `Blob` object represents, as an array of
bytes. This `byte` array contains up to `length`
consecutive bytes starting at position `pos`.

##### Parameters

| pos | the ordinal position of the first byte in the `BLOB` value to be extracted; the first byte is at position 1 |
| length | the number of consecutive bytes to be copied; the value for length must be 0 or greater |
|---|---|

##### 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 `pos`

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` value; if pos is less than 1 or length is less than 0 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#setBytes(long,%20byte[])`

#### public abstract long
**length**
()

Returns the number of bytes in the `BLOB` value
designated by this `Blob` object.

##### Returns

- length of the `BLOB` in bytes

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the length of the `BLOB` |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract long
**position**
([Blob](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html) pattern, long start)

Retrieves the byte position in the `BLOB` value
designated by this `Blob` object at which
`pattern` begins. The search begins at position
`start`.

##### Parameters

| pattern | the `Blob` object designating the `BLOB` value for which to search |
| start | the position in the `BLOB` value at which to begin searching; the first position is 1 |
|---|---|

##### Returns

- the position at which the pattern begins, else -1

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` value or if start is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract long
**position**
(byte\[\] pattern, long start)

Retrieves the byte position at which the specified byte array
`pattern` begins within the `BLOB`
value that this `Blob` object represents. The
search for `pattern` begins at position
`start`.

##### Parameters

| pattern | the byte array for which to search |
| start | the position at which to begin searching; the first position is 1 |
|---|---|

##### Returns

- the position at which the pattern appears, else -1

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` or if start is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

#### public abstract [OutputStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/io/OutputStream.html)
**setBinaryStream**
(long pos)

Retrieves a stream that can be used to write to the `BLOB`
value that this `Blob` object represents. The stream begins
at position `pos`.
The bytes written to the stream will overwrite the existing bytes
in the `Blob` object starting at the position
`pos`. If the end of the `Blob` value is reached
while writing to the stream, then the length of the `Blob`
value will be increased to accomodate the extra bytes.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `BLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`SQLException` while other drivers may support this
operation.

##### Parameters

| pos | the position in the `BLOB` value at which to start writing; the first position is 1 |
|---|---|

##### Returns

- a `java.io.OutputStream` object to which data can be written

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#getBinaryStream()`

#### public abstract int
**setBytes**
(long pos, byte\[\] bytes, int offset, int len)

Writes all or part of the given `byte` array to the
`BLOB` value that this `Blob` object represents
and returns the number of bytes written.
Writing starts at position `pos` in the `BLOB`
value; `len` bytes from the given byte array are written.
The array of bytes will overwrite the existing bytes
in the `Blob` object starting at the position
`pos`. If the end of the `Blob` value is reached
while writing the array of bytes, then the length of the `Blob`
value will be increased to accomodate the extra bytes.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `BLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`SQLException` while other drivers may support this
operation.

##### Parameters

| pos | the position in the `BLOB` object at which to start writing; the first position is 1 |
| bytes | the array of bytes to be written to this `BLOB` object |
| offset | the offset into the array `bytes` at which to start reading the bytes to be set |
| len | the number of bytes to be written to the `BLOB` value from the array of bytes `bytes` |
|---|---|

##### Returns

- the number of bytes written

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#getBytes(long,%20int)`

#### public abstract int
**setBytes**
(long pos, byte\[\] bytes)

Writes the given array of bytes to the `BLOB` value that
this `Blob` object represents, starting at position
`pos`, and returns the number of bytes written.
The array of bytes will overwrite the existing bytes
in the `Blob` object starting at the position
`pos`. If the end of the `Blob` value is reached
while writing the array of bytes, then the length of the `Blob`
value will be increased to accomodate the extra bytes.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `BLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`SQLException` while other drivers may support this
operation.

##### Parameters

| pos | the position in the `BLOB` object at which to start writing; the first position is 1 |
| bytes | the array of bytes to be written to the `BLOB` value that this `Blob` object represents |
|---|---|

##### Returns

- the number of bytes written

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` value or if pos is less than 1 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/Blob.html#getBytes(long,%20int)`

#### public abstract void
**truncate**
(long len)

Truncates the `BLOB` value that this `Blob`
object represents to be `len` bytes in length.


**Note:** If the value specified for `pos`
is greater then the length+1 of the `BLOB` value then the
behavior is undefined. Some JDBC drivers may throw a
`SQLException` while other drivers may support this
operation.

##### Parameters

| len | the length, in bytes, to which the `BLOB` value that this `Blob` object represents should be truncated |
|---|---|

##### Throws

| [SQLException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLException.html) | if there is an error accessing the `BLOB` value or if len is less than 0 |
| [SQLFeatureNotSupportedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/sql/SQLFeatureNotSupportedException.html) | if the JDBC driver does not support this method |
|---|---|