page.java

来自「derby database source code.good for you.」· Java 代码 · 共 1,220 行 · 第 1/4 页

/*

   Derby - Class org.apache.derby.iapi.store.raw.Page

   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.raw;

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

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

import org.apache.derby.iapi.store.access.conglomerate.LogicalUndo;

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

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


/**
	A Page contains an ordered set of records which are the stored form of rows.
	A record is a stream of bytes created from a row array. The record
	contains one or more fields, fields have a one to one correlation with
	the DataValueDescriptor's contained within a row array.
  <P>
	A Page represents <B>exclusive</B> access to a data page within a container.
	Exclusive access is released by calling the unlatch() method, once that 
    occurs the caller must no longer use the Page reference.
	<P>
	Several of the methods in Page take a RecordHandle as an argument. 
    RecordHandles are obtained from a Page, while holding exclusive access of 
    Page or a from a previous exclusive access of a Page representing the same 
    data page.
	All RecordHandle's used as arguments to methods (with the exception of 
    recordExists()) must be valid for the current state of the page. If they 
    are not valid then the method will throw an exception. A caller can ensure 
    that a record handle is valid by:
	<UL>
	<LI> Obtaining the handle during this exclusive access of this page
	<LI> Checking the record still exists with the method recordExists()
	<LI> Not using a handle after a delete().
	</UL>
	<P>
	Several of the methods in Page take a slot number as an argument.  A slot 
    always correspond to a record, which may be deleted or undeleted.

    <BR>
	MT - Latched - In general every method requires the page to be latched.

  <P>
  <B>Latching</B>
  <P>
  All page methods which are not valid for a latched page throw an
  exception if the page is not latched.  [@exception clauses on all
  the methods should be updated to reflect this].

  <P>
  <B>Aux Objects</B>
  <BR>
  The page cache will manage a client object along with the page as long
  as it remains in cache.  This object is called the "aux object".  The 
  aux object is associated with the page with setAuxObject(), and can be
  retreived later with getAuxObject().  The aux object will remain valid
  as long as the page is latched, but callers cannot assume that an aux
  object will ever stick around once the page is unlatched.  However, the
  page manager promises to call pageBeingEvicted() once before clearing
  the aux reference from the page.

	@see Object
	@see ContainerHandle
	@see RecordHandle
	@see AuxObject
*/

public interface Page  
{

    /**************************************************************************
     * Constants of the class
     **************************************************************************
     */

    /**
     * The slot number of the first slot.  This is guaranteed to be zero.
     **/
	public static final int FIRST_SLOT_NUMBER   = 0;
	
    /**
     * A slot number guaranteed to be invalid.
     **/
	public static final int INVALID_SLOT_NUMBER = -1;
	
    /**
     * Return the page number of this page. 
     * <p>
     * Page numbers are unique within a container and start at 
     * ContainerHandle.FIRST_PAGE_NUMBER and increment by 1 regardless of the 
     * page size.
     * <p>
     *
     * <BR> MT - Latched
     *
     * @see ContainerHandle
     *
	 * @return The page number of this page.
     **/
	public long getPageNumber();

    /**************************************************************************
     * Public Methods of This class: record handle interface.
     *     the following interfaces to page use the record Id or record handle
     *     (rather than the slot interface).
     **************************************************************************
     */

    /**
     * Return an invalid record handle.
     * <p>
     *
	 * @return an invalid record handle.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
	public RecordHandle getInvalidRecordHandle();

    /**
     * Return a record handle for the given constant record id.
     * <p>
     * Return a record handle that doesn't represent a record but rather has 
     * a special meaning.  Used for special cases like creating a key 
     * specific to the page, but not specific to a row on the page.
     * <p>
     * See RecordHandle interface for a list of "special record handles."
     *
     * @see RecordHandle
     *
	 * @return The created record handle.
     *
     * @param recordHandleConstant the special recordId
     *
	 * @exception StandardException if input is not a special record identifier.
     **/
	public RecordHandle makeRecordHandle(int recordHandleConstant) 
		 throws	StandardException;

    /**
     * Get a record handle from a previously stored record id.
     * <p>
     * Get a record handle from a previously stored record identifier that was
     * obtained from a RecordHandle.
     * <p>
     * <BR> MT - Latched
     *
	 * @return A valid record handle or null if the record no longer exists.
     *
     * @param recordId previously stored recordId.
     *
     * @see RecordHandle#getId
     **/
	RecordHandle getRecordHandle(int recordId);

