com.almworks.sqlite4java
Class SQLiteBlob

java.lang.Object
  com.almworks.sqlite4java.SQLiteBlob

public final class SQLiteBlob
extends java.lang.Object

SQLiteBlob encapsulates sqlite3_blob* handle, which represents an open BLOB (binary large object), stored in a single cell of a table.

SQLiteBlob is created by SQLiteConnection.blob(java.lang.String, java.lang.String, java.lang.String, long, boolean) method. After application is done using the instance of SQLiteBlob, it should be disposed with dispose() method.

You can read or write portions of the stored blob using read(int, byte[], int, int) and write(int, byte[], int, int) methods. Note that you cannot change the size of the blob using this interface.

Methods of this class are not thread-safe and confined to the thread that opened the SQLite connection.

Author:

Igor Sereda

See Also:

SQLiteConnection.blob(java.lang.String, java.lang.String, java.lang.String, long, boolean), sqlite3_blob_open

Method Summary

void	dispose() Disposes this blob and frees allocated resources.
int	getSize() Returns the size of the open blob.
boolean	isDisposed() Checks if this instance has been disposed
boolean	isWriteAllowed() Returns true if this blob instance was opened for writing.
void	read(int blobOffset, byte[] buffer, int offset, int length) Read bytes from the blob into a buffer.
void	reopen(long rowid) Repositions BLOB to another row in the table.
java.lang.String	toString()
void	write(int blobOffset, byte[] buffer, int offset, int length) Writes bytes into the blob.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

dispose

public void dispose()

Disposes this blob and frees allocated resources.

After blob is disposed, it is no longer usable and holds no references to connection or sqlite db.

isDisposed

public boolean isDisposed()

Checks if this instance has been disposed

Returns:

true if the blob is disposed and cannot be used

getSize

public int getSize()
            throws SQLiteException

Returns the size of the open blob. The size cannot be changed via this interface.

Returns:

size of the blobs in bytes

Throws:

SQLiteException - if SQLite returns an error, or if the call violates the contract of this class

read

public void read(int blobOffset,
                 byte[] buffer,
                 int offset,
                 int length)
          throws SQLiteException

Read bytes from the blob into a buffer.

blobOffset and length should define a sub-range within blob's content. If attempt is made to read blob beyond its size, an exception is thrown and no data is read.

Parameters:

blobOffset - the position in the blob where to start reading

buffer - target buffer

offset - starting offset in the buffer

length - number of bytes to read

Throws:

SQLiteException - if SQLite returns an error, or if the call violates the contract of this class

See Also:

sqlite3_blob_read

write

public void write(int blobOffset,
                  byte[] buffer,
                  int offset,
                  int length)
           throws SQLiteException

Writes bytes into the blob. Bytes are taken from the specified range in the input byte buffer.

Note that you cannot write beyond the current blob's size. The size of the blob cannot be changed via incremental I/O API. To change the size, you need to use SQLiteStatement.bindZeroBlob(int, int) method.

Bytes are written within the current transaction.

If blob was not open for writing, an error is thrown.

Parameters:

blobOffset - the position in the blob where to start writing

buffer - source bytes buffer

offset - starting offset in the buffer

length - number of bytes to write

Throws:

SQLiteException - if SQLite returns an error, or if the call violates the contract of this class

See Also:

sqlite3_blob_write

isWriteAllowed

public boolean isWriteAllowed()

Returns true if this blob instance was opened for writing.

Returns:

true if write(int, byte[], int, int) is allowed

reopen

public void reopen(long rowid)
            throws SQLiteException

Repositions BLOB to another row in the table. It should be quickier that closing the blob and opening another one.

Parameters:

rowid - row id to move to - it must exist and contain data

Throws:

SQLiteException - if SQLite returns an error, or if the call violates the contract of this class

See Also:

sqlite3_blob_reopen

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object