org.apache.derby.impl.jdbc
Class TemporaryClob

java.lang.Object
  org.apache.derby.impl.jdbc.TemporaryClob

All Implemented Interfaces:

InternalClob

final class TemporaryClob
extends java.lang.Object
implements InternalClob

A Clob representation where the Clob is stored either in memory or on disk.

Character positions given as input to methods in this class are always 1-based. Byte positions are always 0-based.

Nested Class Summary

private static class

TemporaryClob.CharToBytePositionCache A simple class to hold the byte position for a character position.

Field Summary

private LOBStreamControl	bytes Underlying structure holding this Clobs raw bytes.
private long	cachedCharLength Cached character length of the Clob.
private ConnectionChild	conChild Connection child assoicated with this Clob.
private UTF8Reader	internalReader Shared internal reader, closed when the Clob is released.
private TemporaryClob.CharToBytePositionCache	posCache Simple one-entry cache for character-byte position.
private boolean	released Tells whether this Clob has been released or not.
private java.io.FilterReader	unclosableInternalReader The internal reader wrapped so that it cannot be closed.

Constructor Summary

TemporaryClob(ConnectionChild conChild)
Constructs a TemporaryClob object used to perform operations on a CLOB value.

TemporaryClob(java.lang.String data, ConnectionChild conChild)
Constructs a TemporaryClob object and initializes with a initial String.

Method Summary

private void	checkIfValid() Makes sure the Clob has not been released.
(package private) static InternalClob	cloneClobContent(java.lang.String dbName, ConnectionChild conChild, InternalClob clob) Clones the content of another internal Clob.
(package private) static InternalClob	cloneClobContent(java.lang.String dbName, ConnectionChild conChild, InternalClob clob, long length) Clones the content of another internal Clob.
private void	copyClobContent(InternalClob clob) Copies the content of another Clob into this one.
private void	copyClobContent(InternalClob clob, long charLength) Copies the content of another Clob into this one.
private byte[]	getByteFromString(java.lang.String str) Converts a string into the modified UTF-8 byte encoding.
long	getByteLength() Returns the size of the Clob in bytes.
private long	getBytePosition(long charPos) Finds the corresponding byte position for the given UTF-8 character position, starting from the byte position startPos.
long	getCharLength() Returns number of characters in the Clob.
long	getCharLengthIfKnown() Returns the cached character count for the Clob, if any.
private CharacterStreamDescriptor	getCSD() Returns a character stream descriptor for the stream.
java.io.Reader	getInternalReader(long characterPosition) Returns an internal reader for the Clob content, initialized at the specified character position.
java.io.InputStream	getRawByteStream() Returns a stream serving the raw bytes of this Clob.
java.io.Reader	getReader(long pos) Constructs and returns a Reader.
long	getUpdateCount() Returns the update count of this Clob.
java.io.Writer	getWriter(long pos) Constructs and returns a Writer for the CLOB value.
long	insertString(java.lang.String str, long insertionPoint) Inserts a string at the given position.
boolean	isReleased() Tells if this Clob has been released.
boolean	isWritable() Tells if this Clob is intended to be writable.
void	release() Releases this Clob by freeing assoicated resources.
void	truncate(long newCharLength) Truncate the Clob to the specifiec size.
private void	updateInternalState(long charChangePosition) Updates the internal state after a modification has been performed on the Clob content.

Methods inherited from class java.lang.Object

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

Field Detail

conChild

private ConnectionChild conChild

Connection child assoicated with this Clob.

Currently only used for synchronization in *some* streams associated with the Clob. This suggests something is off wrt. synchronization.

bytes

private final LOBStreamControl bytes

Underlying structure holding this Clobs raw bytes.

released

private boolean released

Tells whether this Clob has been released or not.

cachedCharLength

private long cachedCharLength

Cached character length of the Clob.

A value of 0 is interpreted as unknown length, even though it is a valid value. If the length is requested and the value is zero, an attempt to obtain the length is made by draining the source.

internalReader

private UTF8Reader internalReader

Shared internal reader, closed when the Clob is released. This is a performance optimization, and the stream is shared between "one time" operations, for instance getSubString calls. Often a subset, or the whole, of the Clob is read subsequently and then this optimization avoids repositioning costs (the store does not support random access for LOBs). NOTE: Do not publish this reader to the end-user.

unclosableInternalReader

private java.io.FilterReader unclosableInternalReader

