org.apache.derby.impl.store.access.sort
Class Scan

java.lang.Object
  extended by org.apache.derby.impl.store.access.sort.Scan
All Implemented Interfaces:
ScanManager, GenericScanController, GroupFetchScanController, RowCountable, ScanController, ScanInfo
Direct Known Subclasses:
SortBufferRowSource, SortScan

public abstract class Scan
extends java.lang.Object
implements ScanManager, ScanInfo

Abstract base class for all sort classes which return rows from the sort. Subclasses must implement fetch, next, and close.


Field Summary
 
Fields inherited from interface org.apache.derby.iapi.store.access.ScanController
GE, GT, NA
 
Constructor Summary
Scan()
           
 
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 fetchLocation(RowLocation templateLocation)
          Fetch the location of the current position in the scan.
 int fetchNextGroup(DataValueDescriptor[][] row_array, RowLocation[] rowloc_array)
          Fetch the next N rows from the table.
 int fetchNextGroup(DataValueDescriptor[][] row_array, RowLocation[] old_rowloc_array, RowLocation[] new_rowloc_array)
           
 void fetchSet(long max_rowcnt, int[] key_column_numbers, BackingStoreHashtable hash_table)
          Insert all rows that qualify for the current scan into the input Hash table.
 java.util.Properties getAllScanInfo(java.util.Properties prop)
          Return all information gathered about the scan.
 long getEstimatedRowCount()
          Get the total estimated number of rows in the container.
 ScanInfo getScanInfo()
          Return ScanInfo object which describes performance of scan.
 boolean isCurrentPositionDeleted()
          Returns true if the current position of the scan is at a deleted row.
 boolean isHeldAfterCommit()
          Return true is the scan has been closed after a commit, but was opened with holdability and can be reopened using positionAtRowLocation.
 boolean isKeyed()
          Return whether this is a keyed conglomerate.
 boolean isTableLocked()
          Return whether this scan is table locked.
 RowLocation newRowLocationTemplate()
          Return a row location object of the correct type to be used in calls to fetchLocation.
 boolean positionAtRowLocation(RowLocation rl)
          Positions the scan at row location and locks the row.
 void reopenScan(DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier[][] qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator)
          Reposition the current scan.
 void reopenScanByRowLocation(RowLocation startRowLocation, Qualifier[][] qualifier)
          Reposition the current scan.
 boolean replace(DataValueDescriptor[] val, FormatableBitSet validColumns)
          Replace the entire row at the current position of the scan.
 void setEstimatedRowCount(long count)
          Set the total estimated number of rows in the container.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.derby.iapi.store.access.conglomerate.ScanManager
closeForEndTransaction
 
Methods inherited from interface org.apache.derby.iapi.store.access.ScanController
fetch, fetchNext, fetchWithoutQualify, next
 
Methods inherited from interface org.apache.derby.iapi.store.access.GroupFetchScanController
next
 
Methods inherited from interface org.apache.derby.iapi.store.access.GenericScanController
close
 

Constructor Detail

Scan

public Scan()
Method Detail

didNotQualify

public void didNotQualify()
                   throws 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.

This call does not make sense for sort scans.

Specified by:
didNotQualify in interface ScanController
Throws:
StandardException - Standard exception policy.

fetchNextGroup

public int fetchNextGroup(DataValueDescriptor[][] row_array,
                          RowLocation[] rowloc_array)
                   throws StandardException
Fetch the next N rows from the table.

Currently unimplemented for sorts.

Specified by:
fetchNextGroup in interface GroupFetchScanController
Parameters:
row_array - The array of rows to copy rows into. row_array[].length must >= 1. The first entry must be non-null destination rows, other entries may be null and will be allocated by access if needed.
rowloc_array - If non-null, the array of row locations to copy into. If null, no row locations are retrieved.
Returns:
The number of qualifying rows found and copied into the provided array of rows. If 0 then the scan is complete, otherwise the return value will be: 1 <= row_count <= row_array.length
Throws:
StandardException - Standard exception policy.

fetchNextGroup

public int fetchNextGroup(DataValueDescriptor[][] row_array,
                          RowLocation[] old_rowloc_array,
                          RowLocation[] new_rowloc_array)
                   throws StandardException
Specified by:
fetchNextGroup in interface GroupFetchScanController
Throws:
StandardException

fetchSet

public void fetchSet(long max_rowcnt,
                     int[] key_column_numbers,
                     BackingStoreHashtable hash_table)
              throws StandardException
