openbtree.java

derby database source code.good for you.

/*

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

   Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.

   Licensed 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.services.sanity.SanityManager;

import org.apache.derby.iapi.error.StandardException;

import org.apache.derby.iapi.reference.SQLState;

import org.apache.derby.iapi.store.access.conglomerate.Conglomerate;
import org.apache.derby.iapi.store.access.conglomerate.LogicalUndo;
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.ScanController;
import org.apache.derby.iapi.store.access.TransactionController;
import org.apache.derby.iapi.store.access.SpaceInfo;
import org.apache.derby.iapi.store.raw.ContainerHandle;
import org.apache.derby.iapi.store.raw.LockingPolicy;
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.OpenConglomerateScratchSpace;



/**

  An open b-tree contains fields and methods common to scans and controllers.
  <P>
  <B>Concurrency Notes<\B>
  <P>
  An instance of an open b-tree is owned by a single context.  The b-tree code
  assumes that the context ensures that only one thread at a time is using
  the open b-tree.  The open b-tree itself does not enforce or check this.

**/

public class OpenBTree 
{
	/*
	** Fields of OpenBTree
	*/

    /**
     * The following group of fields are all basic input parameters which are
     * provided by the calling code when doing any sort of operation requiring
     * an open conglomerate (openScan(), open(), openCostController(), ...).
     * These are just saved values from what was initially input.
     **/
    private BTree                           init_conglomerate;

    /**
    The TransactionManager that open'd this btree.  In the case of Internal
    transactions used by split this will be the internal transaction, and 
    init_open_user_scans will be the user transaction that began the internal
    transaction.
    **/
    private TransactionManager              init_xact_manager;

    private Transaction                     init_rawtran;

	/**
	The ContainerHandle mode the container is opened with.  Remember this so
	that if the BTree needs to do SMO with another transaction, it would open
	the container with the same mode.
	**/
    private int                             init_openmode;

    /**
    Table or page locking?
    **/
    protected int                           init_lock_level;

    private DynamicCompiledOpenConglomInfo  init_dynamic_info;
    private boolean                         init_hold;

    /**
    The Locking Policy to use for for access to this btree.
    **/
    private BTreeLockingPolicy              init_btree_locking_policy;

	
	/**
	The (open) container which contains the b-tree.
	**/
	protected ContainerHandle container;

    /**
    The conglomerate containerid for error reporting.
    **/
    protected long  err_containerid;

    /**
    In the case of splits, notify all scans in this transaction to save their
    current position by key, because the split may move the row they are 
    positioned on.  This is done by calling open_user_scans.saveScanPositions().
    Note that not all OpenBTree's will have a non-null open_user_scans.  For
    instance logical undo of btree operations will get a OpenBTree with a null
    open_user_scans, this is all right because this operation should never need
    to call saveScanPositions() (ie. it will never do a split).
    **/
    protected TransactionManager init_open_user_scans = null;


    protected LogicalUndo btree_undo = null;

    /**
     * scratch space used for stuff like templates, export rows, ...
     **/
    protected OpenConglomerateScratchSpace  runtime_mem;

    /**************************************************************************
     * Public Accessors of This class:
     **************************************************************************
     */
    public final TransactionManager getXactMgr()
    {
        return(init_xact_manager);
    }

    public final Transaction getRawTran()
    {
        return(init_rawtran);
    }
    public final int getLockLevel()
    {
        return(init_lock_level);
    }

    public final ContainerHandle getContainer()
    {
        return(container);
    }

    public final int getOpenMode()
    {
        return(init_openmode);
    }
    
    public final BTree getConglomerate()
    {
        return(init_conglomerate);
    }

    public final boolean getHold()
    {
        return(init_hold);
    }
    public final BTreeLockingPolicy getLockingPolicy()
    {
        return(init_btree_locking_policy);
    }
    public final void setLockingPolicy(BTreeLockingPolicy policy)
    {
        init_btree_locking_policy = policy;
    }


    public final boolean isClosed()
    {
        return(container == null);
    }

    public final OpenConglomerateScratchSpace getRuntimeMem()
    {
        return(runtime_mem);
    }

    /**************************************************************************
     * Public Methods of RowCountable class:
     **************************************************************************
     */

