com.amazon.carbonado.lob
Interface Clob

All Superinterfaces:

Lob

All Known Implementing Classes:

AbstractClob, BlobClob, CharArrayClob, StringClob

public interface Clob
extends Lob

Provides access to CLOBs, which are Character Large OBjects. Consider accessing Clobs within a transaction scope, to prevent unexpected updates.

Author:

Brian S O'Neill

See Also:

Blob

Method Summary

String	asString() Convenience method to capture all the Clob data as a single String.
long	getLength() Returns the length of this Clob, in characters.
Reader	openReader() Returns a Reader for reading Clob data, positioned at the start.
Reader	openReader(long pos) Returns a Reader for reading Clob data.
Reader	openReader(long pos, int bufferSize) Returns a Reader for reading Clob data.
Writer	openWriter() Returns a Writer for writing Clob data, positioned at the start.
Writer	openWriter(long pos) Returns a Writer for writing Clob data.
Writer	openWriter(long pos, int bufferSize) Returns a Writer for writing Clob data.
void	setLength(long length) Set the length of this Clob, in characters.
void	setValue(String value) Convenience method to overwrite all Clob data with the value of a single String.

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

equals, getLocator

Method Detail

openReader

Reader openReader()
                  throws FetchException

Returns a Reader for reading Clob data, positioned at the start. The Clob implementation selects an appropriate buffer size for the reader.

Returns:

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

Throws:

IllegalArgumentException - if position is negative

FetchException

openReader

Reader openReader(long pos)
                  throws FetchException

Returns a Reader for reading Clob data. The Clob implementation selects an appropriate buffer size for the reader.

Parameters:

pos - desired zero-based position to read from

Returns:

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

Throws:

IllegalArgumentException - if position is negative

FetchException

openReader

Reader openReader(long pos,
                  int bufferSize)
                  throws FetchException

Returns a Reader for reading Clob data. A suggested buffer size must be provided, but it might be ignored by the Clob implementation.

Parameters:

pos - desired zero-based position to read from

bufferSize - suggest that the reader buffer be at least this large (in characters)

Returns:

Reader 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 Clob, in characters.

Throws:

FetchException

asString

String asString()
                throws FetchException

Convenience method to capture all the Clob data as a single String. Call within a transaction scope to ensure the data does not change while the String is being built.

Throws:

IllegalArgumentException - if Clob length is greater than Integer.MAX_VALUE

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

FetchException

openWriter

Writer openWriter()
                  throws PersistException

Returns a Writer for writing Clob data, positioned at the start. The Clob implementation selects an appropriate buffer size for the writer.

Returns:

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

Throws:

IllegalArgumentException - if position is negative

PersistException

openWriter

Writer openWriter(long pos)
                  throws PersistException

Returns a Writer for writing Clob data. The Clob implementation selects an appropriate buffer size for the writer.

Parameters:

pos - desired zero-based position to write to

Returns:

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

Throws:

IllegalArgumentException - if position is negative

PersistException

openWriter

Writer openWriter(long pos,
                  int bufferSize)
                  throws PersistException

Returns a Writer for writing Clob data. A suggested buffer size must be provided, but it might be ignored by the Clob implementation.

Parameters:

pos - desired zero-based position to write to

bufferSize - suggest that the writer buffer be at least this large (in characters)

Returns:

Writer 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 Clob, in characters. If the new length is shorter, the Clob is truncated. If the new length is longer, the Clob is padded with '\0' characters.

Parameters:

length - new length to set to

Throws:

IllegalArgumentException - if length is negative

PersistDeniedException - if Clob is read-only

PersistException

setValue

void setValue(String value)
              throws PersistException

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

Parameters:

value - Clob is overwritten with this value

Throws:

IllegalArgumentException - if value is null

PersistException