Insert all rows that qualify for the current scan into the input Hash table.

Currently unimplemented for sorts.

Specified by:
fetchSet in interface ScanManager
Parameters:
max_rowcnt - The maximum number of rows to insert into the Hash table. Pass in -1 if there is no maximum.
key_column_numbers - The column numbers of the columns in the scan result row to be the key to the Hashtable. "0" is the first column in the scan result row (which may be different than the first row in the table of the scan).
Throws:
StandardException - Standard exception policy.

doesCurrentPositionQualify

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

Specified by:
doesCurrentPositionQualify in interface ScanController
Throws:
StandardException - Standard exception policy.
See Also:
ScanController.doesCurrentPositionQualify()

fetchLocation

public void fetchLocation(RowLocation templateLocation)
                   throws StandardException
Fetch the location of the current position in the scan.

Specified by:
fetchLocation in interface ScanController
Throws:
StandardException - Standard exception policy.
See Also:
ScanController.fetchLocation(org.apache.derby.iapi.types.RowLocation)

getScanInfo

public ScanInfo getScanInfo()
                     throws StandardException
Return ScanInfo object which describes performance of scan.

Return ScanInfo object which contains information about the current scan.

Currently the ScanInfo does not have any performance data.

Specified by:
getScanInfo in interface GenericScanController
Returns:
The ScanInfo object which contains info about current scan.
Throws:
StandardException - Standard exception policy.
See Also:
ScanInfo

getEstimatedRowCount

public long getEstimatedRowCount()
                          throws StandardException
Get the total estimated number of rows in the container.

The number is a rough estimate and may be grossly off. In general the server will cache the row count and then occasionally write the count unlogged to a backing store. If the system happens to shutdown before the store gets a chance to update the row count it may wander from reality.

This call is currently only supported on Heap conglomerates, it will throw an exception if called on btree conglomerates.

Specified by:
getEstimatedRowCount in interface RowCountable
Returns:
The total estimated number of rows in the conglomerate.
Throws:
StandardException - Standard exception policy.

setEstimatedRowCount

public void setEstimatedRowCount(long count)
                          throws StandardException
Set the total estimated number of rows in the container.

Often, after a scan, the client of RawStore has a much better estimate of the number of rows in the container than what store has. For instance if we implement some sort of update statistics command, or just after a create index a complete scan will have been done of the table. In this case this interface allows the client to set the estimated row count for the container, and store will use that number for all future references.

This call is currently only supported on Heap conglomerates, it will throw an exception if called on btree conglomerates.

Specified by:
setEstimatedRowCount in interface RowCountable
Parameters:
count - the estimated number of rows in the container.
Throws:
StandardException - Standard exception policy.

isCurrentPositionDeleted

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

Specified by:
isCurrentPositionDeleted in interface ScanController
Throws:
StandardException - Standard exception policy.
See Also:
ScanController.isCurrentPositionDeleted()

isKeyed

public boolean isKeyed()
Return whether this is a keyed conglomerate.

Specified by:
isKeyed in interface GenericScanController
Returns:
whether this is a keyed conglomerate.

isTableLocked

public boolean isTableLocked()
Return whether this scan is table locked.

Specified by:
isTableLocked in interface GenericScanController
Returns:
whether this is table locked.

delete

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

Specified by:
delete in interface ScanController
Returns:
true if the delete was successful, false if the current position is no longer valid (ie. if it was already deleted).
Throws:
StandardException - Standard exception policy.
See Also:
ScanController.delete()

reopenScan

public void reopenScan(DataValueDescriptor[] startKeyValue,
                       int startSearchOperator,
                       Qualifier[][] qualifier,
                       DataValueDescriptor[] stopKeyValue,
                       int stopSearchOperator)
                throws StandardException
Reposition the current scan.

