Documentation of 'org.apache.derby.impl.store.access.btree.BTreeScan' Java class
BTreeScan
Skip navigation links
org.apache.derby.impl.store.access.btree

Class BTreeScan

    • Constructor Detail

      • BTreeScan

        public BTreeScan()

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

        Specified by:
        didNotQualify in interface ScanController
        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(). 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.

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

      • getScanInfo

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

        Return ScanInfo object which contains information about the current scan.

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

      • isCurrentPositionDeleted

        public boolean isCurrentPositionDeleted()
                                 throws 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.
        Specified by:
        isCurrentPositionDeleted in interface ScanController
        Throws:
        StandardException - Standard exception policy.

      • isKeyed

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

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

      • positionAtRowLocation

        public boolean positionAtRowLocation(RowLocation rLoc)
                              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:
        rLoc - 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:
        Not implemented for this class

      • fetchNext

        public boolean fetchNext(DataValueDescriptor[] row)
                  throws StandardException
        Fetch the row at the next position of the Scan. If there is a valid next position in the scan then the value in the template storable row is replaced with the value of the row at the current scan position. The columns of the template row must be of the same type as the actual columns in the underlying conglomerate. The resulting contents of templateRow 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.
        Specified by:
        fetchNext in interface ScanController
        Parameters:
        row - The template row into which the value of the next position in the scan is to be stored.
        Returns:
        True if there is a next position in the scan, false if there isn't.
        Throws:
        StandardException - Standard exception policy.
        See Also:
        ScanController.fetch(org.apache.derby.iapi.types.DataValueDescriptor[]), RowUtil

      • fetchNextGroup

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

        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().

        Specified by:
        fetchNextGroup in interface GroupFetchScanController
        Parameters:
        row_array - The array of rows to copy rows into. row_array[].length must >= 1. This routine assumes that all entries in the array contain complete template rows.
        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.

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

        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.

        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 column in the row in the table of the scan).
        hash_table - The java HashTable to load into.
        Throws:
        StandardException - Standard exception policy.

      • reopenScan

        public final void reopenScan(DataValueDescriptor[] startKeyValue,
                             int startSearchOperator,
                             Qualifier[][] qualifier,
                             DataValueDescriptor[] stopKeyValue,
                             int stopSearchOperator)
                      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 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.
        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 startSearchOperation 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.

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

        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.

        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.

      • closeForEndTransaction

        public boolean closeForEndTransaction(boolean closeHeldScan)
                               throws StandardException
        Close the scan, a commit or abort is about to happen.
        Specified by:
        closeForEndTransaction in interface ScanManager
        Parameters:
        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.
        Returns:
        boolean indicating that the close has resulted in a real close of the scan. A held scan will return false if called by closeForEndTransaction(false), otherwise it will return true. A non-held scan will always return true.
        Throws:
        StandardException - Standard exception policy.

      • getCurrentRecordHandleForDebugging

        public RecordHandle getCurrentRecordHandleForDebugging()

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
Skip navigation links

DataMelt 3.0 © DataMelt by jWork.ORG

You see the box below because you did not login.