conglomeratecontroller.java

derby database source code.good for you.

/*

   Derby - Class org.apache.derby.iapi.store.access.ConglomerateController

   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.iapi.store.access;

import org.apache.derby.iapi.store.access.RowUtil;

import org.apache.derby.iapi.services.io.Storable;

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

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

import org.apache.derby.iapi.error.StandardException;
import org.apache.derby.iapi.services.io.FormatableBitSet;

import java.util.Properties;


/**

A conglomerate is an abstract storage structure (they
correspond to access methods).  The ConglomerateController interface
is the interface that access manager clients can use to manipulate
the contents of the underlying conglomerate.
<p>
Each conglomerate holds a set of rows.  Each row has a row location.
The conglomerate provides methods for:
<ul>
<li>
Inserting rows,
<li>
Fetching, deleting, and replacing entire rows by row location, and
<li>
fetching and updating individual columns of a row identified by row
location.
</ul>
<p>
Conglomerates do not provide any mechanism for associative access to
rows within the conglomerate; this type of access is provided by scans
via the ScanController interface.
<p>
Although all conglomerates have the same interface, they have different
implementations.  The implementation of a conglomerate determines some
of its user-visible semantics; for example whether the rows are ordered
or what the types of the rows' columns must be.  The implementation is
specified by an implementation id.  Currently there are two implementations,
"heap", and "btree".  The details of their behavior are specified in their
implementation documentation.  (Currently, only "heap" is implemented).
<p>
All conglomerate operations are subject to the transactional isolation
of the transaction they were opened from.  Transaction rollback will
close all conglomerates.  Transaction commit will close all non-held
conglomerates.
<p>
Scans are opened from a TransactionController.
<P>
A ConglomerateController can handle partial rows. Partial rows
are described in RowUtil.

@see TransactionController#openConglomerate
@see RowUtil
*/

public interface ConglomerateController extends ConglomPropertyQueryable
{
    public static final int ROWISDUPLICATE = 1;

    /**
     * Close the conglomerate controller.
     * <p>
     * Close the conglomerate controller.  Callers must not use
	 * the conglomerate controller after calling close.  It is
	 * strongly recommended that callers clear out the reference
	 * after closing, e.g., 
	 * <p>
	 * <blockquote><pre>
	 * ConglomerateController cc;
	 * cc.close;
	 * cc = null;
	 * </pre></blockquote>
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public void close()
        throws StandardException;

    /**
     * Close conglomerate controller as part of terminating a transaction.
     * <p>
     * Use this call to close the conglomerate controller resources as part of
     * committing or aborting a transaction.  The normal close() routine may 
     * do some cleanup that is either unnecessary, or not correct due to the 
     * unknown condition of the controller following a transaction ending error.
     * Use this call when closing all controllers as part of an abort of a 
     * transaction.
     * <p)
     * This call is meant to only be used internally by the Storage system,
     * clients of the storage system should use the simple close() interface.
     * <p>
     * RESOLVE (mikem) - move this call to ConglomerateManager so it is
     * obvious that non-access clients should not call this.
     *
     * @param closeHeldScan           If true, means to close controller even if
     *                                it has been opened to be kept opened 
     *                                across commit.  This is
     *                                used to close these controllers on abort.
     *
	 * @return boolean indicating that the close has resulted in a real close
     *                 of the controller.  A held scan will return false if 
     *                 called by closeForEndTransaction(false), otherwise it 
     *                 will return true.  A non-held scan will always return 
     *                 true.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    boolean closeForEndTransaction(boolean closeHeldScan)
		throws StandardException;

    /**
    Check consistency of a conglomerate.

    Checks the consistency of the data within a given conglomerate, does not
    check consistency external to the conglomerate (ie. does not check that 
    base table row pointed at by a secondary index actually exists).

    Raises a StandardException on first consistency problem. 
    
	@exception StandardException Standard exception policy.
    **/
    void checkConsistency()
		throws StandardException;

    /**
    Delete a row from the conglomerate.  
	@return Returns true if delete was successful, false if the record pointed
	at no longer represents a valid record.
	@exception StandardException Standard exception policy.
    **/
    boolean delete(RowLocation loc)
		throws StandardException;

    /**
     * Fetch the (partial) row at the given location.
     * <p>
     *
	 * @param loc             The "RowLocation" which describes the exact row
     *                        to fetch from the table.
	 * @param destRow         The row to read the data into.
	 * @param validColumns    A description of which columns to return from
     *                        row on the page into "destRow."  destRow
     *                        and validColumns work together to
     *                        describe the row to be returned by the fetch - 
     *                        see RowUtil for description of how these three 
     *                        parameters work together to describe a fetched 
     *                        "row".
     *
	 * @return Returns true if fetch was successful, false if the record 
     *         pointed at no longer represents a valid record.
     *
	 * @exception  StandardException  Standard exception policy.
     *
	 * @see RowUtil
     **/
    boolean fetch(
    RowLocation             loc, 
    DataValueDescriptor[]   destRow, 
    FormatableBitSet                 validColumns) 
		throws StandardException;

    /**
     * Fetch the (partial) row at the given location.
     * <p>
     *
	 * @param loc             The "RowLocation" which describes the exact row
     *                        to fetch from the table.
	 * @param destRow         The row to read the data into.
	 * @param validColumns    A description of which columns to return from
     *                        row on the page into "destRow."  destRow
     *                        and validColumns work together to
     *                        describe the row to be returned by the fetch - 
     *                        see RowUtil for description of how these three 
     *                        parameters work together to describe a fetched 
     *                        "row".
	 * @param waitForLock     If false, then the call will throw a lock timeout
     *                        exception immediately, if the lock can not be
     *                        granted without waiting.  If true call will 
     *                        act exactly as fetch() interface with no 
     *                        waitForLock parameter.
     *
	 * @return Returns true if fetch was successful, false if the record 
     *         pointed at no longer represents a valid record.
     *
	 * @exception  StandardException  Standard exception policy.
     *
	 * @see RowUtil
     **/
    boolean fetch(
    RowLocation loc, 
    DataValueDescriptor[]   destRow, 
    FormatableBitSet     validColumns,
    boolean     waitForLock) 
		throws StandardException;

    /**
     * Fetch the (partial) row at the given location.
     * <p>
     * RESOLVE - interface NOT SUPPORTED YET!!!!!
     *
	 * @param loc             The "RowLocation" which describes the exact row
     *                        to fetch from the table.
	 * @param destRow         The row to read the data into.
	 * @param validColumns    A description of which columns to return from
     *                        row on the page into "destRow."  destRow,