    /**
     * does the record still exist on the page?
     * <p>
     * If "ignoreDelete" is true and the record handle represents a record on 
     * the page (either marked deleted or not) return true.  If "ignoreDelete" 
     * is false return true if the record handle represents a record on the 
     * page and the record is not marked as deleted.  Return false otherwise.
     *
     * <BR> MT - Latched
     *
	 * @return boolean indicating if the record still exists on the page.
     *
     * @param handle        handle of the record to look for.
     * @param ignoreDelete  if true, then routine will return true even if the
     *                      row is marked deleted.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
	boolean recordExists(RecordHandle handle, boolean ignoreDelete) 
		 throws StandardException;

    /**
     * Fetch and lock a non-deleted record.
     * <p>
     * Lock and fetch a non-deleted record identified by a RecordHandle.  
     * Reads data from the page into row.
     * <P>
     * <B>Locking Policy</B>
     * <BR>
     * Calls the lockRecordForRead() method of the LockingPolicy object
     * passed to the openContainer() call before the record is accessed.
     * <BR>
     * The page latch may be released and re-latched within this method.
     * This will occur if the record lock has to be waited for.
     *
     * @param handle        Handle to record.
     * @param row           Row to be filled in with data from the record.
     * @param validColumns  a bit map of which columns in the row is to be 
     *                      fetched.  ValidColumns will not be changed by 
     *                      RawStore.
     * @param forUpdate     true if the intention is to update this record, 
     *                      false otherwise.
     *
     * @return A handle to the record, null if the record has been deleted.
     *
     * @exception StandardException	Standard Cloudscape error policy, 
     *                              a statemente level exception is thrown if
     *                              the record handle does not match a record 
     *                              on the page.
     *
     * @see Page#delete
     * @see LockingPolicy
     **/
	RecordHandle fetch(
    RecordHandle        handle, 
    Object[]            row, 
    FormatableBitSet    validColumns, 
    boolean             forUpdate)
		throws StandardException;

    /**
     * Is it likely that an insert will fit on this page?
     * <p>
     * Return true if there is a good chance an insert will fit on this page, 
     * false otherwise.  If this returns true then an insert may still fail by 
     * throwing an exception or by returning null, see insertAtSlot for details.
     * It is very probable that this call is much faster than the version that 
     * takes a row. In situations where it is expected that the 
     * majority of times a row will fit on a page this method should be used 
     * and the null return handled from insert/insertAtSlot.
     *
     * <BR>
     * MT - latched
     *
	 * @return true if it is likely an insert will fit on the page.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
	boolean spaceForInsert() 
        throws StandardException;

    /**
     * will insert of this row fit on this page?
     * <p>
     * Return true if this record is guaranteed to be inserted successfully 
     * using insert() or insertAtSlot(). This guarantee is only valid if the 
     * following conditions are fulfilled before an insert is called with t
     * his row.
     * <UL>
     * <LI> The page is not unlatched
     * <LI> The page is not modified in any way, ie. no updates or other inserts
     * <LI> The row is not modified in such a way that would change its 
     *      storage size
     * </UL>
     *
     * <BR>
     * MT - latched
     *
	 * @return true if insert of this row will fit on this page.
     *
     * @param row                   The row to check for insert.
     * @param validColumns          bit map to interpret valid columns in row.
     * @param overflowThreshold     The percentage of the page to use for the
     *                              insert.  100 means use 100% of the page,
     *                              50 means use 50% of page (ie. make sure
     *                              2 rows fit per page).
     *
	 * @exception  StandardException  Standard exception policy.
     **/
	boolean spaceForInsert(
    Object[]            row, 
    FormatableBitSet    validColumns, 
    int                 overflowThreshold) 
        throws StandardException;

    /**
     * Insert a record anywhere on the page.
     * <P>
     *
     * <B>Locking Policy</B>
     * <BR>
     * Calls the lockRecordForWrite() method of the LockingPolicy object
     * passed to the openContainer() call before the record is inserted.
     * <BR>
     * MT - latched
     *
     * @param row           The row version of the data
     * @param validColumns  a bit map of which columns in the row is valid.  
     *                      ValidColumns will not be changed by RawStore.
     * @param insertFlag    see values for insertFlag below.