Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

# Blob

` public interface Blob `   
` `

|---|
| java.sql.Blob |

<br />

*** ** * ** ***

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://developer.android.com/reference/java/sql/ResultSet`, `https://developer.android.com/reference/java/sql/CallableStatement`, and `https://developer.android.com/reference/java/sql/PreparedStatement`, 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.

## Summary

| ### Public methods ||
|---|---|
| ` abstract void` | ` https://developer.android.com/reference/java/sql/Blob#free()() ` This method frees the `Blob` object and releases the resources that it holds. |
| ` abstract https://developer.android.com/reference/java/io/InputStream` | ` https://developer.android.com/reference/java/sql/Blob#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 https://developer.android.com/reference/java/io/InputStream` | ` https://developer.android.com/reference/java/sql/Blob#getBinaryStream()() ` Retrieves the `BLOB` value designated by this `Blob` instance as a stream. |
| ` abstract byte[]` | ` https://developer.android.com/reference/java/sql/Blob#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` | ` https://developer.android.com/reference/java/sql/Blob#length()() ` Returns the number of bytes in the `BLOB` value designated by this `Blob` object. |
| ` abstract long` | ` https://developer.android.com/reference/java/sql/Blob#position(java.sql.Blob,%20long)(https://developer.android.com/reference/java/sql/Blob pattern, long start) ` Retrieves the byte position in the `BLOB` value designated by this `Blob` object at which `pattern` begins. |
| ` abstract long` | ` https://developer.android.com/reference/java/sql/Blob#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 https://developer.android.com/reference/java/io/OutputStream` | ` https://developer.android.com/reference/java/sql/Blob#setBinaryStream(long)(long pos) ` Retrieves a stream that can be used to write to the `BLOB` value that this `Blob` object represents. |
| ` abstract int` | ` https://developer.android.com/reference/java/sql/Blob#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` | ` https://developer.android.com/reference/java/sql/Blob#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` | ` https://developer.android.com/reference/java/sql/Blob#truncate(long)(long len) ` Truncates the `BLOB` value that this `Blob` object represents to be `len` bytes in length. |

## Public methods

### free

Added in [API level 9](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 />

<br />

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if an error occurs releasing the Blob's resources |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### getBinaryStream

Added in [API level 9](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the offset to the first byte of the partial value to be retrieved. The first byte in the `Blob` is at position 1 <br /> |
| `length` | `long`: the length in bytes of the partial value to be retrieved <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/InputStream` | `InputStream` through which the partial `Blob` value can be read. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/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` |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### getBinaryStream

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract InputStream getBinaryStream ()
```

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

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/InputStream` | a stream containing the `BLOB` data <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` value |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Blob#setBinaryStream(long)`

### getBytes

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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`.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the ordinal position of the first byte in the `BLOB` value to be extracted; the first byte is at position 1 <br /> |
| `length` | `int`: the number of consecutive bytes to be copied; the value for length must be 0 or greater <br /> |

| Returns ||
|---|---|
| `byte[]` | 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` <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` value; if pos is less than 1 or length is less than 0 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Blob#setBytes(long,%20byte[])`

### length

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract long length ()
```

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

<br />

| Returns ||
|---|---|
| `long` | length of the `BLOB` in bytes <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the length of the `BLOB` |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### position

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract long position (Blob 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`.

<br />

| Parameters ||
|---|---|
| `pattern` | `Blob`: the `Blob` object designating the `BLOB` value for which to search <br /> |
| `start` | `long`: the position in the `BLOB` value at which to begin searching; the first position is 1 <br /> |

| Returns ||
|---|---|
| `long` | the position at which the pattern begins, else -1 <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` value or if start is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### position

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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`.

<br />

| Parameters ||
|---|---|
| `pattern` | `byte`: the byte array for which to search <br /> |
| `start` | `long`: the position at which to begin searching; the first position is 1 <br /> |

| Returns ||
|---|---|
| `long` | the position at which the pattern appears, else -1 <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` or if start is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

### setBinaryStream

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public abstract OutputStream 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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the position in the `BLOB` value at which to start writing; the first position is 1 <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/io/OutputStream` | a `java.io.OutputStream` object to which data can be written <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Blob#getBinaryStream()`

### setBytes

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the position in the `BLOB` object at which to start writing; the first position is 1 <br /> |
| `bytes` | `byte`: the array of bytes to be written to this `BLOB` object <br /> |
| `offset` | `int`: the offset into the array `bytes` at which to start reading the bytes to be set <br /> |
| `len` | `int`: the number of bytes to be written to the `BLOB` value from the array of bytes `bytes` <br /> |

| Returns ||
|---|---|
| `int` | the number of bytes written <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Blob#getBytes(long,%20int)`

### setBytes

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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.

<br />

| Parameters ||
|---|---|
| `pos` | `long`: the position in the `BLOB` object at which to start writing; the first position is 1 <br /> |
| `bytes` | `byte`: the array of bytes to be written to the `BLOB` value that this `Blob` object represents <br /> |

| Returns ||
|---|---|
| `int` | the number of bytes written <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` value or if pos is less than 1 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |

**See also:**

- `https://developer.android.com/reference/java/sql/Blob#getBytes(long,%20int)`

### truncate

Added in [API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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.

<br />

| Parameters ||
|---|---|
| `len` | `long`: the length, in bytes, to which the `BLOB` value that this `Blob` object represents should be truncated <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/sql/SQLException` | if there is an error accessing the `BLOB` value or if len is less than 0 |
| `https://developer.android.com/reference/java/sql/SQLFeatureNotSupportedException` | if the JDBC driver does not support this method |