com.amazon.carbonado.lob
Interface Blob

All Superinterfaces:

Lob

All Known Implementing Classes:

AbstractBlob, ByteArrayBlob, FileBlob

public interface Blob
extends Lob

Provides access to BLOBs, which are Binary Large OBjects. Consider accessing Blobs within a transaction scope, to prevent unexpected updates.

Author:

Brian S O'Neill

See Also:

Clob

Method Summary

String	asString() Convenience method to capture all the Blob data as a single String, assuming UTF-8 encoding.
String	asString(Charset charset) Convenience method to capture all the Blob data as a single String, decoded against the given charset.
String	asString(String charsetName) Convenience method to capture all the Blob data as a single String, decoded against the given charset.
long	getLength() Returns the length of this Blob, in bytes.
InputStream	openInputStream() Returns an InputStream for reading Blob data positioned at the start.
InputStream	openInputStream(long pos) Returns an InputStream for reading Blob data.
InputStream	openInputStream(long pos, int bufferSize) Returns an InputStream for reading Blob data.
OutputStream	openOutputStream() Returns an OutputStream for writing Blob data, positioned at the start.
OutputStream	openOutputStream(long pos) Returns an OutputStream for writing Blob data.
OutputStream	openOutputStream(long pos, int bufferSize) Returns an OutputStream for writing Blob data.
void	setLength(long length) Set the length of this Blob, in bytes.
void	setValue(String value) Convenience method to overwrite all Blob data with the value of a single String, applying UTF-8 encoding.
void	setValue(String value, Charset charset) Convenience method to overwrite all Blob data with the value of a single String, applying the given charset encoding.
void	setValue(String value, String charsetName) Convenience method to overwrite all Blob data with the value of a single String, applying the given charset encoding.

Methods inherited from interface com.amazon.carbonado.lob.Lob

equals, getLocator

Method Detail

openInputStream

InputStream openInputStream()
                            throws FetchException

Returns an InputStream for reading Blob data positioned at the start. The Blob implementation selects an appropriate buffer size for the stream.

Returns:

InputStream for this Blob, which is not guaranteed to be thread-safe

Throws:

IllegalArgumentException - if position is negative

FetchException

openInputStream

InputStream openInputStream(long pos)
                            throws FetchException

Returns an InputStream for reading Blob data. The Blob implementation selects an appropriate buffer size for the stream.

Parameters:

pos - desired zero-based position to read from

Returns:

InputStream for this Blob, which is not guaranteed to be thread-safe

Throws:

IllegalArgumentException - if position is negative

FetchException

openInputStream

InputStream openInputStream(long pos,
                            int bufferSize)
                            throws FetchException

Returns an InputStream for reading Blob data. A suggested buffer size must be provided, but it might be ignored by the Blob implementation.

Parameters:

pos - desired zero-based position to read from

bufferSize - suggest that the input stream buffer be at least this large (in bytes)

Returns:

InputStream for this Blob, which is not guaranteed to be thread-safe

Throws:

IllegalArgumentException - if position is negative

FetchException

getLength

long getLength()
               throws FetchException

Returns the length of this Blob, in bytes.

Throws:

FetchException

asString

String asString()
                throws FetchException

Convenience method to capture all the Blob data as a single String, assuming UTF-8 encoding. Call within a transaction scope to ensure the data does not change while the String is being built.

Throws:

IllegalArgumentException - if resulting String length would be greater than Integer.MAX_VALUE

OutOfMemoryError - if not enough memory to hold Blob as a single String

FetchException

asString

String asString(String charsetName)
                throws FetchException

Convenience method to capture all the Blob data as a single String, decoded against the given charset. Call within a transaction scope to ensure the data does not change while the String is being built.

Parameters:

charsetName - name of character set to decode String

Throws:

IllegalCharsetNameException - if the given charset name is illegal

IllegalArgumentException - if resulting String length would be greater than Integer.MAX_VALUE

OutOfMemoryError - if not enough memory to hold Blob as a single String

FetchException

asString

String asString(Charset charset)
                throws FetchException

Convenience method to capture all the Blob data as a single String, decoded against the given charset. Call within a transaction scope to ensure the data does not change while the String is being built.

Parameters:

charset - character set to decode String

Throws:

IllegalArgumentException - if resulting String length would be greater than Integer.MAX_VALUE

OutOfMemoryError - if not enough memory to hold Blob as a single String

FetchException

openOutputStream

OutputStream openOutputStream()
                              throws PersistException

Returns an OutputStream for writing Blob data, positioned at the start. The Blob implementation selects an appropriate buffer size for the stream.

Returns:

OutputStream for this Blob, which is not guaranteed to be thread-safe

Throws:

IllegalArgumentException - if position is negative

PersistException

openOutputStream

OutputStream openOutputStream(long pos)
                              throws PersistException

Returns an OutputStream for writing Blob data. The Blob implementation selects an appropriate buffer size for the stream.

Parameters:

pos - desired zero-based position to write to

Returns:

OutputStream for this Blob, which is not guaranteed to be thread-safe

Throws:

IllegalArgumentException - if position is negative

PersistException

openOutputStream

OutputStream openOutputStream(long pos,
                              int bufferSize)
                              throws PersistException

Returns an OutputStream for writing Blob data. A suggested buffer size must be provided, but it might be ignored by the Blob implementation.

Parameters:

pos - desired zero-based position to write to

bufferSize - suggest that the output stream buffer be at least this large (in bytes)

Returns:

OutputStream for this Blob, which is not guaranteed to be thread-safe

Throws:

IllegalArgumentException - if position is negative

PersistException

setLength

void setLength(long length)
               throws PersistException

Set the length of this Blob, in bytes. If the new length is shorter, the Blob is truncated. If the new length is longer, the Blob is padded with zeros.

Parameters:

length - new length to set to

Throws:

IllegalArgumentException - if length is negative

PersistDeniedException - if Blob is read-only

PersistException

setValue

void setValue(String value)
              throws PersistException

Convenience method to overwrite all Blob data with the value of a single String, applying UTF-8 encoding. The Blob length may grow or shrink, to match the encoded String value. Call within a transaction scope to ensure the data and length does not change while the value is set.

Parameters:

value - Blob is overwritten with this value

Throws:

IllegalArgumentException - if value is null

PersistException

setValue

void setValue(String value,
              String charsetName)
              throws PersistException

Convenience method to overwrite all Blob data with the value of a single String, applying the given charset encoding. The Blob length may grow or shrink, to match the encoded String value. Call within a transaction scope to ensure the data and length does not change while the value is set.

Parameters:

value - Blob is overwritten with this value

charsetName - name of character set to encode String

Throws:

IllegalCharsetNameException - if the given charset name is illegal

IllegalArgumentException - if value is null

PersistException

setValue

void setValue(String value,
              Charset charset)
              throws PersistException

Convenience method to overwrite all Blob data with the value of a single String, applying the given charset encoding. The Blob length may grow or shrink, to match the encoded String value. Call within a transaction scope to ensure the data and length does not change while the value is set.

Parameters:

value - Blob is overwritten with this value

charset - character set to encode String

Throws:

IllegalArgumentException - if value is null

PersistException