org.apache.derby.client.am
Class LOBStateTracker

java.lang.Object
  extended by org.apache.derby.client.am.LOBStateTracker

 class LOBStateTracker
extends java.lang.Object

An object that tracks the state of large objects (LOBs) for the current row in a result set.

A LOB's state is either unpublished or published. When a LOB is published, it means that the end-user has been given a reference to the LOB object. This implies that the LOB cannot be automatically freed/released when the result set position changes (i.e. typically rs.next()), because the LOB object must be kept valid/alive until the transaction is ended or the LOB object is explicitly freed.

This class covers two types of functionality regarding LOBs;

Both functionalities will be disabled if the server doesn't support locators. If locators are enabled, they will be freed when checkCurrentRow(org.apache.derby.client.am.Cursor) is called.

The tracker has a notion of current row. The current row is changed by calling checkCurrentRow. The owner of the tracker is repsonsible for invoking the method at the correct time, and only when the cursor is positioned on a valid data row. The method must be invoked before the cursor changes the position. Note that calling the method discardState makes checkCurrentRow ignore all LOBs on the subsequent call.


Field Summary
private  int[] columns
          1-based column indexes for the LOBs to track.
private  boolean doRelease
          Tells whether locators shall be released.
private  boolean[] isBlob
          Tells whether the LOB is Blob or a Clob.
private  int[] lastLocatorSeen
          The last locator values seen when releasing.
static LOBStateTracker NO_OP_TRACKER
          Instance to use when there are no LOBs in the result set, or when the server doesn't support locators.
private  boolean[] published
          Tells whether the LOB colum has been published for the current row.
 
Constructor Summary
LOBStateTracker(int[] lobIndexes, boolean[] isBlob, boolean doRelease)
          Creates a LOB state tracker for the specified configuration.
 
Method Summary
(package private)  void checkCurrentRow(Cursor cursor)
          Checks the current row, updating state and releasing locators on the server as required.
(package private)  void discardState()
          Discards all recorded dynamic state about LOBs.
(package private)  void markAsPublished(int index)
          Marks the specified column of the current row as published, which implies that the tracker should not release the associated locator.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_OP_TRACKER

public static final LOBStateTracker NO_OP_TRACKER
Instance to use when there are no LOBs in the result set, or when the server doesn't support locators.


columns

private final int[] columns
1-based column indexes for the LOBs to track.


isBlob

private final boolean[] isBlob
Tells whether the LOB is Blob or a Clob.


published

private final boolean[] published
Tells whether the LOB colum has been published for the current row.


doRelease

private final boolean doRelease
Tells whether locators shall be released. This will be false if locators are not supported by the server.


lastLocatorSeen

private final int[] lastLocatorSeen
The last locator values seen when releasing. These values are used to detect if checkCurrentRow(org.apache.derby.client.am.Cursor) is being executed more than once on the same row.

Constructor Detail

LOBStateTracker

LOBStateTracker(int[] lobIndexes,
                boolean[] isBlob,
                boolean doRelease)
Creates a LOB state tracker for the specified configuration.

Parameters:
lobIndexes - the 1-based indexes of the LOB columns
isBlob - whether the LOB is a Blob or a Clob
doRelease - whether locators shall be released
See Also:
NO_OP_TRACKER
Method Detail

checkCurrentRow

void checkCurrentRow(Cursor cursor)
               throws SqlException
Checks the current row, updating state and releasing locators on the server as required.

This method should only be called once per valid row in the result set.

Parameters:
cursor - the cursor object to use for releasing the locators
Throws:
SqlException - if releasing the locators on the server fails

discardState

void discardState()
Discards all recorded dynamic state about LOBs.

Typically called after connection commit or rollback, as those operations will release all locators on the server automatically. There is no need to release them from the client side in this case.


markAsPublished

void markAsPublished(int index)
Marks the specified column of the current row as published, which implies that the tracker should not release the associated locator.

Columns must be marked as published when a LOB object is created on the client, to avoid releasing the corresponding locator too early.

Parameters:
index - 1-based column index

Built on Thu 2012-03-29 21:53:33+0000, from revision ???

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