| /* |
| |
| Derby - Class org.apache.derby.impl.store.access.btree.BTreeScan |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to you under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| |
| */ |
| |
| package org.apache.derby.impl.store.access.btree; |
| |
| import org.apache.derby.iapi.reference.SQLState; |
| |
| import org.apache.derby.shared.common.sanity.SanityManager; |
| |
| import org.apache.derby.iapi.error.StandardException; |
| |
| import org.apache.derby.iapi.store.access.conglomerate.LogicalUndo; |
| import org.apache.derby.iapi.store.access.conglomerate.ScanManager; |
| import org.apache.derby.iapi.store.access.conglomerate.TransactionManager; |
| |
| import org.apache.derby.iapi.store.access.ConglomerateController; |
| import org.apache.derby.iapi.store.access.DynamicCompiledOpenConglomInfo; |
| import org.apache.derby.iapi.store.access.Qualifier; |
| import org.apache.derby.iapi.store.access.RowUtil; |
| import org.apache.derby.iapi.store.access.ScanController; |
| import org.apache.derby.iapi.store.access.ScanInfo; |
| import org.apache.derby.iapi.store.access.StaticCompiledOpenConglomInfo; |
| |
| import org.apache.derby.iapi.store.raw.ContainerHandle; |
| import org.apache.derby.iapi.store.raw.FetchDescriptor; |
| import org.apache.derby.iapi.store.raw.LockingPolicy; |
| import org.apache.derby.iapi.store.raw.Page; |
| import org.apache.derby.iapi.store.raw.RecordHandle; |
| import org.apache.derby.iapi.store.raw.Transaction; |
| |
| import org.apache.derby.iapi.types.DataValueDescriptor; |
| |
| import org.apache.derby.iapi.types.RowLocation; |
| |
| import org.apache.derby.impl.store.access.conglomerate.TemplateRow; |
| |
| import org.apache.derby.iapi.services.io.FormatableBitSet; |
| import org.apache.derby.iapi.store.access.BackingStoreHashtable; |
| |
| /** |
| |
| A b-tree scan controller corresponds to an instance of an open b-tree scan. |
| <P> |
| <B>Concurrency Notes</B> |
| <P> |
| The concurrency rules are derived from OpenBTree. |
| <P> |
| @see OpenBTree |
| |
| **/ |
| |
| public abstract class BTreeScan extends OpenBTree implements ScanManager |
| { |
| |
| /* |
| ** Fields of BTreeScan |
| */ |
| |
| /** |
| * init_startKeyValue, init_qualifier, and init_stopKeyValue all are used |
| * to store * references to the values passed in when ScanController.init() |
| * is called. It is assumed that these are not altered by the client |
| * while the scan is active. |
| */ |
| protected Transaction init_rawtran = null; |
| protected boolean init_forUpdate; |
| protected FormatableBitSet init_scanColumnList; |
| protected DataValueDescriptor[] init_template; |
| protected DataValueDescriptor[] init_startKeyValue; |
| protected int init_startSearchOperator = 0; |
| protected Qualifier init_qualifier[][] = null; |
| protected DataValueDescriptor[] init_stopKeyValue; |
| protected int init_stopSearchOperator = 0; |
| protected boolean init_hold; |
| |
| |
| /** |
| * The fetch descriptor which describes the row to be returned by the scan. |
| **/ |
| protected FetchDescriptor init_fetchDesc; |
| |
| |
| /** |
| * A constant FetchDescriptor which describes the position of the |
| * RowLocation field within the btree, currently always the last column). |
| * Used by lock/unlock to fetch the RowLocation. |
| * Only needs to be allocated once per scan. |
| **/ |
| protected FetchDescriptor init_lock_fetch_desc; |
| |
| |
| BTreeRowPosition scan_position; |
| |
| |
| /** |
| * Whether the scan should requests UPDATE locks which then will be |
| * converted to X locks when the actual operation is performed. |
| **/ |
| protected boolean init_useUpdateLocks = false; |
| |
| /* |
| * There are 5 states a scan can be in. |
| * SCAN_INIT - A scan has started but no positioning has been done. |
| * The scan will be positioned when the first next() call |
| * has been made. None of the positioning state variables |
| * are valid in this state. |
| * SCAN_INPROGRESS - |
| * A scan is in this state after the first next() call. |
| * On exit from any BTreeScan method, while in this state, |
| * the scan "points" at a row which qualifies for the |
| * scan. While not maintaining latches on a page the |
| * current position of the scan is either kept by record |
| * handle or key. To tell which use the following: |
| * if (record key == null) |
| * record handle has current position |
| * else |
| * record key has current position |
| * |
| * SCAN_DONE - Once the end of the table or the stop condition is met |
| * then the scan is placed in this state. Only valid |
| * ScanController method at this point is close(). |
| * |
| * SCAN_HOLD_INIT - |
| * The scan has been opened and held open across a commit, |
| * at the last commit the state was SCAN_INIT. |
| * The scan has never progressed from the SCAN_INIT state |
| * during a transaction. When a next is done the state |
| * will either progress to SCAN_INPROGRESS or SCAN_DONE. |
| * |
| * SCAN_HOLD_INPROGRESS - |
| * The scan has been opened and held open across a commit, |
| * at the last commit the state was in SCAN_INPROGRESS. |
| * The transaction which opened the scan has committed, |
| * but the scan was opened with the "hold" option true. |
| * At commit the locks were released and the "current" |
| * position is remembered. In this state only two calls |
| * are valid, either next() or close(). When next() is |
| * called the scan is reopened, the underlying container |
| * is opened thus associating all new locks with the current |
| * transaction, and the scan continues at the "next" row. |
| */ |
| protected static final int SCAN_INIT = 1; |
| protected static final int SCAN_INPROGRESS = 2; |
| protected static final int SCAN_DONE = 3; |
| protected static final int SCAN_HOLD_INIT = 4; |
| protected static final int SCAN_HOLD_INPROGRESS = 5; |
| |
| /** |
| * Delay positioning the table at the start position until the first |
| * next() call. The initial position is done in positionAtStartPosition(). |
| */ |
| protected int scan_state = SCAN_INIT; |
| |
| /** |
| * Performance counters ... |
| */ |
| protected int stat_numpages_visited = 0; |
| protected int stat_numrows_visited = 0; |
| protected int stat_numrows_qualified = 0; |
| protected int stat_numdeleted_rows_visited = 0; |
| |
| /** |
| * What kind of row locks to get during the scan. |
| **/ |
| protected int lock_operation; |
| |
| |
| /** |
| * A 1 element array to turn fetchNext and fetch calls into |
| * fetchNextGroup calls. |
| **/ |
| protected DataValueDescriptor[][] fetchNext_one_slot_array = |
| new DataValueDescriptor[1][]; |
| |
| /* Constructors for This class: */ |
| |
| public BTreeScan() |
| { |
| } |
| |
| /* |
| ** Private/Protected methods of This class, sorted alphabetically |
| */ |
| |
| /** |
| * Fetch the next N rows from the table. |
| * <p> |
| * Utility routine used by both fetchSet() and fetchNextGroup(). |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| abstract protected int fetchRows( |
| BTreeRowPosition pos, |
| DataValueDescriptor[][] row_array, |
| RowLocation[] rowloc_array, |
| BackingStoreHashtable hash_table, |
| long max_rowcnt, |
| int[] key_column_numbers) |
| throws StandardException; |
| |
| |
| /** |
| * Shared initialization code between init() and reopenScan(). |
| * <p> |
| * Basically save away input parameters describing qualifications for |
| * the scan, and do some error checking. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| private void initScanParams( |
| DataValueDescriptor[] startKeyValue, |
| int startSearchOperator, |
| Qualifier qualifier[][], |
| DataValueDescriptor[] stopKeyValue, |
| int stopSearchOperator) |
| throws StandardException |
| { |
| // startKeyValue init. |
| this.init_startKeyValue = startKeyValue; |
| if (RowUtil.isRowEmpty(this.init_startKeyValue)) |
| this.init_startKeyValue = null; |
| |
| // startSearchOperator init. |
| this.init_startSearchOperator = startSearchOperator; |
| |
| // qualifier init. |
| if ((qualifier != null) && (qualifier .length == 0)) |
| qualifier = null; |
| this.init_qualifier = qualifier; |
| |
| // stopKeyValue init. |
| this.init_stopKeyValue = stopKeyValue; |
| if (RowUtil.isRowEmpty(this.init_stopKeyValue)) |
| this.init_stopKeyValue = null; |
| |
| // stopSearchOperator init. |
| this.init_stopSearchOperator = stopSearchOperator; |
| |
| // reset the "current" position to starting condition. |
| // RESOLVE (mmm) - "compile" this. |
| scan_position = new BTreeRowPosition(this); |
| |
| scan_position.init(); |
| |
| scan_position.current_lock_template = |
| new DataValueDescriptor[this.init_template.length]; |
| |
| scan_position.current_lock_template[this.init_template.length - 1] = |
| scan_position.current_lock_row_loc = (RowLocation) |
| init_template[init_template.length - 1].cloneValue(false); |
| |
| // Verify that all columns in start key value, stop key value, and |
| // qualifiers are present in the list of columns described by the |
| // scanColumnList. |
| if (SanityManager.DEBUG) |
| { |
| if (init_scanColumnList != null) |
| { |
| // verify that all columns specified in qualifiers, start |
| // and stop positions are specified in the scanColumnList. |
| |
| FormatableBitSet required_cols; |
| |
| if (qualifier != null) |
| required_cols = RowUtil.getQualifierBitSet(qualifier); |
| else |
| required_cols = new FormatableBitSet(0); |
| |
| // add in start columns |
| if (this.init_startKeyValue != null) |
| { |
| required_cols.grow(this.init_startKeyValue.length); |
| for (int i = 0; i < this.init_startKeyValue.length; i++) |
| required_cols.set(i); |
| } |
| |
| if (this.init_stopKeyValue != null) |
| { |
| required_cols.grow(this.init_stopKeyValue.length); |
| for (int i = 0; i < this.init_stopKeyValue.length; i++) |
| required_cols.set(i); |
| } |
| |
| FormatableBitSet required_cols_and_scan_list = |
| (FormatableBitSet) required_cols.clone(); |
| |
| required_cols_and_scan_list.and(init_scanColumnList); |
| |
| // FormatableBitSet equals requires the two FormatableBitSets to be of same |
| // length. |
| required_cols.grow(init_scanColumnList.size()); |
| |
| if (!required_cols_and_scan_list.equals(required_cols)) |
| { |
| SanityManager.THROWASSERT( |
| "Some column specified in a Btree " + |
| " qualifier/start/stop list is " + |
| "not represented in the scanColumnList." + |
| "\n:required_cols_and_scan_list = " + |
| required_cols_and_scan_list + |
| "\n;required_cols = " + required_cols + |
| "\n;init_scanColumnList = " + init_scanColumnList); |
| } |
| } |
| } |
| } |
| |
| /** |
| * Position scan at "start" position for a forward scan. |
| * <p> |
| * 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. |
| * <p> |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| protected void positionAtStartForForwardScan( |
| BTreeRowPosition pos) |
| throws StandardException |
| { |
| boolean exact; |
| |
| // This routine should only be called from first next() call // |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT( |
| (scan_state == SCAN_INIT) || (scan_state == SCAN_HOLD_INIT)); |
| SanityManager.ASSERT(pos.current_rh == null); |
| SanityManager.ASSERT(pos.current_positionKey == null); |
| } |
| |
| // Loop until you can lock the row previous to the first row to be |
| // returned by the scan, while holding the page latched, without |
| // waiting. If you have to wait, drop the latch, wait for the lock - |
| // which makes it likely if you wait for the lock you will loop just |
| // once, find the same lock satisfies the search and since you already |
| // have the lock it will be granted. |
| while (true) |
| { |
| // Find the starting page and row slot, must start at root and |
| // search either for leftmost leaf, or search for specific key. |
| ControlRow root = ControlRow.get(this, BTree.ROOTPAGEID); |
| |
| // include search of tree in page visited stats. |
| stat_numpages_visited += root.getLevel() + 1; |
| |
| boolean need_previous_lock = true; |
| |
| if (init_startKeyValue == null) |
| { |
| // No start given, so position at 0 slot of leftmost leaf page |
| pos.current_leaf = (LeafControlRow) root.searchLeft(this); |
| |
| pos.current_slot = ControlRow.CR_SLOT; |
| exact = false; |
| } |
| else |
| { |
| // Search for the starting row. |
| |
| if (SanityManager.DEBUG) |
| SanityManager.ASSERT( |
| (init_startSearchOperator == ScanController.GE) || |
| (init_startSearchOperator == ScanController.GT)); |
| |
| SearchParameters sp = new SearchParameters( |
| init_startKeyValue, |
| ((init_startSearchOperator == ScanController.GE) ? |
| SearchParameters.POSITION_LEFT_OF_PARTIAL_KEY_MATCH : |
| SearchParameters.POSITION_RIGHT_OF_PARTIAL_KEY_MATCH), |
| init_template, this, false); |
| |
| pos.current_leaf = (LeafControlRow) root.search(sp); |
| |
| pos.current_slot = sp.resultSlot; |
| exact = sp.resultExact; |
| |
| // The way that scans are used, the caller calls next() |
| // to position on the first row. If the result of the |
| // search that found the starting page and slot was not |
| // exact, then the page/slot will refer to the row before |
| // the first qualifying row. The first call to next() |
| // will therefore move to the first (potentially) qualifying |
| // row. However, if the search was exact, then we don't |
| // want to move the position on the first call to next. |
| // In that case, by decrementing the slot, the first call |
| // to next will put us back on the starting row. |
| |
| if (exact && init_startSearchOperator == ScanController.GE) |
| { |
| pos.current_slot--; |
| |
| // A scan on a unique index, with a start position of |
| // GE, need not get a previous key lock to protect the |
| // range. Since it is unique no other key can go before |
| // the first row returned from the scan. |
| // |
| // RESOLVE - currently btree's only support allowDuplicates |
| // of "false", so no need to do the extra check, current |
| // btree implementation depends on RowLocation field |
| // making every key unique (duplicate indexes are supported |
| // by the nUniqueColumns and nKeyFields). |
| if (getConglomerate().nUniqueColumns < getConglomerate().nKeyFields) |
| { |
| // this implies unique index, thus no prev key. |
| need_previous_lock = false; |
| } |
| } |
| } |
| |
| boolean latch_released = false; |
| if (need_previous_lock) |
| { |
| latch_released = |
| !this.getLockingPolicy().lockScanRow( |
| this, pos, |
| init_lock_fetch_desc, |
| pos.current_lock_template, |
| pos.current_lock_row_loc, |
| true, init_forUpdate, |
| lock_operation); |
| } |
| |
| // special test to see if latch release code works |
| if (SanityManager.DEBUG) |
| { |
| latch_released = |
| test_errors( |
| this, |
| "BTreeScan_positionAtStartPosition", |
| null, // no need to save the position, since we'll |
| // retry the operation if the latch is released |
| this.getLockingPolicy(), |
| pos.current_leaf, latch_released); |
| } |
| |
| if (latch_released) |
| { |
| // lost latch on pos.current_leaf, search the tree again. |
| // Forget the current position since we'll use the start key |
| // to reposition on the start of the scan. |
| pos.init(); |
| continue; |
| } |
| else |
| { |
| // success! got all the locks, while holding the latch. |
| break; |
| } |
| } |
| |
| this.scan_state = SCAN_INPROGRESS; |
| |
| if (SanityManager.DEBUG) |
| SanityManager.ASSERT(pos.current_leaf != null); |
| } |
| |
| /** |
| * Position scan to 0 slot on next page. |
| * <p> |
| * 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 the latch on the next page. |
| * |
| * @param pos current row position of the scan. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| protected void positionAtNextPage( |
| BTreeRowPosition pos) |
| throws StandardException |
| { |
| |
| pos.next_leaf = (LeafControlRow) pos.current_leaf.getRightSibling(this); |
| |
| // Now that we either have the latch on next leaf, or there is no next |
| // leaf, we can release the latch on the current page. |
| |
| // unlock the previous row if doing read. |
| if (pos.current_rh != null) |
| { |
| this.getLockingPolicy().unlockScanRecordAfterRead( |
| pos, init_forUpdate); |
| } |
| |
| pos.current_leaf.release(); |
| pos.current_leaf = pos.next_leaf; |
| |
| // set up for scan to continue at beginning of next page. |
| pos.current_slot = Page.FIRST_SLOT_NUMBER; |
| pos.current_rh = null; |
| } |
| |
| /** |
| * <p> |
| * Position the scan after the last row on the previous page. Hold the |
| * latch on the current page until the previous page has been latched. If |
| * the immediate left sibling is empty, move further until a non-empty page |
| * is found or there are no more leaves to be found. The latch on the |
| * current page will be held until a non-empty left sibling page is found. |
| * </p> |
| * |
| * <p> |
| * This method never waits for a latch, as waiting for latches while |
| * holding another latch is only allowed when moving forward in the B-tree. |
| * Waiting while moving backward may result in deadlocks with scanners |
| * going forward. A {@code WaitError} is thrown if the previous page cannot |
| * be latched without waiting. {@code scan_position.current_leaf} will |
| * point to the same page as before the method was called in the case where |
| * a {@code WaitError} is thrown, and the page will still be latched. |
| * </p> |
| * |
| * @throws StandardException standard exception policy |
| * @throws WaitError if the previous page cannot be latched immediately |
| */ |
| protected void positionAtPreviousPage() |
| throws StandardException, WaitError { |
| BTreeRowPosition pos = scan_position; |
| |
| LeafControlRow leaf = |
| (LeafControlRow) pos.current_leaf.getLeftSibling(this); |
| |
| // Skip empty leaves. We don't want to stop on empty pages while |
| // moving backwards, since pages with no rows have no keys and we will |
| // need to save the current position by key if we cannot latch a page |
| // immediately. |
| while (leaf != null && isEmpty(leaf.page)) |
| { |
| final LeafControlRow next; |
| try { |
| next = (LeafControlRow) leaf.getLeftSibling(this); |
| } finally { |
| leaf.release(); |
| } |
| |
| // Successfully managed to latch the leaf to the left of the empty |
| // sibling page. Use that leaf instead. |
| leaf = next; |
| } |
| |
| // Now that we either have the latch on the first non-empty leaf to |
| // the left of the current leaf, or we have passed the leftmost leaf, |
| // we can release the latch on the current page. |
| |
| // Unlock the previous row if doing read. |
| if (pos.current_rh != null) |
| { |
| this.getLockingPolicy().unlockScanRecordAfterRead( |
| pos, init_forUpdate); |
| } |
| |
| pos.current_leaf.release(); |
| pos.current_leaf = leaf; |
| |
| // Set up for scan to continue at the end of the page. |
| pos.current_slot = (pos.current_leaf == null) ? |
| Page.INVALID_SLOT_NUMBER : pos.current_leaf.page.recordCount(); |
| pos.current_rh = null; |
| } |
| |
| /** |
| * Check if a B-tree page is empty. The control row, which is always |
| * present, is not counted. |
| * |
| * @param page the B-tree page to check |
| * @return true if the page is empty, false otherwise |
| * @throws StandardException standard exception policy |
| */ |
| static boolean isEmpty(Page page) throws StandardException { |
| // Because of the control row, the page should always have at least |
| // one record. It's empty if that's the only record on the page. |
| if (SanityManager.DEBUG) { |
| SanityManager.ASSERT( |
| page.recordCount() > 0, "Page without control row?"); |
| } |
| return page.recordCount() <= 1; |
| } |
| |
| /** |
| Position scan at "start" position. |
| <p> |
| 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. |
| **/ |
| abstract void positionAtStartPosition( |
| BTreeRowPosition pos) |
| throws StandardException; |
| |
| |
| /** |
| * Do any necessary work to complete the scan. |
| * |
| * @param pos current row position of the scan. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| protected void positionAtDoneScanFromClose( |
| BTreeRowPosition pos) |
| throws StandardException |
| { |
| // call unlockScanRecordAfterRead() before closing, currently |
| // this is only important for releasing RR locks on non-qualified |
| // rows. |
| // |
| // Otherwise the correct behavior happens as part of the close, ie.: |
| // |
| // for READ_UNCOMMITTED there is no lock to release, |
| // for READ_COMMITTED all read locks will be released, |
| // for REPEATABLE_READ or SERIALIZABLE no locks are released. |
| |
| if ((pos.current_rh != null) && !pos.current_rh_qualified) |
| { |
| if (pos.current_leaf == null || pos.current_leaf.page == null) |
| { |
| // If we are being called from a "normal" close then there |
| // will be no latch on current_leaf, get it and do the the |
| // unlock. We may be called sometimes, after an error where |
| // we may have the latch, in this case the transaction is about |
| // to be backed out anyway so don't worry about doing this |
| // unlock (thus why we only do the following code if we |
| // "don't" have lock, ie. pos.current_leaf== null). |
| |
| this.getLockingPolicy().unlockScanRecordAfterRead( |
| pos, init_forUpdate); |
| } |
| } |
| |
| pos.current_slot = Page.INVALID_SLOT_NUMBER; |
| pos.current_rh = null; |
| pos.current_positionKey = null; |
| this.scan_state = SCAN_DONE; |
| |
| return; |
| } |
| |
| /** |
| * Do work necessary to close a scan. |
| * <p> |
| * This routine can only be called "inline" from other btree routines, |
| * as it counts on the state of the pos to be correct. |
| * <p> |
| * 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. |
| **/ |
| protected void positionAtDoneScan( |
| BTreeRowPosition pos) |
| throws StandardException |
| { |
| |
| pos.current_slot = Page.INVALID_SLOT_NUMBER; |
| pos.current_rh = null; |
| pos.current_positionKey = null; |
| this.scan_state = SCAN_DONE; |
| |
| return; |
| } |
| |
| |
| /** |
| * process_qualifier - Determine if a row meets all qualifier conditions. |
| * <p> |
| * Check all qualifiers in the qualifier array against row. Return true |
| * if all compares specified by the qualifier array return true, else |
| * return false. |
| * <p> |
| * It is up to caller to make sure qualifier list is non-null. |
| * |
| * @param row The row with the same partial column list as the |
| * row returned by the current scan. |
| * |
| * @exception StandardException Standard exception policy. |
| */ |
| protected boolean process_qualifier( |
| DataValueDescriptor[] row) |
| throws StandardException |
| { |
| boolean row_qualifies = true; |
| Qualifier q; |
| |
| // Process the 2-d qualifier which is structured as follows: |
| // |
| // A two dimensional array is to be used to pass around a AND's and OR's |
| // in conjunctive normal form (CNF). The top slot of the 2 dimensional |
| // array is optimized for the more frequent where no OR's are present. |
| // The first array slot is always a list of AND's to be treated as |
| // described above for single dimensional AND qualifier arrays. The |
| // subsequent slots are to be treated as AND'd arrays or OR's. Thus |
| // the 2 dimensional array qual[][] argument is to be treated as the |
| // following, note if qual.length = 1 then only the first array is |
| // valid and // it is and an array of and clauses: |
| // |
| // (qual[0][0] and qual[0][0] ... and qual[0][qual[0].length - 1]) |
| // and |
| // (qual[1][0] or qual[1][1] ... or qual[1][qual[1].length - 1]) |
| // and |
| // (qual[2][0] or qual[2][1] ... or qual[2][qual[2].length - 1]) |
| // ... |
| // and |
| // (qual[qual.length - 1][0] or qual[1][1] ... or qual[1][2]) |
| |
| // First do the qual[0] which is an array of qualifer terms. |
| |
| if (SanityManager.DEBUG) |
| { |
| // routine should not be called if there is no qualifier |
| SanityManager.ASSERT(this.init_qualifier != null); |
| SanityManager.ASSERT(this.init_qualifier.length > 0); |
| } |
| |
| for (int i = 0; i < this.init_qualifier[0].length; i++) |
| { |
| // process each AND clause |
| |
| row_qualifies = false; |
| |
| // process each OR clause. |
| |
| q = this.init_qualifier[0][i]; |
| |
| // Get the column from the possibly partial row, of the |
| // q.getColumnId()'th column in the full row. |
| DataValueDescriptor columnValue = row[q.getColumnId()]; |
| |
| row_qualifies = |
| columnValue.compare( |
| q.getOperator(), |
| q.getOrderable(), |
| q.getOrderedNulls(), |
| q.getUnknownRV()); |
| |
| if (q.negateCompareResult()) |
| row_qualifies = !row_qualifies; |
| |
| // Once an AND fails the whole Qualification fails - do a return! |
| if (!row_qualifies) |
| return(false); |
| } |
| |
| // all the qual[0] and terms passed, now process the OR clauses |
| |
| for (int and_idx = 1; and_idx < this.init_qualifier.length; and_idx++) |
| { |
| // process each AND clause |
| |
| row_qualifies = false; |
| |
| if (SanityManager.DEBUG) |
| { |
| // Each OR clause must be non-empty. |
| SanityManager.ASSERT(this.init_qualifier[and_idx].length > 0); |
| } |
| |
| for (int or_idx = 0; |
| or_idx < this.init_qualifier[and_idx].length; or_idx++) |
| { |
| // process each OR clause. |
| |
| q = this.init_qualifier[and_idx][or_idx]; |
| |
| // Get the column from the possibly partial row, of the |
| // q.getColumnId()'th column in the full row. |
| DataValueDescriptor columnValue = row[q.getColumnId()]; |
| |
| row_qualifies = |
| columnValue.compare( |
| q.getOperator(), |
| q.getOrderable(), |
| q.getOrderedNulls(), |
| q.getUnknownRV()); |
| |
| if (q.negateCompareResult()) |
| row_qualifies = !row_qualifies; |
| |
| // once one OR qualifies the entire clause is TRUE |
| if (row_qualifies) |
| break; |
| } |
| |
| if (!row_qualifies) |
| break; |
| } |
| |
| return(row_qualifies); |
| } |
| |
| |
| /** |
| * Reposition the scan leaving and reentering the access layer. |
| * <p> |
| * 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. |
| * |
| * 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, 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. |
| * |
| * |
| * |
| * @param pos position to set the scan to. |
| * |
| * @param missing_row_for_key_ok if true and exact key is not found then |
| * scan is just set to key just left of |
| * the key (thus a next will move to the |
| * key just after "pos") |
| * |
| * @return returns true if scan has been repositioned successfully, else |
| * returns false if the position key could not be found and |
| * missing_row_for_key_ok was false indicating that scan could |
| * only be positioned on the exact key match. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| protected boolean reposition( |
| BTreeRowPosition pos, |
| boolean missing_row_for_key_ok) |
| throws StandardException |
| { |
| // RESOLVE (mikem) - performance - we need to do a buffer manager |
| // get for every row returned from the scan. It may be better to |
| // allow a reference to the page with no latch (ie. a fixed bit). |
| |
| if (this.scan_state != SCAN_INPROGRESS) |
| { |
| throw StandardException.newException( |
| SQLState.BTREE_SCAN_NOT_POSITIONED, |
| this.scan_state); |
| } |
| |
| // positionKey is always valid |
| if (SanityManager.DEBUG) |
| { |
| if (pos.current_positionKey == null) |
| SanityManager.THROWASSERT( |
| "pos.current_rh = (" + pos.current_rh + "), " + |
| "pos.current_positionKey = (" + |
| pos.current_positionKey + ")."); |
| } |
| |
| if (pos.current_positionKey == null) |
| { |
| throw StandardException.newException( |
| SQLState.BTREE_SCAN_INTERNAL_ERROR, |
| (pos.current_rh == null), |
| (pos.current_positionKey == null)); |
| } |
| |
| // If current_rh is non-null, we know the exact physical position of |
| // the scan before the latch on the leaf was released. Check if the |
| // row is still on that position so that we don't need to renavigate |
| // from the root of the B-tree in the common case. |
| if (pos.current_rh != null) |
| { |
| // Reposition to remembered spot on page. |
| |
| // Get the page object. If getPage() returns null, the page is |
| // not valid (could for instance have been removed by compress |
| // table) so we need to reposition by key instead. |
| Page page = container.getPage(pos.current_rh.getPageNumber()); |
| if (page != null) { |
| ControlRow row = |
| ControlRow.getControlRowForPage(container, page); |
| if (row instanceof LeafControlRow && |
| !row.page.isRepositionNeeded(pos.versionWhenSaved)) { |
| // No rows have been moved off the page after we released |
| // the latch, and the page is still a leaf page. No need |
| // to reposition by key. |
| pos.current_leaf = (LeafControlRow) row; |
| pos.current_slot = row.page.getSlotNumber(pos.current_rh); |
| pos.current_positionKey = null; |
| return true; |
| } |
| // We couldn't use the position specified by current_rh, so we |
| // need to reposition by key and may find the row on another |
| // page. Therefore, give up the latch on this page. |
| row.release(); |
| } |
| } |
| |
| SearchParameters sp = |
| new SearchParameters( |
| pos.current_positionKey, |
| // this is a full key search, so this arg is not used. |
| SearchParameters.POSITION_LEFT_OF_PARTIAL_KEY_MATCH, |
| init_template, this, false); |
| |
| pos.current_leaf = (LeafControlRow) |
| ControlRow.get(this, BTree.ROOTPAGEID).search(sp); |
| |
| if (!sp.resultExact && !missing_row_for_key_ok) |
| { |
| // Did not find key to exactly position on. |
| |
| pos.current_leaf.release(); |
| pos.current_leaf = null; |
| return (false); |
| } |
| |
| pos.current_slot = sp.resultSlot; |
| |
| // Need to update current_rh to the new position. current_rh should |
| // only be non-null if the row was locked when the position was saved, |
| // so we don't set it here if its old value is null. |
| if (pos.current_rh != null) { |
| pos.current_rh = pos.current_leaf.page. |
| getRecordHandleAtSlot(pos.current_slot); |
| } |
| |
| pos.current_positionKey = null; |
| |
| return(true); |
| } |
| |
| /* |
| ** Public Methods of BTreeScan |
| */ |
| |
| |
| /** |
| Initialize the scan for use. |
| <p> |
| Any changes to this method may have to be reflected in close as well. |
| <p> |
| 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. |
| **/ |
| public void init( |
| TransactionManager xact_manager, |
| Transaction rawtran, |
| boolean hold, |
| int open_mode, |
| int lock_level, |
| BTreeLockingPolicy btree_locking_policy, |
| FormatableBitSet scanColumnList, |
| DataValueDescriptor[] startKeyValue, |
| int startSearchOperator, |
| Qualifier qualifier[][], |
| DataValueDescriptor[] stopKeyValue, |
| int stopSearchOperator, |
| BTree conglomerate, |
| LogicalUndo undo, |
| StaticCompiledOpenConglomInfo static_info, |
| DynamicCompiledOpenConglomInfo dynamic_info) |
| throws StandardException |
| { |
| super.init( |
| xact_manager, xact_manager, (ContainerHandle) null, rawtran, |
| hold, |
| open_mode, lock_level, btree_locking_policy, |
| conglomerate, undo, dynamic_info); |
| |
| |
| this.init_rawtran = rawtran; |
| this.init_forUpdate = |
| ((open_mode & ContainerHandle.MODE_FORUPDATE) == |
| ContainerHandle.MODE_FORUPDATE); |
| |
| // Keep track of whether this scan should use update locks. |
| this.init_useUpdateLocks = |
| ((open_mode & |
| ContainerHandle.MODE_USE_UPDATE_LOCKS) != 0); |
| |
| this.init_hold = hold; |
| |
| this.init_template = |
| runtime_mem.get_template(getRawTran()); |
| |
| this.init_scanColumnList = scanColumnList; |
| |
| this.init_lock_fetch_desc = |
| RowUtil.getFetchDescriptorConstant(init_template.length - 1); |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT( |
| init_lock_fetch_desc.getMaxFetchColumnId() == |
| (init_template.length - 1)); |
| SanityManager.ASSERT( |
| (init_lock_fetch_desc.getValidColumnsArray())[init_template.length - 1] == 1); |
| } |
| |
| // note that we don't process qualifiers in btree fetch's |
| this.init_fetchDesc = |
| new FetchDescriptor( |
| init_template.length, init_scanColumnList,(Qualifier[][]) null); |
| |
| initScanParams( |
| startKeyValue, startSearchOperator, |
| qualifier, stopKeyValue, stopSearchOperator); |
| |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT( |
| TemplateRow.checkColumnTypes( |
| getRawTran().getDataValueFactory(), |
| this.getConglomerate().format_ids, |
| this.getConglomerate().collation_ids, |
| init_template)); |
| } |
| |
| // System.out.println("initializing scan:" + this); |
| |
| // initialize default locking operation for the scan. |
| this.lock_operation = |
| (init_forUpdate ? |
| ConglomerateController.LOCK_UPD : |
| ConglomerateController.LOCK_READ); |
| |
| if (init_useUpdateLocks) |
| this.lock_operation |= ConglomerateController.LOCK_UPDATE_LOCKS; |
| |
| // System.out.println("Btree scan: " + this); |
| } |
| |
| |
| |
| /* |
| ** Methods of ScanController |
| */ |
| |
| /** |
| Close the scan. |
| **/ |
| public void close() |
| throws StandardException |
| { |
| // Scan is closed, make sure no access to any state variables |
| positionAtDoneScanFromClose(scan_position); |
| |
| super.close(); |
| |
| // null out so that these object's can get GC'd earlier. |
| this.init_rawtran = null; |
| this.init_template = null; |
| this.init_startKeyValue = null; |
| this.init_qualifier = null; |
| this.init_stopKeyValue = null; |
| |
| this.getXactMgr().closeMe(this); |
| } |
| |
| /** |
| Delete the row at the current position of the scan. |
| @see ScanController#delete |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public boolean delete() |
| throws StandardException |
| { |
| boolean ret_val = false; |
| |
| if (scan_state != SCAN_INPROGRESS) |
| throw StandardException.newException( |
| SQLState.AM_SCAN_NOT_POSITIONED); |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT(this.container != null, |
| "BTreeScan.delete() called on a closed scan."); |
| SanityManager.ASSERT(init_forUpdate); |
| } |
| |
| try |
| { |
| // Get current page of scan, with latch. |
| if (!reposition(scan_position, false)) |
| { |
| throw StandardException.newException( |
| SQLState.AM_RECORD_NOT_FOUND, |
| err_containerid, |
| scan_position.current_rh.getPageNumber(), |
| scan_position.current_rh.getId()); |
| } |
| |
| |
| if (init_useUpdateLocks) |
| { |
| // RESOLVE (mikem) - I don't think lockScanRow() is the right |
| // thing to call. |
| |
| // if we are doing update locking, then we got an U lock on |
| // this row when the scan positioned on it, but now that we |
| // are doing a delete on the current position we need to upgrade |
| // the lock to X. |
| boolean latch_released = |
| !this.getLockingPolicy().lockScanRow( |
| this, scan_position, |
| init_lock_fetch_desc, |
| scan_position.current_lock_template, |
| scan_position.current_lock_row_loc, |
| false, init_forUpdate, lock_operation); |
| |
| // Special test to see if latch release code works. |
| if (SanityManager.DEBUG) |
| { |
| latch_released = test_errors( |
| this, "BTreeScan_delete_useUpdateLocks", |
| scan_position, getLockingPolicy(), |
| scan_position.current_leaf, latch_released); |
| } |
| |
| if (latch_released) |
| { |
| // lost latch on page in order to wait for row lock. |
| // reposition() will take care of the complexity of |
| // positioning on the correct page if the row has been |
| // moved to another page. |
| if (!reposition(scan_position, false)) |
| { |
| throw StandardException.newException( |
| SQLState.AM_RECORD_NOT_FOUND, |
| err_containerid, |
| scan_position.current_rh.getPageNumber(), |
| scan_position.current_rh.getId()); |
| } |
| } |
| } |
| |
| if (SanityManager.DEBUG) |
| { |
| // DERBY-2197: Assume no row locking here. If locking policy |
| // requires row locking, we would need to obtain a row lock at |
| // this point. |
| SanityManager.ASSERT( |
| (container.getLockingPolicy().getMode() != |
| LockingPolicy.MODE_RECORD), |
| "Locking policy requires row locking."); |
| } |
| |
| if (scan_position.current_leaf.page.isDeletedAtSlot( |
| scan_position.current_slot)) |
| { |
| ret_val = false; |
| } |
| else |
| { |
| scan_position.current_leaf.page.deleteAtSlot( |
| scan_position.current_slot, true, this.btree_undo); |
| ret_val = true; |
| } |
| |
| // See if we just deleted the last row on the page, in a btree a |
| // page with all rows still has 1 left - the control row. |
| // Do not reclaim the root page of the btree if there are no |
| // children since we were doing too many post commit actions in a |
| // benchmark which does an insert/commit/delete/commit operations |
| // in a single user system. Now with this change the work will |
| // move to the user thread which does the insert and finds no space |
| // on the root page. In that case it will try a split, which |
| // automatically first checks if there is committed deleted space |
| // that can be reclaimed. |
| |
| if (scan_position.current_leaf.page.nonDeletedRecordCount() == 1 && |
| !(scan_position.current_leaf.getIsRoot() && |
| scan_position.current_leaf.getLevel() == 0)) |
| { |
| this.getXactMgr().addPostCommitWork(new BTreePostCommit( |
| this.getXactMgr().getAccessManager(), |
| this.getConglomerate(), |
| scan_position.current_leaf.page.getPageNumber())); |
| } |
| } |
| finally |
| { |
| if (scan_position.current_leaf != null) |
| { |
| // release latch on page |
| savePositionAndReleasePage(); |
| } |
| } |
| |
| return(ret_val); |
| } |
| |
| /** |
| * A call to allow client to indicate that current row does not qualify. |
| * <p> |
| * 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. |
| * <p> |
| * 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). |
| * <p> |
| * This call should only be made while the scan is positioned on a current |
| * valid row. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| public void didNotQualify() |
| 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. |
| * <p> |
| * 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. |
| * <p> |
| * Note that for comglomerates which don't support update, like btree's, |
| * there is no need to recheck the qualifiers. |
| * <p> |
| * The results of a fetch() performed on a scan positioned on |
| * a deleted row are undefined. |
| * <p> |
| * @exception StandardException Standard exception policy. |
| **/ |
| public boolean doesCurrentPositionQualify() |
| throws StandardException |
| { |
| if (scan_state != SCAN_INPROGRESS) |
| throw StandardException.newException( |
| SQLState.AM_SCAN_NOT_POSITIONED); |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT(this.container != null, |
| "BTreeScan.doesCurrentPositionQualify() called on a closed scan."); |
| } |
| |
| try |
| { |
| // Get current page of scan, with latch |
| if (!reposition(scan_position, false)) |
| { |
| // TODO - write unit test to get here, language always calls |
| // isCurrentPositionDeleted() right before calling this, so |
| // hard to write .sql test to exercise this. |
| |
| // if reposition fails it means the position of the scan |
| // has been purged from the table - for example if this is |
| // a uncommitted read scan and somehow the row was purged |
| // since the last positioning. |
| |
| return(false); |
| } |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT( |
| scan_position.current_leaf.page.fetchNumFieldsAtSlot( |
| scan_position.current_slot) > 1); |
| } |
| |
| // Since btree row don't get updated, the only way a current |
| // position may not qualify is if it got deleted. |
| return( |
| !scan_position.current_leaf.page.isDeletedAtSlot( |
| scan_position.current_slot)); |
| } |
| finally |
| { |
| |
| if (scan_position.current_leaf != null) |
| { |
| // release latch on page. |
| savePositionAndReleasePage(); |
| } |
| } |
| } |
| |
| |
| /** |
| * Fetch the row at the current position of the Scan. |
| * |
| * @param row The row into which the value of the current |
| * position in the scan is to be stored. |
| * @param qualify indicates whether the qualifiers should be applied. |
| * |
| * @exception StandardException Standard exception policy. |
| */ |
| private void fetch(DataValueDescriptor[] row, boolean qualify) |
| throws StandardException |
| { |
| if (scan_state != SCAN_INPROGRESS) |
| throw StandardException.newException( |
| SQLState.AM_SCAN_NOT_POSITIONED); |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT(this.container != null, |
| "BTreeScan.fetch() called on a closed scan."); |
| } |
| |
| try |
| { |
| // Get current page of scan, with latch |
| if (!reposition(scan_position, false)) |
| { |
| // TODO - write unit test to get here, language always calls |
| // isCurrentPositionDeleted() right before calling this, so |
| // hard to write .sql test to exercise this. |
| |
| throw StandardException.newException( |
| SQLState.AM_RECORD_NOT_FOUND, |
| err_containerid, |
| scan_position.current_rh.getPageNumber(), |
| scan_position.current_rh.getId()); |
| } |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT( |
| scan_position.current_leaf.page.fetchNumFieldsAtSlot( |
| scan_position.current_slot) > 1); |
| } |
| |
| scan_position.current_rh = |
| scan_position.current_leaf.page.fetchFromSlot( |
| (RecordHandle) null, |
| scan_position.current_slot, row, |
| qualify ? init_fetchDesc : null, |
| true); |
| |
| // The possibility is that the row at the current position |
| // has been marked as deleted (it cannot have been purged |
| // since the scan maintains a lock on the row, and purges |
| // are always done from system transactions). I'm not sure |
| // what the desired behavior is in this case. For now, |
| // just return null. |
| |
| // RESOLVE (mikem) - what should be done here? |
| if (scan_position.current_leaf.page.isDeletedAtSlot( |
| scan_position.current_slot)) |
| { |
| if (SanityManager.DEBUG) |
| SanityManager.ASSERT(false, "positioned on deleted row"); |
| } |
| } |
| finally |
| { |
| if (scan_position.current_leaf != null) |
| { |
| // release latch on page. |
| savePositionAndReleasePage(); |
| } |
| } |
| |
| return; |
| } |
| |
| /** |
| * @see org.apache.derby.iapi.store.access.ScanController#isHeldAfterCommit |
| */ |
| public boolean isHeldAfterCommit() throws StandardException |
| { |
| return (scan_state == SCAN_HOLD_INIT || |
| scan_state == SCAN_HOLD_INPROGRESS); |
| } |
| |
| /** |
| Fetch the row at the current position of the Scan. |
| @see ScanController#fetch |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public void fetch(DataValueDescriptor[] row) |
| throws StandardException |
| { |
| fetch(row, true); |
| } |
| |
| /** |
| * Fetch the row at the current position of the Scan without applying the |
| * qualifiers. |
| * @see ScanController#fetchWithoutQualify |
| * |
| * @exception StandardException Standard exception policy. |
| */ |
| public void fetchWithoutQualify(DataValueDescriptor[] row) |
| throws StandardException |
| { |
| fetch(row, false); |
| } |
| |
| /** |
| * Return ScanInfo object which describes performance of scan. |
| * <p> |
| * Return ScanInfo object which contains information about the current |
| * scan. |
| * <p> |
| * |
| * @see ScanInfo |
| * |
| * @return The ScanInfo object which contains info about current scan. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| public ScanInfo getScanInfo() |
| throws StandardException |
| { |
| return(new BTreeScanInfo(this)); |
| } |
| |
| /** |
| 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. |
| **/ |
| public boolean isCurrentPositionDeleted() |
| throws StandardException |
| { |
| boolean ret_val; |
| |
| if (scan_state != SCAN_INPROGRESS) |
| throw StandardException.newException( |
| SQLState.AM_SCAN_NOT_POSITIONED); |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT(this.container != null, |
| "BTreeScan.isCurrentPositionDeleted() called on closed scan."); |
| } |
| try |
| { |
| // Get current page of scan, with latch |
| |
| if (reposition(scan_position, false)) |
| { |
| |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT( |
| scan_position.current_leaf.page.fetchNumFieldsAtSlot( |
| scan_position.current_slot) > 1); |
| } |
| |
| ret_val = |
| scan_position.current_leaf.page.isDeletedAtSlot( |
| scan_position.current_slot); |
| } |
| else |
| { |
| ret_val = false; |
| } |
| } |
| finally |
| { |
| if (scan_position.current_leaf != null) |
| { |
| // release latch on page. |
| savePositionAndReleasePage(); |
| } |
| } |
| |
| return(ret_val); |
| } |
| |
| /** |
| * Return whether this is a keyed conglomerate. |
| * <p> |
| * |
| * @return whether this is a keyed conglomerate. |
| **/ |
| public boolean isKeyed() |
| { |
| return(true); |
| } |
| |
| /** |
| * @see ScanController#positionAtRowLocation |
| * |
| * Not implemented for this class |
| */ |
| public boolean positionAtRowLocation (RowLocation rLoc) |
| throws StandardException |
| { |
| throw StandardException.newException( |
| SQLState.BTREE_UNIMPLEMENTED_FEATURE); |
| } |
| |
| /** |
| Move to the next position in the scan. |
| @see ScanController#next |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public boolean next() |
| throws StandardException |
| { |
| // Turn this call into a group fetch of a 1 element group. |
| fetchNext_one_slot_array[0] = runtime_mem.get_scratch_row(getRawTran()); |
| boolean ret_val = |
| fetchRows( |
| scan_position, |
| fetchNext_one_slot_array, |
| (RowLocation[]) null, |
| (BackingStoreHashtable) null, |
| 1, |
| (int[]) null) == 1; |
| |
| |
| return(ret_val); |
| } |
| |
| /** |
| 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. |
| |
| @param row The template row into which the value |
| of the next position in the scan is to be stored. |
| |
| @return True if there is a next position in the scan, |
| false if there isn't. |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public boolean fetchNext(DataValueDescriptor[] row) |
| throws StandardException |
| { |
| boolean ret_val; |
| |
| // Turn this call into a group fetch of a 1 element group. |
| fetchNext_one_slot_array[0] = row; |
| ret_val = |
| fetchRows( |
| scan_position, |
| fetchNext_one_slot_array, |
| (RowLocation[]) null, |
| (BackingStoreHashtable) null, |
| 1, |
| (int[]) null) == 1; |
| |
| return(ret_val); |
| } |
| |
| /** |
| * Fetch the next N rows from the table. |
| * <p> |
| * 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. |
| * <p> |
| * 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). |
| * <p> |
| * 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. |
| * <p> |
| * Qualifiers, start and stop positioning of the openscan are applied |
| * just as in a normal scan. |
| * <p> |
| * 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. |
| * <p> |
| * 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] |
| * } |
| * |
| * <p> |
| * |
| * 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(). |
| * |
| * @return 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 |
| * |
| * @param 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. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| public int fetchNextGroup( |
| DataValueDescriptor[][] row_array, |
| RowLocation[] rowloc_array) |
| throws StandardException |
| { |
| return( |
| fetchRows( |
| scan_position, |
| row_array, |
| rowloc_array, |
| (BackingStoreHashtable) null, |
| row_array.length, |
| (int[]) null)); |
| } |
| |
| public int fetchNextGroup( |
| DataValueDescriptor[][] row_array, |
| RowLocation[] old_rowloc_array, |
| RowLocation[] new_rowloc_array) |
| throws StandardException |
| { |
| // This interface is currently only used to move rows around in |
| // a heap table, unused in btree's -- so not implemented. |
| |
| throw StandardException.newException( |
| SQLState.BTREE_UNIMPLEMENTED_FEATURE); |
| } |
| |
| /** |
| * Insert all rows that qualify for the current scan into the input |
| * Hash table. |
| * <p> |
| * 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. |
| * <p> |
| * 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. |
| * <p> |
| * 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); |
| * } |
| * } |
| * <p> |
| * 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? |
| * <p> |
| * 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. |
| * <p> |
| * 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." |
| * <p> |
| * 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. |
| * <p> |
| * |
| * 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. |
| * <p> |
| * 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. |
| * |
| * |
| * @param max_rowcnt The maximum number of rows to insert into the |
| * Hash table. Pass in -1 if there is no maximum. |
| * @param 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). |
| * @param hash_table The java HashTable to load into. |
| * |
| * @exception StandardException Standard exception policy. |
| **/ |
| public void fetchSet( |
| long max_rowcnt, |
| int[] key_column_numbers, |
| BackingStoreHashtable hash_table) |
| throws StandardException |
| { |
| // System.out.println("fetchSet"); |
| |
| fetchRows( |
| scan_position, |
| (DataValueDescriptor[][]) null, |
| (RowLocation[]) null, |
| (BackingStoreHashtable) hash_table, |
| max_rowcnt, |
| key_column_numbers); |
| |
| return; |
| } |
| |
| |
| /** |
| 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. |
| |
| @param 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. |
| |
| @param 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. |
| |
| @param 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. |
| |
| @param 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. |
| |
| @param 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. |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public final void reopenScan( |
| DataValueDescriptor[] startKeyValue, |
| int startSearchOperator, |
| Qualifier qualifier[][], |
| DataValueDescriptor[] stopKeyValue, |
| int stopSearchOperator) |
| throws StandardException |
| { |
| if (SanityManager.DEBUG) |
| { |
| if (!init_hold) |
| SanityManager.ASSERT(this.container != null, |
| "BTreeScan.reopenScan() called on non-held closed scan."); |
| |
| // should only be called by clients outside of store, so should |
| // not be possible for a latch to held. |
| SanityManager.ASSERT(scan_position.current_leaf == null); |
| } |
| |
| // call unlockScanRecordAfterRead() before setting the scan back |
| // to init state, so that we release the last lock if necessary (ie. |
| // for read committed). |
| // |
| |
| if (scan_position.current_rh != null) |
| { |
| this.getLockingPolicy().unlockScanRecordAfterRead( |
| scan_position, init_forUpdate); |
| } |
| |
| scan_position.current_slot = Page.INVALID_SLOT_NUMBER; |
| scan_position.current_rh = null; |
| scan_position.current_positionKey = null; |
| |
| initScanParams( |
| startKeyValue, startSearchOperator, |
| qualifier, stopKeyValue, stopSearchOperator); |
| |
| if (!init_hold) |
| this.scan_state = SCAN_INIT; |
| else |
| this.scan_state = |
| (this.container != null ? SCAN_INIT : SCAN_HOLD_INIT); |
| } |
| |
| /** |
| 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. |
| <p> |
| The statistics gathered by the scan are not reset to 0 by a reopenScan(), |
| rather they continue to accumulate. |
| <p> |
| 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. |
| |
| @param 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. |
| |
| @param 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. |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public void reopenScanByRowLocation( |
| RowLocation startRowLocation, |
| Qualifier qualifier[][]) |
| throws StandardException |
| { |
| throw StandardException.newException( |
| SQLState.BTREE_UNIMPLEMENTED_FEATURE); |
| } |
| |
| /* |
| ** Methods of ScanController, which are not supported by btree. |
| */ |
| |
| /** |
| Fetch the location of the current position in the scan. |
| @see ScanController#fetchLocation |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public void fetchLocation(RowLocation templateLocation) |
| throws StandardException |
| { |
| throw StandardException.newException( |
| SQLState.BTREE_UNIMPLEMENTED_FEATURE); |
| } |
| |
| /** |
| Return a row location object of the correct type to be |
| used in calls to fetchLocation. |
| @see org.apache.derby.iapi.store.access.GenericScanController#newRowLocationTemplate |
| |
| @exception StandardException Standard exception policy. |
| **/ |
| public RowLocation newRowLocationTemplate() |
| throws StandardException |
| { |
| throw StandardException.newException( |
| SQLState.BTREE_UNIMPLEMENTED_FEATURE); |
| } |
| |
| /** |
| Replace the entire row at the current position of the scan. |
| |
| Unimplemented interface by btree, will throw an exception. |
| |
| @see ScanController#replace |
| @exception StandardException Standard exception policy. |
| **/ |
| public boolean replace(DataValueDescriptor[] row, FormatableBitSet validColumns) |
| throws StandardException |
| { |
| throw StandardException.newException( |
| SQLState.BTREE_UNIMPLEMENTED_FEATURE); |
| } |
| |
| /* |
| ** Methods of ScanManager |
| */ |
| |
| |
| /** |
| Close the scan, a commit or abort is about to happen. |
| **/ |
| public boolean closeForEndTransaction(boolean closeHeldScan) |
| throws StandardException |
| { |
| if (!init_hold || closeHeldScan) |
| { |
| // Scan is closed, make sure no access to any state variables |
| positionAtDoneScan(scan_position); |
| |
| super.close(); |
| |
| // null out so that these object's can get GC'd earlier. |
| this.init_rawtran = null; |
| this.init_template = null; |
| this.init_startKeyValue = null; |
| this.init_qualifier = null; |
| this.init_stopKeyValue = null; |
| |
| this.getXactMgr().closeMe(this); |
| |
| return(true); |
| } |
| else |
| { |
| |
| if (this.scan_state == SCAN_INPROGRESS) |
| { |
| if (SanityManager.DEBUG) |
| { |
| SanityManager.ASSERT(scan_position != null); |
| SanityManager.ASSERT( |
| scan_position.current_positionKey != null, |
| "Position must be saved by key when tx ends"); |
| } |
| |
| // When the transaction ends, we release all the locks |
| // obtained in this scan, so the row we're positioned on is |
| // no longer locked. |
| scan_position.current_rh = null; |
| |
| this.scan_state = SCAN_HOLD_INPROGRESS; |
| } |
| else if (this.scan_state == SCAN_INIT) |
| { |
| this.scan_state = SCAN_HOLD_INIT; |
| } |
| |
| super.close(); |
| |
| return(false); |
| } |
| } |
| |
| /** |
| * Save the current scan position by key and release the latch on the leaf |
| * that's being scanned. This method should be called if the latch on a |
| * leaf needs to be released in the middle of the scan. The scan can |
| * later reposition to the saved position by calling {@code reposition()}. |
| * |
| * @param partialKey known parts of the key that should be saved, or |
| * {@code null} if the entire key is unknown and will have to be fetched |
| * from the page |
| * @param vcols an array which tells which columns of the partial key are |
| * valid (key columns that have 0 in this array are not valid, and their |
| * values must be fetched from the page), or {@code null} if all the |
| * columns are valid |
| * @throws StandardException if an error occurs while saving the position |
| * @see #reposition(BTreeRowPosition, boolean) |
| */ |
| void savePositionAndReleasePage(DataValueDescriptor[] partialKey, |
| int[] vcols) |
| throws StandardException { |
| |
| final Page page = scan_position.current_leaf.getPage(); |
| |
| if (SanityManager.DEBUG) { |
| SanityManager.ASSERT(page.isLatched(), "Page is not latched"); |
| SanityManager.ASSERT(scan_position.current_positionKey == null, |
| "Scan position already saved"); |
| |
| if (partialKey == null) { |
| SanityManager.ASSERT(vcols == null); |
| } |
| if (vcols != null) { |
| SanityManager.ASSERT(partialKey != null); |
| SanityManager.ASSERT(vcols.length <= partialKey.length); |
| } |
| } |
| |
| try { |
| DataValueDescriptor[] fullKey = scan_position.getKeyTemplate(); |
| |
| FetchDescriptor fetchDescriptor = null; |
| boolean haveAllColumns = false; |
| if (partialKey != null) { |
| int copiedCols = 0; |
| final int partialKeyLength = |
| (vcols == null) ? partialKey.length : vcols.length; |
| for (int i = 0; i < partialKeyLength; i++) { |
| if (vcols == null || vcols[i] != 0) { |
| fullKey[i].setValue(partialKey[i]); |
| copiedCols++; |
| } |
| } |
| if (copiedCols < fullKey.length) { |
| fetchDescriptor = |
| scan_position.getFetchDescriptorForSaveKey( |
| vcols, fullKey.length); |
| } else { |
| haveAllColumns = true; |
| } |
| } |
| |
| if (!haveAllColumns) { |
| RecordHandle rh = page.fetchFromSlot( |
| (RecordHandle) null, |
| scan_position.current_slot, |
| fullKey, |
| fetchDescriptor, |
| true); |
| |
| if (SanityManager.DEBUG) { |
| SanityManager.ASSERT(rh != null, "Row not found"); |
| } |
| } |
| |
| scan_position.current_positionKey = fullKey; |
| // Don't null out current_rh, we might be able to use it later if |
| // no rows are moved off the page. |
| //scan_position.current_rh = null; |
| scan_position.versionWhenSaved = page.getPageVersion(); |
| scan_position.current_slot = Page.INVALID_SLOT_NUMBER; |
| |
| } finally { |
| scan_position.current_leaf.release(); |
| scan_position.current_leaf = null; |
| } |
| } |
| |
| /** Shortcut for for savePositionAndReleasePage(null,null). */ |
| void savePositionAndReleasePage() throws StandardException { |
| savePositionAndReleasePage(null, null); |
| } |
| |
| public RecordHandle getCurrentRecordHandleForDebugging() |
| { |
| return(scan_position.current_rh); |
| } |
| |
| /* |
| ** Standard toString() method. Prints out current position in scan. |
| */ |
| public String toString() |
| { |
| if (SanityManager.DEBUG) |
| { |
| String string = |
| "\n\tbtree = " + this.getConglomerate() + |
| "\n\tscan direction = " + |
| (this instanceof BTreeForwardScan ? "forward" : |
| (this instanceof BTreeMaxScan ? "backward" : |
| "illegal")) + |
| "\n\t(scan_state:" + |
| (this.scan_state == SCAN_INIT ? "SCAN_INIT" : |
| this.scan_state == SCAN_INPROGRESS ? "SCAN_INPROGRESS" : |
| this.scan_state == SCAN_DONE ? "SCAN_DONE" : |
| this.scan_state == SCAN_HOLD_INIT ? "SCAN_HOLD_INIT" : |
| this.scan_state == SCAN_HOLD_INPROGRESS ? "SCAN_HOLD_INPROGRESS" : |
| "BAD_SCAN_STATE") + |
| "\n\trh:" + scan_position.current_rh + |
| "\n\tkey:" + scan_position.current_positionKey + ")" + |
| "\n\tinit_rawtran = " + init_rawtran + |
| "\n\tinit_hold = " + init_hold + |
| "\n\tinit_forUpdate = " + init_forUpdate + |
| "\n\tinit_useUpdateLocks = " + init_useUpdateLocks + |
| "\n\tinit_scanColumnList = " + init_scanColumnList + |
| "\n\tinit_scanColumnList.size() = "+ ( |
| (init_scanColumnList != null ? |
| init_scanColumnList.size() : 0)) + |
| "\n\tinit_template = " + |
| RowUtil.toString(init_template) + |
| "\n\tinit_startKeyValue = " + |
| RowUtil.toString(init_startKeyValue) + |
| "\n\tinit_startSearchOperator = " + |
| (init_startSearchOperator == ScanController.GE ? "GE" : |
| (init_startSearchOperator == ScanController.GT ? "GT" : |
| Integer.toString(init_startSearchOperator))) + |
| "\n\tinit_qualifier[] = " + init_qualifier + |
| "\n\tinit_stopKeyValue = " + |
| RowUtil.toString(init_stopKeyValue) + |
| "\n\tinit_stopSearchOperator = " + |
| (init_stopSearchOperator == ScanController.GE ? "GE" : |
| (init_stopSearchOperator == ScanController.GT ? "GT" : |
| Integer.toString(init_stopSearchOperator))) + |
| "\n\tstat_numpages_visited = " + |
| stat_numpages_visited + |
| "\n\tstat_numrows_visited = " + |
| stat_numrows_visited + |
| "\n\tstat_numrows_qualified = " + |
| stat_numrows_qualified + |
| "\n\tstat_numdeleted_rows_visited = " + |
| stat_numdeleted_rows_visited ; |
| |
| return(string); |
| } |
| else |
| { |
| return(null); |
| } |
| } |
| } |
