| java.lang.Object
 org.apache.derby.impl.store.access.conglomerate.GenericController
org.apache.derby.impl.store.access.conglomerate.GenericScanController
All known Subclasses: org.apache.derby.impl.store.access.heap.HeapScan,
| GenericScanController | | abstract public class GenericScanController extends GenericController implements ScanManager(Code) | | 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.
|
| Method Summary | |
| protected RowPosition | allocateScanPosition()
Create object which represents the scan position. | | public void | close()
| | public boolean | closeForEndTransaction(boolean closeHeldScan)
| | public boolean | delete()
| | public void | didNotQualify()
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. | | public boolean | doesCurrentPositionQualify()
Returns true if the current position of the scan still qualifies
under the set of qualifiers passed to the openScan(). | | public void | fetch(DataValueDescriptor[] row)
Fetch the row at the current position of the Scan. | | public 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. | | public 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. | | public void | fetchWithoutQualify(DataValueDescriptor[] row)
Fetch the row at the current position of the Scan without applying the
qualifiers. | | final public int | getNumPagesVisited()
| | final public int | getNumRowsQualified()
| | final public int | getNumRowsVisited()
| | final public Qualifier[][] | getQualifier()
| | final public FormatableBitSet | getScanColumnList()
| | public ScanInfo | getScanInfo()
Return ScanInfo object which describes performance of scan. | | final public RowPosition | getScanPosition()
| | final public int | getScanState()
| | final public DataValueDescriptor[] | getStartKeyValue()
| | final public int | getStartSearchOperator()
| | final public DataValueDescriptor[] | getStopKeyValue()
| | final public int | getStopSearchOperator()
| | public void | init(OpenConglomerate open_conglom, FormatableBitSet scanColumnList, DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator)
| | public 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.
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. | | protected void | positionAtStartForForwardScan(RowPosition pos)
Move the scan from SCAN_INIT to SCAN_INPROGRESS.
This routine is called to move the scan from SCAN_INIT to
SCAN_INPROGRESS. | | final protected boolean | reopenAfterEndTransaction()
Reopens the scan after it has been closed as part of a commit. | | public 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. | | public void | reopenScanByRowLocation(RowLocation startRowLocation, Qualifier qualifier)
| | public boolean | replace(DataValueDescriptor[] row, FormatableBitSet validColumns)
| | abstract protected void | setRowLocationArray(RowLocation[] rowloc_array, int index, RowPosition pos)
| | final public void | setScanPosition(RowPosition pos)
| | final public void | setScanState(int state)
|
| SCAN_DONE | | final public static int SCAN_DONE(Code) | | |
| SCAN_HOLD_INIT | | final public static int SCAN_HOLD_INIT(Code) | | |
| SCAN_HOLD_INPROGRESS | | final public static int SCAN_HOLD_INPROGRESS(Code) | | |
| SCAN_INIT | | final public static int SCAN_INIT(Code) | | Constants of the class
|
| SCAN_INPROGRESS | | final public static int SCAN_INPROGRESS(Code) | | |
| rowLocationsInvalidated | | protected boolean rowLocationsInvalidated(Code) | | If this flag is set to true, a RowLocation returned from this controller
may have been reused for another row.
|
| scan_position | | protected RowPosition scan_position(Code) | | The position for the current scan. The can be maintained in any
of the following ways:
record handle - scan_position.current_rh:
The scan maintains it's position using the record handle while
it does not have a latch on the page, which is the case anytime
control leaves access. The access method must take appropriate
steps to make sure the record handle will still be valid when
the scan needs to reposition using the record handle.
slot number - scan_position.current_slot:
While the scan has a latch on the page the scan is positioned
using the slot number as the order of the rows cannot change
while the latch is held (unless the holder of the latch causes
them to move).
page number - (RESOLVE - TODO)
Sometimes it would be interesting to position a scan "between"
pages, such that the next time the scan starts is starts at
the next page. This would allow us to efficiently do group
scans returning page at atime results.
NOT IMPLEMENTED CURRENTLY.
|
| stat_numpages_visited | | protected int stat_numpages_visited(Code) | | Performance counters ...
|
| stat_numrows_qualified | | protected int stat_numrows_qualified(Code) | | |
| stat_numrows_visited | | protected int stat_numrows_visited(Code) | | |
| allocateScanPosition | | protected RowPosition allocateScanPosition() throws StandardException(Code) | | Create object which represents the scan position.
Designed so that extending classes can override and allocate
implementation specific row position's.
exception:
StandardException - Standard exception policy. |
| didNotQualify | | public void didNotQualify() throws StandardException(Code) | | 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.
RESOLVE (mikem-05/29/98) - Implement this when we support levels of
concurrency less than serializable.
exception:
StandardException - Standard exception policy. |
| doesCurrentPositionQualify | | public boolean doesCurrentPositionQualify() throws StandardException(Code) | | 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.
exception:
StandardException - Standard exception policy. |
| fetchSet | | public void fetchSet(long max_rowcnt, int[] key_column_numbers, BackingStoreHashtable hash_table) throws StandardException(Code) | | Insert all rows that qualify for the current scan into the input
Hash table.
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.
Parameters:
max_rowcnt - The maximum number of rows to insert into the Hash table. Pass in -1 if there is no maximum.
Parameters:
key_column_numbers - The column numbers of the columns in thescan result row to be the key to the Hashtable."0" is the first column in the scan resultrow (which may be different than the firstcolumn in the row in the table of the scan).
Parameters:
hash_table - The java HashTable to load into.
exception:
StandardException - Standard exception policy. |
| getNumPagesVisited | | final public int getNumPagesVisited()(Code) | | |
| getNumRowsQualified | | final public int getNumRowsQualified()(Code) | | |
| getNumRowsVisited | | final public int getNumRowsVisited()(Code) | | |
| getScanInfo | | public ScanInfo getScanInfo() throws StandardException(Code) | | Return ScanInfo object which describes performance of scan.
Return ScanInfo object which contains information about the current
scan.
See Also: ScanInfo The ScanInfo object which contains info about current scan.
exception:
StandardException - Standard exception policy. |
| getScanState | | final public int getScanState()(Code) | | |
| getStartSearchOperator | | final public int getStartSearchOperator()(Code) | | |
| getStopSearchOperator | | final public int getStopSearchOperator()(Code) | | |
| isCurrentPositionDeleted | | public boolean isCurrentPositionDeleted() throws StandardException(Code) | | 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.
exception:
StandardException - Standard exception policy. |
| positionAtInitScan | | protected void positionAtInitScan(DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator, RowPosition pos) throws StandardException(Code) | | Move scan to the the SCAN_INIT state.
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().
|
| positionAtResumeScan | | protected void positionAtResumeScan(RowPosition pos) throws StandardException(Code) | | Reposition the scan upon entering the fetchRows loop.
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.
exception:
StandardException - Standard exception policy. |
| positionAtStartForForwardScan | | protected void positionAtStartForForwardScan(RowPosition pos) throws StandardException(Code) | | Move the scan from SCAN_INIT to SCAN_INPROGRESS.
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.
exception:
StandardException - Standard exception policy. |
| reopenAfterEndTransaction | | final protected boolean reopenAfterEndTransaction() throws StandardException(Code) | | Reopens the scan after it has been closed as part of a commit.
This method will check the reusableRecordIdSequenceNumber of the
container, and will set the rowLocationsInvalidated flag if it has
changed.
true if the conglomerate has been reopened
exception:
StandardException - Derby standard exception |
| reopenScan | | public void reopenScan(DataValueDescriptor[] startKeyValue, int startSearchOperator, Qualifier qualifier, DataValueDescriptor[] stopKeyValue, int stopSearchOperator) throws StandardException(Code) | | 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 with against the same conglomerate, and the scan
is reopened with the same "hold" and "forUpdate" parameters passed in
the original openScan. The previous template row continues to be used.
Parameters:
startKeyValue - An indexable row which holds a (partial) key value which, in combination with thestartSearchOperator, defines the starting position ofthe scan. If null, the starting position of the scanis the first row of the conglomerate.
Parameters:
startSearchOperator - an operator which defineshow the startKeyValue is to be searched for. If startSearchOperator is ScanController.GE, the scan starts onthe 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 thanstartKeyValue. The startSearchOperation parameter is ignored if the startKeyValue parameter is null.
Parameters:
qualifier - An array of qualifiers which, appliedto each key, restrict the rows returned by the scan. Rowsfor which any one of the qualifiers returns false are notreturned by the scan. If null, all rows are returned.
Parameters:
stopKeyValue - An indexable row which holds a (partial) key value which, in combination with thestopSearchOperator, defines the ending position ofthe scan. If null, the ending position of the scanis the last row of the conglomerate.
Parameters:
stopSearchOperator - an operator which defineshow the stopKeyValue is used to determine the scan stoppingposition. If stopSearchOperation is ScanController.GE, the scan stops just before the first row which is greater than orequal to the stopKeyValue. If stopSearchOperation isScanController.GT, the scan stops just before the first row whosekey is greater than startKeyValue. The stopSearchOperationparameter is ignored if the stopKeyValue parameter is null.
exception:
StandardException - Standard exception policy. |
| reopenScanByRecordHandle | | protected void reopenScanByRecordHandle(RecordHandle startRecordHandle, Qualifier qualifier) throws StandardException(Code) | | 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.
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.
Parameters:
startRecordHandle - An existing RecordHandle within the conglomerate,at which to position the start of the scan. The scan will begin at thislocation and continue forward until the end of the conglomerate. Positioning at a non-existent RowLocation (ie. an invalid one or one thathad been deleted), will result in an exception being thrown when the first next operation is attempted.
Parameters:
qualifier - An array of qualifiers which, appliedto each key, restrict the rows returned by the scan. Rowsfor which any one of the qualifiers returns false are notreturned by the scan. If null, all rows are returned.
exception:
StandardException - Standard exception policy. |
| setScanState | | final public void setScanState(int state)(Code) | | |
|
|