org.apache.derby.client.am
Class Lob

java.lang.Object
  extended by org.apache.derby.client.am.Lob
All Implemented Interfaces:
UnitOfWorkListener
Direct Known Subclasses:
Blob, Clob

public abstract class Lob
extends java.lang.Object
implements UnitOfWorkListener


Field Summary
protected  Agent agent_
           
static int ASCII_STREAM
           
static int BINARY_STREAM
           
static int BINARY_STRING
           
static int CHARACTER_STREAM
           
protected  int dataType_
           
static int INVALID_LOCATOR
           
protected  boolean isValid_
          This boolean variable indicates whether the Lob object has been invalidated by calling free() on it
private  boolean lengthObtained_
           
protected static ClientMessageId LOB_OBJECT_LENGTH_UNKNOWN_YET
           
static int LOCATOR
           
protected  int locator_
           
private  long sqlLength_
           
static int STRING
           
private  int transactionID_
          This integer identifies which transaction the Lob is associated with
static int UNICODE_STREAM
           
private  long updateCount
           
private  boolean willBeLayerBStreamed_
           
 
Constructor Summary
protected Lob(Agent agent, boolean willBeLayerBStreamed)
           
 
Method Summary
(package private)  void checkForClosedConnection()
           
(package private)  void checkForLocatorValidity()
          Calls SqlLength() to check if the Locator associated with the underlying Lob is valid.
protected  void checkPosAndLength(long pos, long length)
          Checks the pos and length.
protected  void checkValidity()
          Checks if isValid is true and whether the transaction that created the Lob is still active.
(package private)  void completeLocalCommit()
           
 void completeLocalCommit(java.util.Iterator listenerIterator)
           
(package private)  void completeLocalRollback()
           
 void completeLocalRollback(java.util.Iterator listenerIterator)
           
protected  void finalize()
           
 Agent getAgent()
           
 int getLocator()
          Get locator for this Lob
(package private)  long getLocatorLength()
          Get the length of locator based Lob from the server.
(package private)  long getUpdateCount()
          Returns the current updateCount of the Clob.
protected  void incrementUpdateCount()
          Increments and returns the new updateCount of this Lob.
protected static boolean isLayerBStreamingPossible(Agent agent)
           
 boolean isLocator()
          Check whether this Lob is based on a locator
abstract  long length()
           
 void listenToUnitOfWork()
           
protected abstract  void materializeStream()
          Method to be implemented by subclasses, so that #materializedStream(InputStream, String) can be called with subclass specific parameters and the result assigned to the right stream.
protected  java.io.InputStream materializeStream(java.io.InputStream is, java.lang.String typeDesc)
          Materialize the given stream into memory and update the internal length variable.
(package private)  void setSqlLength(long length)
          Update the registered length of the Lob value.
(package private)  long sqlLength()
          Return the length of the Lob value represented by this Lob object.
 boolean willBeLayerBStreamed()
           
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STRING

public static final int STRING
See Also:
Constant Field Values

ASCII_STREAM

public static final int ASCII_STREAM
See Also:
Constant Field Values

UNICODE_STREAM

public static final int UNICODE_STREAM
See Also:
Constant Field Values

CHARACTER_STREAM

public static final int CHARACTER_STREAM
See Also:
Constant Field Values

BINARY_STREAM

public static final int BINARY_STREAM
See Also:
Constant Field Values

BINARY_STRING

public static final int BINARY_STRING
See Also:
Constant Field Values

LOCATOR

public static final int LOCATOR
See Also:
Constant Field Values

INVALID_LOCATOR

public static final int INVALID_LOCATOR
See Also:
Constant Field Values

agent_

protected Agent agent_

dataType_

protected int dataType_

locator_

protected int locator_

sqlLength_

private long sqlLength_

lengthObtained_

private boolean lengthObtained_

isValid_

protected boolean isValid_
This boolean variable indicates whether the Lob object has been invalidated by calling free() on it


willBeLayerBStreamed_

private final boolean willBeLayerBStreamed_

updateCount

private long updateCount

transactionID_

private int transactionID_
This integer identifies which transaction the Lob is associated with


LOB_OBJECT_LENGTH_UNKNOWN_YET

protected static final ClientMessageId LOB_OBJECT_LENGTH_UNKNOWN_YET
Constructor Detail

Lob

protected Lob(Agent agent,
              boolean willBeLayerBStreamed)
Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

