/*

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

   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.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.shared.common.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,
     *                        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 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.  
     *                        Qualifiers can only reference columns which are 
     *                        included in the scanColumnList.  The column id 
     *                        that a qualifier returns in the column id the 
     *                        table, not the column id in the partial row being
     *                        returned.  See openScan() for description of how 
     *                        qualifiers are applied.
     *
	 * @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, 
    Qualifier[][]           qualifier)
		throws StandardException;
    */

	/**
    Insert a row into the conglomerate.

    @param row The row to insert into the conglomerate.  The stored
	representations of the row's columns are copied into a new row
	somewhere in the conglomerate.

	@return Returns 0 if insert succeeded.  Returns 
    ConglomerateController.ROWISDUPLICATE if conglomerate supports uniqueness
    checks and has been created to disallow duplicates, and the row inserted
    had key columns which were duplicate of a row already in the table.  Other
    insert failures will raise StandardException's.

	@exception StandardException Standard exception policy.
	@see RowUtil
    **/
	int insert(DataValueDescriptor[]    row) 
		throws StandardException;

    /**
     * insert row and fetch it's row location in one operation.
     * <p>
     * Insert a row into the conglomerate, and store its location in 
     * the provided destination row location.  The row location must be of the
     * correct type for this conglomerate (a new row location of the correct 
     * type can be obtained from newRowLocationTemplate()).
     *
     * @param row           The row to insert into the conglomerate.  The 
     *                      stored representations of the row's columns are 
     *                      copied into a new row somewhere in the conglomerate.
     *
     * @param destRowLocation The rowlocation to read the inserted row location
     *                      into.
     *
	 * @exception  StandardException  Standard exception policy.
     *
	 * @see RowUtil
     **/
	void insertAndFetchLocation(
    DataValueDescriptor[]   row, 
    RowLocation             destRowLocation)
		throws StandardException;

    /**
	Return whether this is a keyed conglomerate.
	**/
	boolean isKeyed();


    public static final int LOCK_READ         = (0x00000000);
    public static final int LOCK_UPD          = (0x00000001);
    public static final int LOCK_INS          = (0x00000002);
    public static final int LOCK_INS_PREVKEY  = (0x00000004);
    public static final int LOCK_UPDATE_LOCKS = (0x00000008);

    /**
     * Lock the given row location.
     * <p>
     * Should only be called by access.
     * <p>
     * This call can be made on a ConglomerateController that was opened
     * for locking only.
     * <p>
     * RESOLVE (mikem) - move this call to ConglomerateManager so it is
     * obvious that non-access clients should not call this.
     *
	 * @return true if lock was granted, only can be false if wait was false.
     *
	 * @param loc           The "RowLocation" of the exact row to lock.
     * @param lock_oper     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]
     *                      (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for 
     *                          update, will upgrade lock later if actual update
     *                          is take place]
     * @param wait          Should the lock call wait to be granted?
     * @param lock_duration If set to TransactionManager.LOCK_INSTANT_DURATION,
     *                      then lock will be released immediately after being
     *                      granted.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    boolean lockRow(
    RowLocation     loc,
    int             lock_oper,
    boolean         wait,
    int             lock_duration)
        throws StandardException;

    /**
     * Lock the given record id/page num pair.
     * <p>
     * Should only be called by access, to lock "special" locks formed from
     * the Recordhandle.* reserved constants for page specific locks.
     * <p>
     * This call can be made on a ConglomerateController that was opened
     * for locking only.
     * <p>
     * RESOLVE (mikem) - move this call to ConglomerateManager so it is
     * obvious that non-access clients should not call this.
     *
	 * @return true if lock was granted, only can be false if wait was false.
     *
     * @param page_num      page number of record to lock.
     * @param record_id     record id of record to lock.
     * @param lock_oper     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]
     *                      (LOCK_UPD | LOCK_UPDATE_LOCKS) [lock scan for 
     *                          update, will upgrade lock later if actual update
     *                          is take place]
     * @param wait          Should the lock call wait to be granted?
     * @param lock_duration If set to TransactionManager.LOCK_INSTANT_DURATION,
     *                      then lock will be released immediately after being
     *                      granted.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    boolean lockRow(
    long            page_num,
    int             record_id,
    int             lock_oper,
    boolean         wait,
    int             lock_duration)
        throws StandardException;

    /**
     * UnLock the given row location.
     * <p>
     * Should only be called by access.
     * <p>
     * This call can be made on a ConglomerateController that was opened
     * for locking only.
     * <p>
     * RESOLVE (mikem) - move this call to ConglomerateManager so it is
     * obvious that non-access clients should not call this.
     *
	 * @param loc           The "RowLocation" which describes the row to unlock.
     * @param forUpdate     Row was locked for read or update.
     * @param row_qualified Row was qualified and returned to the user.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    public void unlockRowAfterRead(
    RowLocation     loc,
    boolean         forUpdate,
    boolean         row_qualified)
        throws StandardException;

	/**
	Return a row location object of the correct type to be
	used in calls to insertAndFetchLocation.
	@exception StandardException Standard exception policy.
	**/
	RowLocation newRowLocationTemplate()
		throws StandardException;

	/**
    Replace the (partial) row at the given location.  
	@return true if update was successful, returns false if the update 
	fails because the record pointed at no longer represents a valid record.
	@exception StandardException Standard exception policy.
	@see RowUtil
    **/
    boolean replace(
    RowLocation             loc, 
    DataValueDescriptor[]   row, 
    FormatableBitSet                 validColumns)
		throws StandardException;

    /**
    Get information about space used by the conglomerate.
    **/
    SpaceInfo getSpaceInfo()
        throws StandardException;

    /**
     * Dump debugging output to error log.
     * <p>
     * Dump information about the conglomerate to error log.
     * This is only for debugging purposes, does nothing in a delivered 
     * system, currently.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
    void debugConglomerate()
		throws StandardException;
}