The internal reader wrapped so that it cannot be closed.

posCache

private final TemporaryClob.CharToBytePositionCache posCache

Simple one-entry cache for character-byte position.

Constructor Detail

TemporaryClob

TemporaryClob(ConnectionChild conChild)

Constructs a TemporaryClob object used to perform operations on a CLOB value.

Parameters:

conChild - connection object used to obtain synchronization object

Throws:

java.lang.NullPointerException - if conChild is null

TemporaryClob

TemporaryClob(java.lang.String data,
              ConnectionChild conChild)
        throws java.io.IOException,
               StandardException

Constructs a TemporaryClob object and initializes with a initial String.

Parameters:

data - initial value in String

conChild - connection object used to obtain synchronization object

Throws:

java.io.IOException

StandardException

Method Detail

cloneClobContent

static InternalClob cloneClobContent(java.lang.String dbName,
                                     ConnectionChild conChild,
                                     InternalClob clob)
                              throws java.io.IOException,
                                     java.sql.SQLException

Clones the content of another internal Clob.

Parameters:

dbName - name of the assoicated database

conChild - assoiated connection child

clob - the Clob whose content to clone

Returns:

A read-write Clob.

Throws:

java.io.IOException - if accessing the I/O resources fail (read or write)

java.sql.SQLException - if accessing underlying resources fail

cloneClobContent

static InternalClob cloneClobContent(java.lang.String dbName,
                                     ConnectionChild conChild,
                                     InternalClob clob,
                                     long length)
                              throws java.io.IOException,
                                     java.sql.SQLException

Clones the content of another internal Clob.

Parameters:

dbName - name of the assoicated database

conChild - assoiated connection child

clob - the Clob whose content to clone

length - number of chars in new InternalClob

Returns:

A read-write Clob.

Throws:

java.io.IOException - if accessing the I/O resources fail (read or write)

java.sql.SQLException - if accessing underlying resources fail

release

public void release()
             throws java.io.IOException

Releases this Clob by freeing assoicated resources.

Specified by:

release in interface InternalClob

Throws:

java.io.IOException - if accessing underlying I/O resources fail

getRawByteStream

public java.io.InputStream getRawByteStream()
                                     throws java.io.IOException

Returns a stream serving the raw bytes of this Clob.

The stream is managed by the underlying byte store, and can serve bytes both from memory and from a file on disk.

Specified by:

getRawByteStream in interface InternalClob

Returns:

A stream serving the raw bytes of the stream, initialized at byte position 0.

Throws:

java.io.IOException - if obtaining the stream fails

getBytePosition

private long getBytePosition(long charPos)
                      throws java.io.IOException

Finds the corresponding byte position for the given UTF-8 character position, starting from the byte position startPos. See comments in SQLChar.readExternal for more notes on processing the UTF8 format.

Parameters:

charPos - character position

Returns:

Stream position in bytes for the given character position.

Throws:

java.io.EOFException - if the character position specified is greater than the Clob length +1

java.io.IOException - if accessing underlying I/O resources fail

getUpdateCount

public long getUpdateCount()

Returns the update count of this Clob.

Specified by:

getUpdateCount in interface InternalClob

Returns:

Update count.

getWriter

public java.io.Writer getWriter(long pos)
                         throws java.io.IOException,
                                java.sql.SQLException

Constructs and returns a Writer for the CLOB value.

Specified by:

getWriter in interface InternalClob

Parameters:

pos - the initial position in bytes for the Writer

Returns:

A Writer to write to the CLOB value.

Throws:

java.io.IOException

java.sql.SQLException - if the specified position is invalid

getReader

public java.io.Reader getReader(long pos)
                         throws java.io.IOException,
                                java.sql.SQLException

Constructs and returns a Reader.

Specified by:

getReader in interface InternalClob

Parameters:

pos - initial position of the returned Reader in number of characters. Expected to be non-negative. The first character is at position 0.

Returns:

A Reader with the underlying CLOB value as source.

Throws:

java.io.IOException

java.sql.SQLException - if the specified position is too big

getInternalReader

public java.io.Reader getInternalReader(long characterPosition)
                                 throws java.io.IOException,
                                        java.sql.SQLException

Description copied from interface: InternalClob

Returns an internal reader for the Clob content, initialized at the specified character position.

