Lob (Apache Derby V10.14 Internals)

java.lang.Object
- org.apache.derby.client.am.Lob

All Implemented Interfaces:

UnitOfWorkListener

Direct Known Subclasses:

ClientBlob, ClientClob
```
public abstract class Lob
extends java.lang.Object
implements UnitOfWorkListener
```

Field Summary

Fields
Modifier and Type	Field	Description
`protected Agent`	`agent_`
`(package private) static int`	`ASCII_STREAM`
`(package private) static int`	`BINARY_STREAM`
`(package private) static int`	`BINARY_STRING`
`(package private) 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_`
`private static ClientMessageId`	`LOB_OBJECT_LENGTH_UNKNOWN_YET`
`(package private) static int`	`LOCATOR`
`protected int`	`locator_`
`private long`	`sqlLength_`
`(package private) static int`	`STRING`
`private int`	`transactionID_`	This integer identifies which transaction the Lob is associated with
`(package private) static int`	`UNICODE_STREAM`
`private long`	`updateCount`
`private boolean`	`willBeLayerBStreamed_`

Constructor Summary

Constructors
Modifier Constructor Description

protected Lob(Agent agent, boolean willBeLayerBStreamed)

Constructors
Modifier	Constructor	Description
`protected`	`Lob(Agent agent, boolean willBeLayerBStreamed)`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`(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.
`void`	`completeLocalCommit(java.util.Iterator listenerIterator)`
`void`	`completeLocalRollback(java.util.Iterator listenerIterator)`
`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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - STRING
```
static final int STRING
```
    See Also:
    
    Constant Field Values
  - ASCII_STREAM
```
static final int ASCII_STREAM
```
    See Also:
    
    Constant Field Values
  - UNICODE_STREAM
```
static final int UNICODE_STREAM
```
    See Also:
    
    Constant Field Values
  - CHARACTER_STREAM
```
static final int CHARACTER_STREAM
```
    See Also:
    
    Constant Field Values
  - BINARY_STREAM
```
static final int BINARY_STREAM
```
    See Also:
    
    Constant Field Values
  - BINARY_STRING
```
static final int BINARY_STRING
```
    See Also:
    
    Constant Field Values
  - LOCATOR
```
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
```
private static final ClientMessageId LOB_OBJECT_LENGTH_UNKNOWN_YET
```
- Constructor Detail
  - Lob
```
protected Lob(Agent agent,
              boolean willBeLayerBStreamed)
```
- Method Detail
  - 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
  - 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

Class Lob

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

STRING

ASCII_STREAM

UNICODE_STREAM

CHARACTER_STREAM

BINARY_STREAM

BINARY_STRING

LOCATOR

INVALID_LOCATOR

agent_

dataType_

locator_

sqlLength_

lengthObtained_

isValid_

willBeLayerBStreamed_

updateCount

transactionID_

LOB_OBJECT_LENGTH_UNKNOWN_YET

Constructor Detail

Lob

Method Detail

sqlLength

setSqlLength

getLocatorLength

listenToUnitOfWork

completeLocalCommit

completeLocalRollback

getAgent

checkForClosedConnection

materializeStream

materializeStream

length

isLayerBStreamingPossible

willBeLayerBStreamed

isLocator

getLocator

checkPosAndLength

incrementUpdateCount

getUpdateCount

checkForLocatorValidity

checkValidity