|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.derby.impl.store.access.conglomerate.GenericController
org.apache.derby.impl.store.access.conglomerate.GenericScanController
Generic class implementing shared ScanController methods. Logically a scancontroller is used to scan a set of rows that meet some specified qualification. Rows that meet the qualification may be operated upon by the scan to fetch, delete, or replace. The ScanController also supports the notion or "repositioning" the scan, which simply resets the beginning of the scan to a new place, and allows the user to continue from there. This class attempts to abstract out some of the parts of the scan such that maybe multiple access methods can share code, even if they perform parts of the scan wildly differently. Here is how the scan has been broken apart: scan_position - this variable holds the current scan position, it may be extended to provide more information if necessary. scan_state - a scan has 3 possible states: SCAN_INIT, SCAN_INPROGRESS, SCAN_DONE positionAtInitScan() - This routine is called to move the scan to the SCAN_INIT state. It is used both for initialization of the ScanController and by reopenScan(). positionAtStartForForwardScan() - This routine is called to move the scan from SCAN_INIT to SCAN_INPROGRESS. Upon return from this routine it is expected that scan_position is set such that calling the generic scan loop will reach the first row of the scan. Note that this usually means setting the scan_postion to one before the 1st row to be returned. fetchRows() - This routine is the meat of the scan, it moves the scan to the next row, applies necessary qualifiers, and handles group or non-group operations. It moves through rows on a page in order and then moves to the "next" page. positionAtNextPage() - This routine handles moving the scan from the current scan_position to the next page. positionAtDoneScan() - Handle all cleanup associated with moving the scan state from SCAN_INPROGRESS to SCAN_DONE. This may include releasing locks, and setting the state of the scan. This does not close the scan, it allows for a reopenScan() to be called.
Field Summary | |
private FetchDescriptor |
init_fetchDesc
|
private Qualifier[][] |
init_qualifier
|
private FormatableBitSet |
init_scanColumnList
The following group of fields are all basic input parameters which are provided by the calling code when doing a scan. |
private DataValueDescriptor[] |
init_startKeyValue
|
private int |
init_startSearchOperator
|
private DataValueDescriptor[] |
init_stopKeyValue
|
private int |
init_stopSearchOperator
|
static int |
SCAN_DONE
|
static int |
SCAN_HOLD_INIT
|
static int |
SCAN_HOLD_INPROGRESS
|
static int |
SCAN_INIT
Constants of the class |
static int |
SCAN_INPROGRESS
|
protected RowPosition |
scan_position
The position for the current scan. |
private int |
scan_state
Delay positioning the table at the start position until the first next() call. |
protected int |
stat_numpages_visited
Performance counters ... |
protected int |
stat_numrows_qualified
|
protected int |
stat_numrows_visited
|
Fields inherited from class org.apache.derby.impl.store.access.conglomerate.GenericController |
open_conglom |
Fields inherited from interface org.apache.derby.iapi.store.access.ScanController |
GE, GT, NA |
Constructor Summary | |
GenericScanController()
|
Method Summary | |
protected RowPosition |
allocateScanPosition()
Create object which represents the scan position. |
void |
close()
Close the scan. |
boolean |
closeForEndTransaction(boolean closeHeldScan)
Close scan as part of terminating a transaction. |
private void |
closeScan()
Public Methods implementing ScanController: |
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(DataValueDescriptor[] row)
Fetch the (partial) row at the current position of the Scan. |
void |
fetchLocation(RowLocation templateLocation)
Fetch the location of the current position in the scan. |
protected int |
fetchRows(DataValueDescriptor[][] row_array,
RowLocation[] rowloc_array,
BackingStoreHashtable hash_table,
long max_rowcnt,
int[] key_column_numbers)
Fetch the next N rows from the table. |
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. |
int |
getNumPagesVisited()
|
int |
getNumRowsQualified()
|
int |
getNumRowsVisited()
|
Qualifier[][] |
getQualifier()
|
FormatableBitSet |
getScanColumnList()
|
ScanInfo |
getScanInfo()
Return ScanInfo object which describes performance of scan. |
RowPosition |
getScanPosition()
|
int |
getScanState()
|
DataValueDescriptor[] |
getStartKeyValue()
|
int |
getStartSearchOperator()
|
DataValueDescriptor[] |
getStopKeyValue()
|
int |
getStopSearchOperator()
|
void |
init(OpenConglomerate open_conglom,
FormatableBitSet scanColumnList,
DataValueDescriptor[] startKeyValue,
int startSearchOperator,
Qualifier[][] qualifier,
DataValueDescriptor[] stopKeyValue,
int stopSearchOperator)
Public Methods of This class: |
boolean |
isCurrentPositionDeleted()
Returns true if the current position of the scan is at a deleted row. |
protected void |
positionAtDoneScan(RowPosition pos)
Do any necessary work to complete the scan. |
protected void |
positionAtInitScan(DataValueDescriptor[] startKeyValue,
int startSearchOperator,
Qualifier[][] qualifier,
DataValueDescriptor[] stopKeyValue,
int stopSearchOperator,
RowPosition pos)
Move scan to the the SCAN_INIT state. |
protected void |
positionAtNextPage(RowPosition pos)
Position scan to slot before first slot on next page. |
protected void |
positionAtResumeScan(RowPosition pos)
Reposition the scan upon entering the fetchRows loop. |
protected void |
positionAtStartForForwardScan(RowPosition pos)
Move the scan from SCAN_INIT to SCAN_INPROGRESS. |
void |
reopenScan(DataValueDescriptor[] startKeyValue,
int startSearchOperator,
Qualifier[][] qualifier,
DataValueDescriptor[] stopKeyValue,
int stopSearchOperator)
Reposition the current scan. |
protected void |
reopenScanByRecordHandle(RecordHandle startRecordHandle,
Qualifier[][] qualifier)
Reposition the current scan. |
void |
reopenScanByRowLocation(RowLocation startRowLocation,
Qualifier[][] qualifier)
Reposition the current scan. |
boolean |
replace(DataValueDescriptor[] row,
FormatableBitSet validColumns)
Replace the (partial) row at the current position of the scan. |
private void |
repositionScanForUpateOper()
Private methods of This class: |
protected void |
setRowLocationArray(RowLocation[] rowloc_array,
int index,
RowPosition pos)
|
void |
setScanPosition(RowPosition pos)
|
void |
setScanState(int state)
|
Methods inherited from class org.apache.derby.impl.store.access.conglomerate.GenericController |
checkConsistency, debugConglomerate, getEstimatedRowCount, getInternalTablePropertySet, getOpenConglom, getRowPositionFromRowLocation, getSpaceInfo, getTableProperties, init, isKeyed, isTableLocked, newRowLocationTemplate, queueDeletePostCommitWork, setEstimatedRowCount |
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 |
savePosition |
Methods inherited from interface org.apache.derby.iapi.store.access.ScanController |
fetchNext, next |
Methods inherited from interface org.apache.derby.iapi.store.access.GenericScanController |
isKeyed, isTableLocked, newRowLocationTemplate |
Methods inherited from interface org.apache.derby.iapi.store.access.RowCountable |
getEstimatedRowCount, setEstimatedRowCount |
Methods inherited from interface org.apache.derby.iapi.store.access.GroupFetchScanController |
fetchNextGroup, next |
Field Detail |
public static final int SCAN_INIT
public static final int SCAN_INPROGRESS
public static final int SCAN_DONE
public static final int SCAN_HOLD_INIT
public static final int SCAN_HOLD_INPROGRESS
private FormatableBitSet init_scanColumnList
private DataValueDescriptor[] init_startKeyValue
private int init_startSearchOperator
private Qualifier[][] init_qualifier
private DataValueDescriptor[] init_stopKeyValue
private int init_stopSearchOperator
private FetchDescriptor init_fetchDesc
private int scan_state
protected RowPosition scan_position
protected int stat_numpages_visited
protected int stat_numrows_visited
protected int stat_numrows_qualified
Constructor Detail |
public GenericScanController()
Method Detail |
private final void repositionScanForUpateOper() throws StandardException
StandardException
protected void positionAtInitScan(DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier[][] qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator, RowPosition pos) throws StandardException
This routine is called to move the scan to the SCAN_INIT state. It is used both for initialization of the ScanController and by reopenScan().
StandardException
protected void positionAtResumeScan(RowPosition pos) throws StandardException
Called upon entering fetchRows() while in the SCAN_INPROGRESS state. Do work necessary to look at rows in the current page of the scan.
The default implementation uses a record handle to maintain a scan position. It will get the latch again on the current scan position and set the slot to the current record handle.
StandardException
- Standard exception policy.protected void positionAtStartForForwardScan(RowPosition pos) throws StandardException
This routine is called to move the scan from SCAN_INIT to SCAN_INPROGRESS. Upon return from this routine it is expected that scan_position is set such that calling the generic scan loop will reach the first row of the scan. Note that this usually means setting the scan_postion to one before the 1st row to be returned.
StandardException
- Standard exception policy.protected void positionAtNextPage(RowPosition pos) throws StandardException
StandardException
- Standard exception policy.protected void positionAtDoneScan(RowPosition pos) throws StandardException
StandardException
- Standard exception policy.public void reopenScanByRowLocation(RowLocation startRowLocation, Qualifier[][] qualifier) throws StandardException
GenericScanController
The statistics gathered by the scan are not reset to 0 by a reopenScan(), rather they continue to accumulate.
Note that this operation is currently only supported on Heap conglomerates. Also note that order of rows within are heap are not guaranteed, so for instance positioning at a RowLocation in the "middle" of a heap, then inserting more data, then continuing the scan is not guaranteed to see the new rows - they may be put in the "beginning" of the heap.
reopenScanByRowLocation
in interface GenericScanController
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.
StandardException
- Standard exception policy.protected RowPosition allocateScanPosition() throws StandardException
Designed so that extending classes can override and allocate implementation specific row position's.
StandardException
- Standard exception policy.protected int fetchRows(DataValueDescriptor[][] row_array, RowLocation[] rowloc_array, BackingStoreHashtable hash_table, long max_rowcnt, int[] key_column_numbers) throws StandardException
Utility routine used by both fetchSet() and fetchNextGroup().
StandardException
- Standard exception policy.protected void reopenScanByRecordHandle(RecordHandle startRecordHandle, Qualifier[][] qualifier) throws StandardException
The statistics gathered by the scan are not reset to 0 by a reopenScan(), rather they continue to accumulate.
Note that this operation is currently only supported on Heap conglomerates. Also note that order of rows within are heap are not guaranteed, so for instance positioning at a RowLocation in the "middle" of a heap, then inserting more data, then continuing the scan is not guaranteed to see the new rows - they may be put in the "beginning" of the heap.
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.
StandardException
- Standard exception policy.protected void setRowLocationArray(RowLocation[] rowloc_array, int index, RowPosition pos) throws StandardException
StandardException
public void init(OpenConglomerate open_conglom, FormatableBitSet scanColumnList, DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier[][] qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator) throws StandardException
StandardException
public final int getNumPagesVisited()
public final int getNumRowsVisited()
public final int getNumRowsQualified()
public final FormatableBitSet getScanColumnList()
public final DataValueDescriptor[] getStartKeyValue()
public final int getStartSearchOperator()
public final DataValueDescriptor[] getStopKeyValue()
public final int getStopSearchOperator()
public final Qualifier[][] getQualifier()
public final int getScanState()
public final void setScanState(int state)
public final RowPosition getScanPosition()
public final void setScanPosition(RowPosition pos)
private void closeScan() throws StandardException
StandardException
public void close() throws StandardException
GenericScanController
close
in interface GenericScanController
close
in class GenericController
StandardException
public boolean closeForEndTransaction(boolean closeHeldScan) throws StandardException
ScanManager
Use this call to close the scan resources as part of committing or aborting a transaction. The normal close() routine may do some cleanup that is either unnecessary, or not correct due to the unknown condition of the scan following a transaction ending error. Use this call when closing all scans as part of an abort of a transaction.
closeForEndTransaction
in interface ScanManager
closeHeldScan
- If true, means to close scan even if it has been
opened to be kept opened across commit. This is
used to close these scans on abort.
StandardException
- Standard exception policy.public boolean delete() throws StandardException
ScanController
delete
in interface ScanController
StandardException
- Standard exception policy.ScanController.delete()
public void didNotQualify() throws StandardException
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. RESOLVE (mikem-05/29/98) - Implement this when we support levels of concurrency less than serializable.
didNotQualify
in interface ScanController
StandardException
- Standard exception policy.public void fetchSet(long max_rowcnt, int[] key_column_numbers, BackingStoreHashtable hash_table) throws StandardException
This routine scans executes the entire scan as described in the openScan call. For every qualifying unique row value an entry is placed into the HashTable. For unique row values the entry in the Hashtable has a key value of the object stored in row[key_column_number], and the value of the data is row. For row values with duplicates, the key value is also row[key_column_number], but the value of the data is a Vector of rows. The caller will have to call "instanceof" on the data value object if duplicates are expected, to determine if the data value of the Hashtable entry is a row or is a Vector of rows.
Note, that for this routine to work efficiently the caller must ensure that the object in row[key_column_number] implements the hashCode and equals method as appropriate for it's datatype.
It is expected that this call will be the first and only call made in an openscan. Qualifiers and stop position of the openscan are applied just as in a normal scan. This call is logically equivalent to the caller performing the following: import java.util.Hashtable; hash_table = new Hashtable(); while (next()) { row = create_new_row(); fetch(row); if ((duplicate_value = hash_table.put(row[key_column_number], row)) != null) { Vector row_vec; // inserted a duplicate if ((duplicate_value instanceof vector)) { row_vec = (Vector) duplicate_value; } else { // allocate vector to hold duplicates row_vec = new Vector(2); // insert original row into vector row_vec.addElement(duplicate_value); // put the vector as the data rather than the row hash_table.put(row[key_column_number], row_vec); } // insert new row into vector row_vec.addElement(row); } }
The columns of the row will be the standard columns returned as part of a scan, as described by the validColumns - see openScan for description. RESOLVE - is this ok? or should I hard code somehow the row to be the first column and the row location?
Currently it is only possible to hash on the first column in the conglomerate, in the future we may change the interface to allow hashing either on a different column or maybe on a combination of columns.
No overflow to external storage is provided, so calling this routine on a 1 gigabyte conglomerate will incur at least 1 gigabyte of memory (probably failing with a java out of memory condition). If this routine gets an out of memory condition, or if "max_rowcnt" is exceeded then then the routine will give up, empty the Hashtable, and return "false."
On exit from this routine, whether the fetchSet() succeeded or not the scan is complete, it is positioned just the same as if the scan had been drained by calling "next()" until it returns false (ie. fetchNext() and next() calls will return false). reopenScan() can be called to restart the scan.
RESOLVE - until we get row counts what should we do for sizing the the size, capasity, and load factor of the hash table. For now it is up to the caller to create the Hashtable, Access does not reset any parameters.
RESOLVE - I am not sure if access should be in charge of allocating the new row objects. I know that I can do this in the case of btree's, but I don't think I can do this in heaps. Maybe this is solved by work to be done on the sort interface.
fetchSet
in interface ScanManager
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
column in the row in the table of the scan).hash_table
- The java HashTable to load into.
StandardException
- Standard exception policy.public void reopenScan(DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier[][] qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator) throws StandardException
reopenScan
in interface GenericScanController
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.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.
StandardException
- Standard exception policy.public boolean replace(DataValueDescriptor[] row, FormatableBitSet validColumns) throws StandardException
ScanController
replace
in interface ScanController
StandardException
- Standard exception policy.ScanController.replace(org.apache.derby.iapi.types.DataValueDescriptor[], org.apache.derby.iapi.services.io.FormatableBitSet)
public boolean doesCurrentPositionQualify() throws StandardException
doesCurrentPositionQualify
in interface ScanController
StandardException
- Standard exception policy.public void fetch(DataValueDescriptor[] row) throws StandardException
ScanController
fetch
in interface ScanController
row
- The row into which the value of the current
position in the scan is to be stored.
StandardException
- Standard exception policy.ScanController.fetch(org.apache.derby.iapi.types.DataValueDescriptor[])
public void fetchLocation(RowLocation templateLocation) throws StandardException
fetchLocation
in interface ScanController
StandardException
- Standard exception policy.ScanController.fetchLocation(org.apache.derby.iapi.types.RowLocation)
public ScanInfo getScanInfo() throws StandardException
Return ScanInfo object which contains information about the current scan.
getScanInfo
in interface GenericScanController
StandardException
- Standard exception policy.ScanInfo
public boolean isCurrentPositionDeleted() throws StandardException
isCurrentPositionDeleted
in interface ScanController
StandardException
- Standard exception policy.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |