/*

   Derby - Class org.apache.derby.impl.store.access.btree.BTreeLockingPolicy

   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.shared.common.error.StandardException; 

import org.apache.derby.iapi.store.raw.FetchDescriptor;

import org.apache.derby.iapi.types.DataValueDescriptor;
import org.apache.derby.iapi.types.RowLocation;

/**

The generic.BTree directory wants to know as little about locking as possible,
in order to make the code usuable by multiple implementations.  But the 
generic code will make calls to abstract lock calls implemented by concrete
btree implementations.  Concrete implementations like B2I understand locking,
and needs informatation specific to the implementation to make the lock calls.
<p>
This class is created and owned by the concrete application, but is passed
into and returned from the generic code when lock calls are made.
Concrete implementations which do not need lock calls can just pass a null
pointer where a BTreeLockingPolicy is requested.
<p>
There are 2 types of lock interfaces, lockScan*() and lockNonScan*().
<p>
The lockScan*() interfaces save the key for the current scan position before
giving up the latch on the page if they have to wait for a row lock. The
callers can reposition the scan using the saved key by calling
{@code BTreeScan.reposition()} if such a situation occurs. Then the latches
are reobtained, possibly on a different page if the current key has been moved
to another page in the meantime. Upon return from these interfaces
the row lock requested is guaranteed to have been obtained on the correct
key for the row requested.  These interfaces handle the special case of 
unique indexes where the RowLocation can change while waiting on the lock 
(see implementation for details), basically the lock is retryed after waiting
if the RowLocation has changed.
<p>
The lockNonScan*() interfaces do not save the current scan position. If these
routines return that the latch was released while waiting to obtain the
lock, then the caller must requeue the lock request after taking appropriate
action.  This action usually involves researching the tree to make sure 
that the correct key is locked with latches held. These interfaces
do not handle the special case of unique indexes where the RowLocation can 
change while waiting on the lock, as the row may disappear when the latch
is released to wait on the lock - thus it is necessary that the caller retry
the lock if the interface returns that the latch was released.


**/

public interface BTreeLockingPolicy
{
    /**************************************************************************
     * Abstract Protected lockScan*() locking methods of BTree:
     *     lockScanRow              - lock row
     *     unlockScanRecordAfterRead- unlock the scan record
     **************************************************************************
     */

    /**
     * Lock a btree row to determine if it is a committed deleted row.
     * <p>
     * Request an exclusive lock on the row located at the given slot, NOWAIT.
     * Return true if the lock is granted, otherwise false.
     * <p>
     *
     * @param open_btree        The conglomerate we are locking.
     * @param leaf              The leaf page with the row to lock.
     * @param template          Empty full template row, to read row into.
     * @param slot_no           The slot of row on "current_leaf" 
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    abstract public boolean lockScanCommittedDeletedRow(
    OpenBTree               open_btree,
    LeafControlRow          leaf,
    DataValueDescriptor[]   template,
    FetchDescriptor         lock_fetch_desc,
    int                     slot_no)
		throws StandardException;

    /**
     * Lock a row as part of doing the scan.
     * <p>
     * Lock the row at the given slot (or the previous row if slot is 0).
     * <p>
     * If this routine returns true all locks were acquired while maintaining
     * the latch on leaf.  If this routine returns false, locks may or may
     * not have been acquired, and the routine should be called again after
     * the client has researched the tree to reget the latch on the 
     * appropriate page.
     *
	 * @return Whether locks were acquired without releasing latch on leaf.
     *
     * @param open_btree        The open_btree to associate latches with - 
     *                          used if routine has to scan backward.
     * @param pos               Description of position of row to lock.
     * @param lock_template     A scratch area to use to read in rows.
     * @param previous_key_lock Is this a previous key lock call?
     * @param forUpdate         Is the scan for update or for read only.
     * @param lock_operation    For what operation are we requesting the lock, 
     *                          this should be one of the following 4 options:
     *                          LOCK_READ [read lock], 
     *                          (LOCK_INS | LOCK_UPD) [ lock for insert], 
     *                          (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for 
     *                          previous key to insert],
     *                          (LOCK_UPD) [lock for delete or replace]
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    abstract public boolean lockScanRow(
    OpenBTree               open_btree,
    BTreeRowPosition        pos,
    FetchDescriptor         lock_fetch_desc,
    DataValueDescriptor[]   lock_template,
    RowLocation             lock_row_loc,
    boolean                 previous_key_lock,
    boolean                 forUpdate,
    int                     lock_operation)
		throws StandardException;

    /**
     * Release read lock on a row.
     *
     * @param pos               Data structure that defines the current position
     *                          in the scan to be unlocked.
     *
     * @param forUpdate         Is the scan for update or for read only.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    abstract public void unlockScanRecordAfterRead(
    BTreeRowPosition        pos,
    boolean                 forUpdate)
		throws StandardException;


    /**************************************************************************
     * Abstract Protected lockNonScan*() locking methods of BTree:
     *
     *     lockNonScanPreviousRow   - lock the row previous to the current
     *     lockNonScanRow           - lock the input row
     *     lockNonScanRowOnPage     - lock the given row on the page.
     **************************************************************************
     */

    /**
     * Lock the previous key.
     * <p>
     * Given the current latched page and slot number, lock the logically
     * previous key in the table.  There are 3 cases:
     * <p>
     * slotnumber &gt; 1                       - just lock (slotnumber - 1)
     * (slotnumber == 1) &amp;&amp; (leftmost leaf) - this is the first key in the
     *                                        table, so lock a "magic" FIRSTKEY.
     * (slotnumber == 1) &amp;&amp; !(leftmost leaf)- traverse left in the tree looking
     *                                        for a previous key.
     * <p>
     * On successful return from this routine appropriate locking will have
     * been done.  All locks and latches are requested nowait, if any 
     * lock/latch cannot be granted this routine releases the current_leaf
     * latch and any latches it may have acquired and returns "false."
     * <p>
     * All extra latches that may have been gotten will have been released.
     * <p>
     * This routine will find the "previous row" to the (current_leaf,
     * current_slot), walking left in the tree as necessary, and first request
     * the lock on that row NOWAIT.  If that lock can not be granted,
     * then it will release all latches that it has acquired up to that point
     * including the latched current_leaf passed into the routine, and request 
     * the lock WAIT.  Once the lock has been granted the routine will return
     * and it is up to the caller to research the tree to find where the
     * current position may have ended up.  For instance in the case of insert
     * once the current latch is released, the correct page to do the insert
     * may no longer be where the original scan found it.
     * <p>
     * If routine returns true, lock was granted NOWAIT, current leaf
     * remains latched, and was never unlatched.  If routine returns false,
     * lock was granted WAIT, current leaf is not latched, row may have 
     * moved in the btree so caller must research to find the row.
     *
     *
     * @param current_leaf      Latched current leaf where "current" key is.
     * @param current_slot      The slot of row on "current_leaf" 
     * @param lock_template     Empty full template row, to read row into.
     * @param open_btree        The open_btree to associate latches with - 
     *                          used if routine has to scan backward.
     * @param lock_operation    For what operation are we requesting the lock, 
     *                          this should be one of the following 4 options:
     *                          LOCK_READ [read lock], 
     *                          (LOCK_INS | LOCK_UPD) [ lock for insert], 
     *                          (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for 
     *                          previous key to insert],
     *                          (LOCK_UPD) [lock for delete or replace]
     * @param lock_duration     For what duration should the lock be held,
     *                          if INSTANT_DURATION, then the routine will
     *                          guarantee that lock was acquired while holding
     *                          the latch, but then immediately release the
     *                          lock.  If COMMIT_DURATION or MANUAL_DURATION
     *                          then the lock be held when routine returns
     *                          successfully.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    abstract public boolean lockNonScanPreviousRow(
    LeafControlRow          current_leaf,
    int                     current_slot,
    FetchDescriptor         lock_fetch_desc,
    DataValueDescriptor[]   lock_template,
    RowLocation             lock_row_loc,
    OpenBTree               open_btree,
    int                     lock_operation,
    int                     lock_duration)
		throws StandardException;

    /**
     * Lock a btree row (row in memory).  Meant to be used if caller 
     * has the entire row objectified.
     * <p>
     * Lock a btree row, enforcing the standard lock/latch protocol.  
     * On return the row is locked.  Return status indicates if the lock
     * was waited for, which will mean a latch was dropped while waiting.
     * In general a false status means that the caller will either have 
     * to research the tree unless some protocol has been implemented that
     * insures that the row will not have moved while the latch was dropped.
     * <p>
     * This routine request a row lock NOWAIT on the in-memory row 
     * "current_row.".  If the lock is granted the routine will return true.
     * If the lock cannot be granted NOWAIT, then the routine will release
     * the latch on "current_leaf" (if current_leaf is non-null) and 
     * "aux_leaf" (if aux_leaf is non-null), and then it will request a WAIT 
     * lock on the row.  
     *
     *
     * @param btree             The conglomerate we are locking.
     * @param current_leaf      If non-null, this leaf is unlatched if the 
     *                          routine has to wait on the lock.
     * @param aux_leaf          If non-null, this leaf is unlatched if the 
     *                          routine has to wait on the lock.
     * @param current_row       In memory, objectified "current" row.
     * @param lock_operation    For what operation are we requesting the lock, 
     *                          this should be one of the following 4 options:
     *                          LOCK_READ [read lock], 
     *                          (LOCK_INS | LOCK_UPD) [ lock for insert], 
     *                          (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for 
     *                          previous key to insert],
     *                          (LOCK_UPD) [lock for delete or replace]
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    abstract public boolean lockNonScanRow(
    BTree                   btree,
    LeafControlRow          current_leaf,
    LeafControlRow          aux_leaf,
    DataValueDescriptor[]   current_row,
    int                     lock_operation)
		throws StandardException;

    /**
     * Lock the row at the given slot.
     * <p>
     * If this routine returns true all locks were acquired while maintaining
     * the latch on leaf.  If this routine returns false, locks may or may
     * not have been acquired, and the routine should be called again after
     * the client has researched the tree to reget the latch on the 
     * appropriate page.
     *
	 * @return Whether locks were acquired without releasing latch on leaf.
     *
     * @param leaf              The control row of the current leaf to lock.
     * @param slot              The slot position of the row to lock.
     * @param lock_template     A scratch area to use to read in rows.
     * @param lock_operation    For what operation are we requesting the lock, 
     *                          this should be one of the following 4 options:
     *                          LOCK_READ [read lock], 
     *                          (LOCK_INS | LOCK_UPD) [ lock for insert], 
     *                          (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for 
     *                          previous key to insert],
     *                          (LOCK_UPD) [lock for delete or replace]
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    abstract public boolean lockNonScanRowOnPage(
    LeafControlRow          leaf,
    int                     slot,
    FetchDescriptor         lock_fetch_desc,
    DataValueDescriptor[]   lock_template,
    RowLocation             lock_row_loc,
    int                     lock_operation)
		throws StandardException;
}