This method can return a shared reader object, avoiding instantiation and repositioning costs for internal operations where the stream itself is not published to the end-user. One such example is Clob.getSubString.

Specified by:

getInternalReader in interface InternalClob

Parameters:

characterPosition - character position. The first character is at position 1.

Returns:

A Reader serving the content of the Clob.

Throws:

java.io.IOException - if accessing underlying I/O resources fail

java.sql.SQLException - if accessing underlying resources fail

See Also:

getReader(long)

getCharLength

public long getCharLength()
                   throws java.io.IOException

Returns number of characters in the Clob.

Specified by:

getCharLength in interface InternalClob

Returns:

The length of the Clob in number of characters.

Throws:

java.io.IOException - if accessing the underlying I/O resources fail

getCharLengthIfKnown

public long getCharLengthIfKnown()

Returns the cached character count for the Clob, if any.

Specified by:

getCharLengthIfKnown in interface InternalClob

Returns:

The number of characters in the Clob, or -1 if unknown.

getByteLength

public long getByteLength()
                   throws java.io.IOException

Returns the size of the Clob in bytes.

Returns:

Number of bytes in the CLOB value.

Throws:

java.io.IOException - if accessing the underlying I/O resources fail

insertString

public long insertString(java.lang.String str,
                         long insertionPoint)
                  throws java.io.IOException,
                         java.sql.SQLException

Inserts a string at the given position.

Specified by:

insertString in interface InternalClob

Parameters:

str - the string to insert

insertionPoint - the character position to insert the string at

Returns:

Number of characters inserted.

Throws:

java.io.EOFException - if the position is larger than the Clob length +1

java.io.IOException - if accessing the underlying I/O resources fail

java.sql.SQLException - if accessing the underlying resources fail

isReleased

public boolean isReleased()

Tells if this Clob has been released.

Specified by:

isReleased in interface InternalClob

Returns:

true if released, false if not.

isWritable

public boolean isWritable()

Tells if this Clob is intended to be writable.

Specified by:

isWritable in interface InternalClob

Returns:

true

truncate

public void truncate(long newCharLength)
              throws java.io.IOException,
                     java.sql.SQLException

Truncate the Clob to the specifiec size.

Specified by:

truncate in interface InternalClob

Parameters:

newCharLength - the new length, in characters, of the Clob

Throws:

java.io.IOException - if accessing the underlying I/O resources fails

java.sql.SQLException - if accessing underlying resources fail

getByteFromString

private byte[] getByteFromString(java.lang.String str)

Converts a string into the modified UTF-8 byte encoding.

Parameters:

str - string to represent with modified UTF-8 encoding

Returns:

Byte array representing the string in modified UTF-8 encoding.

copyClobContent

private void copyClobContent(InternalClob clob)
                      throws java.io.IOException,
                             java.sql.SQLException

Copies the content of another Clob into this one.

Parameters:

clob - the Clob to copy from

Throws:

java.io.IOException - if accessing I/O resources fail (both read and write)

java.sql.SQLException - if accessing underlying resources fail

copyClobContent

private void copyClobContent(InternalClob clob,
                             long charLength)
                      throws java.io.IOException,
                             java.sql.SQLException

Copies the content of another Clob into this one.

Parameters:

clob - the Clob to copy from

charLength - number of chars to copy

Throws:

java.io.EOFException - if the length of the stream is shorter than the specified length

java.io.IOException - if accessing I/O resources fail (both read and write)

java.sql.SQLException - if accessing underlying resources fail

checkIfValid

private final void checkIfValid()

Makes sure the Clob has not been released.

All operations are invalid on a released Clob.

Throws:

java.lang.IllegalStateException - if the Clob has been released

updateInternalState

private final void updateInternalState(long charChangePosition)

Updates the internal state after a modification has been performed on the Clob content.

Currently the state update consists of dicarding the internal reader to stop it from delivering stale data, to reset the byte/char position cache if necessary, and to reset the cached length.

Parameters:

charChangePosition - the position where the Clob change started

getCSD

private final CharacterStreamDescriptor getCSD()
                                        throws java.io.IOException

Returns a character stream descriptor for the stream.

All streams from the underlying source (LOBStreamControl) are position aware and can be moved to a specific byte position cheaply. The maximum length is not really needed, nor known, at the moment, so the maximum allowed Clob length in Derby is used.

Returns:

A character stream descriptor.

Throws:

java.io.IOException - if obtaining the length of the stream fails