org.apache.derby.impl.jdbc
Class TemporaryClob

java.lang.Object
  extended by 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,
               java.sql.SQLException,
               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
java.sql.SQLException
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

Built on Thu 2011-03-10 11:54:14+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.