Specified by:
reopenScan in interface GenericScanController
Parameters:
startKeyValue - An indexable row which holds a (partial) key value which, in combination with the startSearchOperator, defines the starting position of the scan. If null, the starting position of the scan is the first row of the conglomerate.
startSearchOperator - an operator which defines how the startKeyValue is to be searched for. If startSearchOperator is ScanController.GE, the scan starts on the first row which is greater than or equal to the startKeyValue. If startSearchOperation is ScanController.GT, the scan starts on the first row whose key is greater than startKeyValue. The startSearchOperation parameter is ignored if the startKeyValue parameter is null.
qualifier - An array of qualifiers which, applied to each key, restrict the rows returned by the scan. Rows for which any one of the qualifiers returns false are not returned by the scan. If null, all rows are returned.
stopKeyValue - An indexable row which holds a (partial) key value which, in combination with the stopSearchOperator, defines the ending position of the scan. If null, the ending position of the scan is the last row of the conglomerate.
stopSearchOperator - an operator which defines how the stopKeyValue is used to determine the scan stopping position. If stopSearchOperation is ScanController.GE, the scan stops just before the first row which is greater than or equal to the stopKeyValue. If stopSearchOperation is ScanController.GT, the scan stops just before the first row whose key is greater than startKeyValue. The stopSearchOperation parameter is ignored if the stopKeyValue parameter is null.
Throws:
StandardException - Standard exception policy.
See Also:
GenericScanController.reopenScan(org.apache.derby.iapi.types.DataValueDescriptor[], int, org.apache.derby.iapi.store.access.Qualifier[][], org.apache.derby.iapi.types.DataValueDescriptor[], int)

reopenScanByRowLocation

public void reopenScanByRowLocation(RowLocation startRowLocation,
                                    Qualifier[][] qualifier)
                             throws StandardException
Reposition the current scan. This call is semantically the same as if the current scan had been closed and a openScan() had been called instead. The scan is reopened against the same conglomerate, and the scan is reopened with the same "scan column list", "hold" and "forUpdate" parameters passed in the original openScan.

Specified by:
reopenScanByRowLocation in interface GenericScanController
Parameters:
startRowLocation - An existing RowLocation within the conglomerate, at which to position the start of the scan. The scan will begin at this location and continue forward until the end of the conglomerate. Positioning at a non-existent RowLocation (ie. an invalid one or one that had been deleted), will result in an exception being thrown when the first next operation is attempted.
qualifier - An array of qualifiers which, applied to each key, restrict the rows returned by the scan. Rows for which any one of the qualifiers returns false are not returned by the scan. If null, all rows are returned.
Throws:
StandardException - Standard exception policy.

replace

public boolean replace(DataValueDescriptor[] val,
                       FormatableBitSet validColumns)
                throws StandardException
Replace the entire row at the current position of the scan.

Specified by:
replace in interface ScanController
Returns:
true if the replace was successful, false if the current position is no longer valid (ie. if it was deleted).
Throws:
StandardException - Standard exception policy.
See Also:
ScanController.replace(org.apache.derby.iapi.types.DataValueDescriptor[], org.apache.derby.iapi.services.io.FormatableBitSet)

newRowLocationTemplate

public RowLocation newRowLocationTemplate()
                                   throws StandardException
Return a row location object of the correct type to be used in calls to fetchLocation.

Specified by:
newRowLocationTemplate in interface GenericScanController
Returns:
a row location object to be used in calls to fetchLocation.
Throws:
StandardException - Standard exception policy.
See Also:
GenericScanController.newRowLocationTemplate()

positionAtRowLocation

public boolean positionAtRowLocation(RowLocation rl)
                              throws StandardException
Description copied from interface: ScanController
Positions the scan at row location and locks the row. If the scan is not opened, it will be reopened if this is a holdable scan and there has not been any operations which causes RowLocations to be invalidated.

Specified by:
positionAtRowLocation in interface ScanController
Parameters:
rl - RowLocation for the new position for the scan. The RowLocation submitted should be a RowLocation which has previously been returned by this ScanController.
Returns:
true if the scan has been positioned at the RowLocation. false if the scan could not be positioned.
Throws:
StandardException - Standard exception policy.
See Also:
ScanController.positionAtRowLocation(org.apache.derby.iapi.types.RowLocation)

getAllScanInfo

public java.util.Properties getAllScanInfo(java.util.Properties prop)
                                    throws StandardException
Return all information gathered about the scan.

This routine returns a list of properties which contains all information gathered about the scan. If a Property is passed in, then that property list is appeneded to, otherwise a new property object is created and returned.

Currently sort scans doesn't track any information.

Specified by:
getAllScanInfo in interface ScanInfo
Parameters:
prop - Property list to fill in.
Throws:
StandardException - Standard exception policy.

isHeldAfterCommit

public boolean isHeldAfterCommit()
                          throws StandardException
Description copied from interface: ScanController
Return true is the scan has been closed after a commit, but was opened with holdability and can be reopened using positionAtRowLocation.

Specified by:
isHeldAfterCommit in interface ScanController
Throws:
StandardException - Standard exception policy.
See Also:
ScanController.isHeldAfterCommit()

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.