org.apache.derby.impl.jdbc
Class StoreStreamClob

java.lang.Object
  extended by org.apache.derby.impl.jdbc.StoreStreamClob
All Implemented Interfaces:
InternalClob

final class StoreStreamClob
extends java.lang.Object
implements InternalClob

A read-only Clob representation operating on streams out of the Derby store module.

Note that the streams from the store are expected to have the following properties:

  1. The first few bytes are used for length encoding. Currently the number of bytes is either 2 or 5.
  2. A Derby-specific end-of-stream marker at the end of the stream can be present. The marker is expected to be 0xe0 0x00 0x00


Field Summary
private  ConnectionChild conChild
          The connection (child) this Clob belongs to.
private  CharacterStreamDescriptor csd
          The descriptor used to describe the underlying source stream.
private  UTF8Reader internalReader
          Shared internal reader, closed when the Clob is released.
private  PositionedStoreStream positionedStoreStream
          The stream from store, used to read bytes from the database.
private  boolean released
          Tells whether this Clob has been released or not.
private  java.lang.Object synchronizationObject
          Object used for synchronizing access to the store stream.
private  java.io.FilterReader unclosableInternalReader
          The internal reader wrapped so that it cannot be closed.
 
Constructor Summary
StoreStreamClob(CharacterStreamDescriptor csd, ConnectionChild conChild)
          Creates a new Clob based on a stream from store.
 
Method Summary
private  void checkIfValid()
          Makes sure the Clob has not been released.
 long getCharLength()
          Returns the number of characters in the Clob.
 long getCharLengthIfKnown()
          Returns the cached character count for the Clob, if any.
 java.io.Reader getInternalReader(long characterPosition)
          Returns an internal reader for the Clob, 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)
          Returns a reader for the Clob, initialized at the specified character position.
 long getUpdateCount()
          Returns the update count of this Clob.
 java.io.Writer getWriter(long pos)
          Not supported.
 long insertString(java.lang.String str, long pos)
          Not supported.
 boolean isReleased()
          Tells if this Clob has been released.
 boolean isWritable()
          Tells if this Clob can be modified.
private static java.sql.SQLException noStateChangeLOB(java.lang.Throwable t)
          Wrap real exception in a SQLException to avoid changing the state of the connection child by cleaning it up.
 void release()
          Releases resources associated with this Clob.
 void truncate(long newLength)
          Not supported.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

released

private volatile boolean released
Tells whether this Clob has been released or not.


positionedStoreStream

private final PositionedStoreStream positionedStoreStream
The stream from store, used to read bytes from the database.

To be able to support the requirements, the stream must implement Resetable.


csd

private CharacterStreamDescriptor csd
The descriptor used to describe the underlying source stream.


conChild

private final ConnectionChild conChild
The connection (child) this Clob belongs to.


synchronizationObject

private final java.lang.Object synchronizationObject
Object used for synchronizing access to the store stream.


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.

Constructor Detail

StoreStreamClob

public StoreStreamClob(CharacterStreamDescriptor csd,
                       ConnectionChild conChild)
                throws StandardException
Creates a new Clob based on a stream from store.

The stream used as a source for this Clob has to implement the interface Resetable, as the stream interface from store only allows for movement forwards. If the stream has been advanced too far with regards to the user request, the stream must be reset and we start from the beginning.

Parameters:
csd - descriptor for the source stream, including a reference to it
conChild - the connection (child) this Clob belongs to
Throws:
StandardException
Method Detail

release

public void release()
Releases resources associated with this Clob.

Specified by:
release in interface InternalClob

getCharLength

public long getCharLength()
                   throws java.sql.SQLException
Returns the number of characters in the Clob.

Specified by:
getCharLength in interface InternalClob
Returns:
Number of characters in the Clob.
Throws:
java.sql.SQLException - if any kind of error is encountered, be it related to I/O or something else

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.

getRawByteStream

public java.io.InputStream getRawByteStream()
                                     throws java.io.IOException,
                                            java.sql.SQLException
Returns a stream serving the raw bytes of this Clob.

Note that the stream returned is an internal stream, and it should not be pulished to end users.

Specified by:
getRawByteStream in interface InternalClob
Returns:
A stream serving the bytes of this Clob, initialized at byte 0 of the data. The buffer must be assumed to be unbuffered, but no such guarantee is made.
Throws:
java.io.IOException - if accessing the I/O resources fail
java.sql.SQLException - if accessing the store resources fail

getReader

public java.io.Reader getReader(long pos)
                         throws java.io.IOException,
                                java.sql.SQLException
Returns a reader for the Clob, initialized at the specified character position.

Specified by:
getReader in interface InternalClob
Parameters:
pos - character position. The first character is at position 1.
Returns:
A reader initialized at the specified position.
Throws:
java.io.EOFException - if the positions is larger than the Clob
java.io.IOException - if accessing the I/O resources fail
java.sql.SQLException - if accessing the store resources fail

getInternalReader

public java.io.Reader getInternalReader(long characterPosition)
                                 throws java.io.IOException,
                                        java.sql.SQLException
Returns an internal reader for the Clob, initialized at the specified character position.

Specified by:
getInternalReader in interface InternalClob
Parameters:
characterPosition - 1-based character position.
Returns:
A reader initialized at the specified position.
Throws:
java.io.EOFException - if the positions is larger than the Clob
java.io.IOException - if accessing the I/O resources fail
java.sql.SQLException - if accessing the store resources fail

getUpdateCount

public long getUpdateCount()
Returns the update count of this Clob.

Always returns zero, as this Clob cannot be updated.

Specified by:
getUpdateCount in interface InternalClob
Returns:
Zero (read-only Clob).

getWriter

public java.io.Writer getWriter(long pos)
Not supported.

Specified by:
getWriter in interface InternalClob
Parameters:
pos - the starting character position. The first character is at position 1.
Returns:
A writer initialized at the specified character position.
See Also:
InternalClob.getWriter(long)

insertString

public long insertString(java.lang.String str,
                         long pos)
Not supported.

Specified by:
insertString in interface InternalClob
Parameters:
str - the string to insert
pos - the character position the string will be inserted at. Must be between 1 and clob.length() +1, inclusive.
Returns:
The number of characters inserted.
See Also:
InternalClob.insertString(java.lang.String, long)

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 can be modified.

Specified by:
isWritable in interface InternalClob
Returns:
false, this Clob is read-only.

truncate

public void truncate(long newLength)
Not supported.

Specified by:
truncate in interface InternalClob
Parameters:
newLength - the length in characters to truncate to
See Also:
InternalClob.truncate(long)

noStateChangeLOB

private static java.sql.SQLException noStateChangeLOB(java.lang.Throwable t)
Wrap real exception in a SQLException to avoid changing the state of the connection child by cleaning it up.

Parameters:
t - real cause of error that we want to "ignore" with respect to transaction context cleanup
Returns:
A SQLException wrapped around the real cause of the error

checkIfValid

private 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

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.