ScanController

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> org >> apache >> derby >> iapi >> store >> [ access overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

Sourc code of org.apache.derby.iapi.store.access.ScanController

SOURCE |

Download org.apache.derby.iapi.store.access.ScanController

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.derby.iapi.store.access
Interface ScanController

All Superinterfaces:: GenericScanController, RowCountable

public interface ScanController
extends GenericScanController

A scan is the mechanism for iterating over the rows in a conglomerate, the scan controller is the interface through which access clients control the underlying scan. An instance of a scan controller can be thought of as an open scan.

Scans are opened from a TransactionController.

A ScanController can handle partial rows. Partial rows are described in RowUtil.
A scan controller is opened with a FormatableBitSet that describes the columns that need to be returned on a fetch call. This FormatableBitSet need not include any columns referenced in the qualifers, start and/or stop keys.

Field Summary

static int GE
          GE is used to position a scan at values greater than or or equal to the given key in the scan.

static int GT
          GT is used to position a scan at values greater than the given key.

static int NA
          NA - argument is unused in call.

Method Summary

boolean delete()
          Delete the row at the current position of the scan.

void didNotQualify()
          A call to allow client to indicate that current row does not qualify.

boolean doesCurrentPositionQualify()
          Returns true if the current position of the scan still qualifies under the set of qualifiers passed to the openScan().

void fetch(org.apache.derby.iapi.types.DataValueDescriptor[] destRow)
          Fetch the (partial) row at the current position of the Scan.

void fetchLocation(org.apache.derby.iapi.types.RowLocation destRowLocation)
          Fetch the location of the current position in the scan.

boolean fetchNext(org.apache.derby.iapi.types.DataValueDescriptor[] destRow)
          Fetch the (partial) row at the next position of the Scan.

boolean isCurrentPositionDeleted()
          Returns true if the current position of the scan is at a deleted row.

boolean next()
          Move to the next position in the scan.

boolean replace(org.apache.derby.iapi.types.DataValueDescriptor[] row, org.apache.derby.iapi.services.io.FormatableBitSet validColumns)
          Replace the (partial) row at the current position of the scan.

Methods inherited from interface org.apache.derby.iapi.store.access.GenericScanController

close, getScanInfo, isKeyed, isTableLocked, newRowLocationTemplate, reopenScan, reopenScanByRowLocation

Methods inherited from interface org.apache.derby.iapi.store.access.RowCountable

getEstimatedRowCount, setEstimatedRowCount

Field Detail

GE

public static final int GE

GE is used to position a scan at values greater than or or equal to the given key in the scan. This positioning argument refers to the order within the scan (not necessarily actual compare calls on the datatypes). "greater" than is interpreted in terms of the current conglomerate and scan. For instance, a btree may be ordered ascending on an int, in that case a 2 is "greater" than 1 in a forward scan on that index, and 1 is "greater" than 2 in a backward scan. If the btree was ordered descending on an int then 1 is "greater" than 2 in a forward scan on that index, and 2 is "greater" than 1 in a backward scan.

See Also:: TransactionController.openScan(long, boolean, int, int, int, org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.Qualifier[][], org.apache.derby.iapi.types.DataValueDescriptor[], int) 55 , Constant Field Values

GT

public static final int GT

GT is used to position a scan at values greater than the given key. This positioning argument refers to the order within the scan (not necessarily actual compare calls on the datatypes). "greater" than is interpreted in terms of the current conglomerate and scan. For instance, a btree may be ordered ascending on an int, in that case a 2 is "greater" than 1 in a forward scan on that index, and 1 is "greater" than 2 in a backward scan. If the btree was ordered descending on an int then 1 is "greater" than 2 in a forward scan on that index, and 2 is "greater" than 1 in a backward scan.

See Also:: TransactionController.openScan(long, boolean, int, int, int, org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.Qualifier[][], org.apache.derby.iapi.types.DataValueDescriptor[], int) 55 , Constant Field Values

NA

public static final int NA

NA - argument is unused in call. For some scans the key is set to null to indicate no start or stop position, in those cases the position operator is ignored.

See Also:: TransactionController.openScan(long, boolean, int, int, int, org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.Qualifier[][], org.apache.derby.iapi.types.DataValueDescriptor[], int) 55 , Constant Field Values

Method Detail

delete

public boolean delete()
               throws org.apache.derby.iapi.error.StandardException

Delete the row at the current position of the scan.

didNotQualify

public void didNotQualify()
                   throws org.apache.derby.iapi.error.StandardException

A call to allow client to indicate that current row does not qualify.

Indicates to the ScanController that the current row does not qualify for the scan. If the isolation level of the scan allows, this may result in the scan releasing the lock on this row.

Note that some scan implimentations may not support releasing locks on non-qualifying rows, or may delay releasing the lock until sometime later in the scan (ie. it may be necessary to keep the lock until either the scan is repositioned on the next row or page).

This call should only be made while the scan is positioned on a current valid row.

doesCurrentPositionQualify

public boolean doesCurrentPositionQualify()
                                   throws org.apache.derby.iapi.error.StandardException

Returns true if the current position of the scan still qualifies under the set of qualifiers passed to the openScan(). When called this routine will reapply all qualifiers against the row currently positioned and return true if the row still qualifies. If the row has been deleted or no longer passes the qualifiers then this routine will return false. This case can come about if the current scan or another scan on the same table in the same transaction deleted the row or changed columns referenced by the qualifier after the next() call which positioned the scan at this row. Note that for comglomerates which don't support update, like btree's, there is no need to recheck the qualifiers. The results of a fetch() performed on a scan positioned on a deleted row are undefined, note that this can happen even if next() has returned true (for instance the client can delete the row, or if using read uncommitted another thread can delete the row after the next() call but before the fetch).

fetch

public void fetch(org.apache.derby.iapi.types.DataValueDescriptor[] destRow)
           throws org.apache.derby.iapi.error.StandardException

Fetch the (partial) row at the current position of the Scan. The value in the destRow storable row is replaced with the value of the row at the current scan position. The columns of the destRow row must be of the same type as the actual columns in the underlying conglomerate. The number of elements in fetch must be compatible with the number of scan columns requested at the openScan call time.
A fetch can return a sub-set of the scan columns reqested at scan open time by supplying a destRow will less elements than the number of requested columns. In this case the N leftmost of the requested columns are fetched, where N = destRow.length. In the case where all columns are rested and N = 2 then columns 0 and 1 are returned. In the case where the openScan FormatableBitSet requested columns 1, 4 and 7, then columns 1 and 4 would be fetched when N = 2.
The results of a fetch() performed on a scan after next() has returned false are undefined. A fetch() performed on a scan positioned on a deleted row will throw a StandardException with state = SQLState.AM_RECORD_NOT_FOUND. Note that this can happen even if next() has returned true (for instance the client can delete the row, or if using read uncommitted another thread can delete the row after the next() call but before the fetch).

fetchNext

public boolean fetchNext(org.apache.derby.iapi.types.DataValueDescriptor[] destRow)
                  throws org.apache.derby.iapi.error.StandardException

Fetch the (partial) row at the next position of the Scan. If there is a valid next position in the scan then the value in the destRow storable row is replaced with the value of the row at the current scan position. The columns of the destRow row must be of the same type as the actual columns in the underlying conglomerate. The resulting contents of destRow after a fetchNext() which returns false is undefined. The result of calling fetchNext(row) is exactly logically equivalent to making a next() call followed by a fetch(row) call. This interface allows implementations to optimize the 2 calls if possible.

fetchLocation

public void fetchLocation(org.apache.derby.iapi.types.RowLocation destRowLocation)
                   throws org.apache.derby.iapi.error.StandardException

Fetch the location of the current position in the scan. The destination location is replaced with the location corresponding to the current position in the scan. The destination location must be of the correct actual type to accept a location from the underlying conglomerate location. The results of a fetchLocation() performed on a scan after next() has returned false are undefined. The results of a fetchLocation() performed on a scan positioned on a deleted row are undefined, note that this can happen even if next() has returned true (for instance the client can delete the row, or if using read uncommitted another thread can delete the row after the next() call but before the fetchLocation).

isCurrentPositionDeleted

public boolean isCurrentPositionDeleted()
                                 throws org.apache.derby.iapi.error.StandardException

Returns true if the current position of the scan is at a deleted row. This case can come about if the current scan or another scan on the same table in the same transaction deleted the row after the next() call which positioned the scan at this row. The results of a fetch() performed on a scan positioned on a deleted row are undefined.

public boolean next()
             throws org.apache.derby.iapi.error.StandardException

Move to the next position in the scan. If this is the first call to next(), the position is set to the first row. Returns false if there is not a next row to move to. It is possible, but not guaranteed, that this method could return true again, after returning false, if some other operation in the same transaction appended a row to the underlying conglomerate.

replace

public boolean replace(org.apache.derby.iapi.types.DataValueDescriptor[] row,
                       org.apache.derby.iapi.services.io.FormatableBitSet validColumns)
                throws org.apache.derby.iapi.error.StandardException

Replace the (partial) row at the current position of the scan.