sqlLength

long sqlLength()
         throws SqlException
Return the length of the Lob value represented by this Lob object. If length is not already known, and Lob is locator based, length will be retrieved from the server. If not, locator based, Lob will first be materialized. NOTE: The caller needs to deal with synchronization.

Returns:
length of Lob value
Throws:
SqlException - on execution errors while materializing the stream, or if Layer B streaming is used and length not yet obtained.

setSqlLength

void setSqlLength(long length)
Update the registered length of the Lob value. To be called by methods that make changes to the length of the Lob. NOTE: The caller needs to deal with synchronization.

Parameters:
length - the new length of the Lob value

getLocatorLength

long getLocatorLength()
                throws SqlException
Get the length of locator based Lob from the server. This is a dummy implementation that is supposed to be overridden by subclasses. A stored procedure call will be made to get the length from the server.

Returns:
length of Lob
Throws:
SqlException

listenToUnitOfWork

public void listenToUnitOfWork()
Specified by:
listenToUnitOfWork in interface UnitOfWorkListener

completeLocalCommit

public void completeLocalCommit(java.util.Iterator listenerIterator)
Specified by:
completeLocalCommit in interface UnitOfWorkListener

completeLocalRollback

public void completeLocalRollback(java.util.Iterator listenerIterator)
Specified by:
completeLocalRollback in interface UnitOfWorkListener

getAgent

public Agent getAgent()

checkForClosedConnection

void checkForClosedConnection()
                        throws SqlException
Throws:
SqlException

completeLocalRollback

void completeLocalRollback()

completeLocalCommit

void completeLocalCommit()

materializeStream

protected abstract void materializeStream()
                                   throws SqlException
Method to be implemented by subclasses, so that #materializedStream(InputStream, String) can be called with subclass specific parameters and the result assigned to the right stream.

Throws:
SqlException

materializeStream

protected java.io.InputStream materializeStream(java.io.InputStream is,
                                                java.lang.String typeDesc)
                                         throws SqlException
Materialize the given stream into memory and update the internal length variable.

Parameters:
is - stream to use for input
typeDesc - description of the data type we are inserting, for instance java.sql.Clob
Returns:
a stream whose source is the materialized data
Throws:
SqlException - if the stream exceeds 2 GB, or an error happens while reading from the stream

length

public abstract long length()
                     throws java.sql.SQLException
Throws:
java.sql.SQLException

isLayerBStreamingPossible

protected static boolean isLayerBStreamingPossible(Agent agent)

willBeLayerBStreamed

public boolean willBeLayerBStreamed()

isLocator

public boolean isLocator()
Check whether this Lob is based on a locator

Returns:
true if Lob is based on locator, false otherwise

getLocator

public int getLocator()
Get locator for this Lob

Returns:
locator for this Lob, INVALID_LOCATOR if Lob is not based on locator

checkPosAndLength

protected void checkPosAndLength(long pos,
                                 long length)
                          throws java.sql.SQLException
Checks the pos and length.

Parameters:
pos - a long that contains the position that needs to be checked
length - a long that contains the length that needs to be checked
Throws:
java.sql.SQLException - if a) pos <= 0 b) pos > (length of LOB) c) length < 0 d) (pos -1) + length > (length of LOB)

incrementUpdateCount

protected void incrementUpdateCount()
Increments and returns the new updateCount of this Lob. The method needs to be synchronized since multiple updates can happen on this Lob simultaneously. It will be called from the 1) Locator Writers 2) Locator OutputStreams 3) From the update methods within the Lobs like setString, truncate. since all of the above acesses are inside the am package, this method will have default access. We do not need to worry about the non-locator streams since non-locator InputStreams would not depend on updateCount for invalidation


getUpdateCount

long getUpdateCount()
Returns the current updateCount of the Clob.


checkForLocatorValidity

void checkForLocatorValidity()
                       throws SqlException
Calls SqlLength() to check if the Locator associated with the underlying Lob is valid. If it is not it throws an exception.

Throws:
SqlException

checkValidity

protected void checkValidity()
                      throws java.sql.SQLException
Checks if isValid is true and whether the transaction that created the Lob is still active. If any of which is not true throws a SQLException stating that a method has been called on an invalid LOB object.

Throws:
java.sql.SQLException - if isValid is not true or the transaction that created the Lob is not active

Built on Thu 2010-12-23 20:49:13+0000, from revision ???

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