    /**
     * Get the total estimated number of rows in the container.
     * <p>
     * The number is a rough estimate and may be grossly off.  In general
     * the server will cache the row count and then occasionally write
     * the count unlogged to a backing store.  If the system happens to 
     * shutdown before the store gets a chance to update the row count it
     * may wander from reality.
     * <p>
     * This call is currently only supported on Heap conglomerates, it
     * will throw an exception if called on btree conglomerates.
     *
	 * @return The total estimated number of rows in the conglomerate.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public long getEstimatedRowCount()
		throws StandardException
    {
        if (container == null)
            reopen();

        // Don't return 0 rows (return 1 instead), as this often leads the 
        // optimizer to produce plans which don't use indexes because of the 0 
        // row edge case.
        //
        // Eventually the plan is recompiled when rows are added, but we
        // have seen multiple customer cases of deadlocks and timeouts 
        // because of these 0 row based plans.  
        long row_count = 
            this.container.getEstimatedRowCount(/* unused flag */ 0);

        return(row_count == 0 ? 1 : row_count);
    }

    /**
     * Set the total estimated number of rows in the container.
     * <p>
     * Often, after a scan, the client of RawStore has a much better estimate
     * of the number of rows in the container than what store has.  For 
     * instance if we implement some sort of update statistics command, or
     * just after a create index a complete scan will have been done of the
     * table.  In this case this interface allows the client to set the
     * estimated row count for the container, and store will use that number
     * for all future references.
     * <p>
     * This call is currently only supported on Heap conglomerates, it
     * will throw an exception if called on btree conglomerates.
     *
     * @param count the estimated number of rows in the container.
     *
	 * @return The total estimated number of rows in the conglomerate.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public void setEstimatedRowCount(long count)
		throws StandardException
    {
        if (container == null)
            reopen();

        this.container.setEstimatedRowCount(count, /* unused flag */ 0);
    }


    /**************************************************************************
     * Public Methods of ConglomerateController interface:
     **************************************************************************
     */

    /**
     * Check consistency of a btree.
     * <p>
     * Read in root and check consistency of entire tree.  Currently raises
     * sanity check errors.
     * <p>
     * RESOLVE (mikem) if this is to be supported in non-sanity servers what 
     * should it do?
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public void checkConsistency()
		throws StandardException
    {
		ControlRow root = null;

        try
        {
            if (this.container == null)
            {
                throw(StandardException.newException(
                        SQLState.BTREE_IS_CLOSED, new Long(err_containerid)));
            }

            if (SanityManager.DEBUG)
                SanityManager.ASSERT(this.init_conglomerate.format_ids != null);

            root = ControlRow.Get(this, BTree.ROOTPAGEID);

            int actualpages = root.checkConsistency(this, null, true);

            // RESOLVE (mikem) - anything useful to assert about number of pages
            // in the tree?
        }
        finally
        {
            if (root != null)
                root.release();
        }
    }

    /**************************************************************************
     * Public Methods of ScanController interface:
     **************************************************************************
     */

    /**
     * is the open btree table locked?
     **/
    public boolean isTableLocked()
    {
        return(init_lock_level == TransactionController.MODE_TABLE);
    }


	/*
	** Methods of OpenBTree
	*/

	/**
	Initialize the open conglomerate.

    If container is null, open the container, otherwise use the container
    passed in.

    @exception StandardException standard exception policy.
	**/
    /**
     * Initialize the open conglomerate.
     * <p>
     * If container is null, open the container, otherwise use the container
     * passed in.  The container is always opened with no locking, it is up
     * to the caller to make the appropriate container locking call.
     * <p>
     *
	 * @return The identifier to be used to open the conglomerate later.
     *
     * @param open_user_scans The user transaction which opened this btree.
     * @param xact_manager    The current transaction, usually the same as
     *                        "open_user_scans", but in the case of split it
     *                        is the internal xact nested below the user xact.
     * @param input_container The open container holding the index, if it is
     *                        already open, else null which will mean this
     *                        routine will open it.
     * @param rawtran         The current raw store transaction.
     * @param open_mode       The opening mode for the ContainerHandle.
     * @param conglomerate    Readonly description of the conglomerate.
     * @param undo            Logical undo object to associate with all updates