Java Doc for BTreeScan.java in  » Database-DBMS » db-derby-10.2 » org » apache » derby » impl » store » access » btree » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Concurrency Notes<\B>

The concurrency rules are derived from OpenBTree.

See Also:   OpenBTree

Indicates to the ScanController that the current row does not qualify for the scan.

The client allocates an array of N rows and passes it into the fetchNextSet() call.

Any changes to this method may have to be reflected in close as well.

The btree init opens the container (super.init), and stores away the state of the qualifiers.

This routine can only be called "inline" from other btree routines, as it counts on the state of the pos to be correct.

Closing a scan from close() must handle long jumps from exceptions where the state of pos may not be correct.

Position to next page, keeping latch on previous page until we have latch on next page.

Positions the scan to the slot just after the first record to be returned from the backward scan.

Positions the scan to the slot just before the first record to be returned from the scan.

Positions the scan to the slot just before the first record to be returned from the scan.

Check all qualifiers in the qualifier array against row.

When a scan leaves access it saves the RecordHandle of the record on the page.

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.
exception:
  StandardException - Standard exception policy.

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.

The client allocates an array of N rows and passes it into the fetchNextSet() call. This routine does the equivalent of N fetchNext() calls, filling in each of the rows in the array. Locking is performed exactly as if the N fetchNext() calls had been made.

It is up to Access how many rows to return. fetchNextSet() will return how many rows were filled in. If fetchNextSet() returns 0 then the scan is complete, (ie. the scan is in the same state as if fetchNext() had returned false). If the scan is not complete then fetchNext() will return (1 <= row_count <= N).

The current position of the scan is undefined if fetchNextSet() is used (ie. mixing fetch()/fetchNext() and fetchNextSet() calls in a single scan does not work). This is because a fetchNextSet() request for 5 rows from a heap where the first 2 rows qualify, but no other rows qualify will result in the scan being positioned at the end of the table, while if 5 rows did qualify the scan will be positioned on the 5th row.

Qualifiers, start and stop positioning of the openscan are applied just as in a normal scan.

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.

Expected usage: // allocate an array of 5 empty row templates DataValueDescriptor[][] row_array = allocate_row_array(5); int row_cnt = 0; scan = openScan(); while ((row_cnt = scan.fetchNextSet(row_array) != 0) { // I got "row_cnt" rows from the scan. These rows will be // found in row_array[0] through row_array[row_cnt - 1] }

RESOLVE - This interface is being provided so that we can prototype the performance results it can achieve. If it looks like this interface is useful, it is very likely we will look into a better way to tie together the now 4 different fetch interfaces: fetch, fetchNext(), fetchNextGroup(), and fetchSet(). 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
Parameters:
  row_array - The array of rows to copy rows into. row_array[].length must >= 1. This routineassumes that all entries in the array contain complete template rows.
exception:
  StandardException - Standard exception policy.

Utility routine used by both fetchSet() and fetchNextGroup().
exception:
  StandardException - Standard exception policy.

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 BackingStoreHashtable 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.

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.

Any changes to this method may have to be reflected in close as well.

The btree init opens the container (super.init), and stores away the state of the qualifiers. The actual searching for the first position is delayed until the first next() call.
exception:
  StandardException - Standard exception policy.

whether this is a keyed conglomerate.

This routine can only be called "inline" from other btree routines, as it counts on the state of the pos to be correct.

Closing a scan from close() must handle long jumps from exceptions where the state of pos may not be correct. The easiest case is a lock timeout which has caused us not to have a latch on a page, but pos still thinks there is a latch. This is the easiest but other exceptions can also caused the same state at close() time.

Position to next page, keeping latch on previous page until we have latch on next page. This routine releases the latch on current_page once it has successfully gotten both the latch on the next page and the scan lock on the next page.
Parameters:
  pos - current row position of the scan.
exception:
  StandardException - Standard exception policy.

Positions the scan to the slot just after the first record to be returned from the backward scan. Returns the start page latched, and sets "current_slot" to the slot number just right of the first slot to return.

exception:
  StandardException - Standard exception policy.

Positions the scan to the slot just before the first record to be returned from the scan. Returns the start page latched, and sets "current_slot" to the slot number.

exception:
  StandardException - Standard exception policy.

Positions the scan to the slot just before the first record to be returned from the scan. Returns the start page latched, and sets "current_slot" to the slot number.
exception:
  StandardException - Standard exception policy.

Check all qualifiers in the qualifier array against row. Return true if all compares specified by the qualifier array return true, else return false.

It is up to caller to make sure qualifier list is non-null.
Parameters:
  row - The row with the same partial column list as therow returned by the current scan.
exception:
  StandardException - Standard exception policy.

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:
  startRowLocation - An existing RowLocation 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.

When a scan leaves access it saves the RecordHandle of the record on the page. There are 2 cases to consider when trying to reposition the scan when re-entering access: o ROW has not moved off the page. If the row has not moved then the RecordHandle we have saved away is valid, and we just call RawStore to reposition on that RecordHandle (RawStore takes care of the row moving within the page). o ROW has moved off the page. This can only happen in the case of a btree split. In that case the splitter will have caused all scans positioned on this page within the same transaction to save a copy of the row that the scan was positioned on. Then to reposition the scan it is necessary to research the tree from the top using the copy of the row. If the scan has saved it's position by key (and thus has given up the scan lock on the page), there are a few cases where it is possible that the key no longer exists in the table. In the case of a scan held open across commit it is easy to imagine that the row the scan was positioned on could be deleted and subsequently purged from the table all before the scan resumes. Also in the case of read uncommitted the scan holds no lock on the current row, so it could be purged - in the following scenario for instance: read uncommitted transaction 1 opens scan and positions on row (1,2), transaction 2 deletes (1,2) and commits, transaction 1 inserts (1,3) which goes to same page as (1,2) and is going to cause a split, transaction 1 saves scan position as key, gives up scan lock and then purges row (1, 2), when transaction 1 resumes scan (1, 2) no longer exists. missing_row_for_key_ok parameter is added as a sanity check to make sure it ok that repositioning does not go to same row that we were repositioned on.
Parameters:
  pos - position to set the scan to.
Parameters:
  missing_row_for_key_ok - if true and exact key is not found thenscan is just set to key just left ofthe key (thus a next will move to thekey just after "pos") returns true if scan has been repositioned successfully, elsereturns false if the position key could not be found andmissing_row_for_key_ok was false indicating that scan couldonly be positioned on the exact key match.
exception:
  StandardException - Standard exception policy.

The latched page in the conglomerate "congomid" is changing, do whatever is necessary to maintain the current position of the scan. For some conglomerates this may be a no-op.

Parameters:
  conglom - Conglomerate object of the conglomerate being changed.
Parameters:
  page - Page in the conglomerate being changed.
exception:
  StandardException - Standard exception policy.