page.java

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

     * 
     * @exception StandardException	Standard Cloudscape error policy
     * @exception StandardException The container was not opened in update mode.
     * @exception StandardException A statement level exception is thrown when 
     *                              trying to delete an already deleted record,
     *                              or undelete a not deleted record.
     *
     * @exception StandardException A statement level exception is thrown if 
     *                              the slot is not on the page.
     *
     * @see LockingPolicy
     * @see Page#delete
     * @see LogicalUndo
     * @see LogicalUndoable
     *
     **/
	public RecordHandle deleteAtSlot(
    int         slot, 
    boolean     delete, 
    LogicalUndo undo)
		 throws StandardException;


    /**
     * Purge the row(s) from page.
     * <p>
     * Purge the row(s) from page, get rid of the row(s) and slot(s) - 
     * <B>USE WITH CAUTION</B>, 
     * please see entire description of this operation before attempting to 
     * use this.
     *
     * Starting from the specified slot, n rows will be purged. That is, rows 
     * that occupies from slot to slot+n-1 will be purged from the page.
     *
     * <P>
     * <B>Locking Policy</B>
     * <P>
     * Calls the lockRecordForWrite() method of the LockingPolicy object passed
     * to the openContainer() call before the records are purged.
     * <P>
     *
     * <B>NOTE : CAVEAT</B><BR>
     * This operation will physically get rid of the row from the page, so if a
     * subsequent operation on this page uses a slot that has been purged, then
     * the undo of this operation will fail.  It is only safe to use this 
     * operation if the caller knows that it has exclusive access to the page 
     * for the duration of the transaction, i.e, effectively holding a page 
     * lock on the page
     * <P>
     * <B>NOTE</B><BR>
     * Outstanding handles to purged rows are no longer valid, accessing them 
     * will cause an exception to be thrown.
     *
     * <BR>
	 *<B>NOTE : Data Logging for Purges</B><BR>
	 * needDataLogged is used to specify whether data is required to be
	 * logged for purge operatios. Data Logging is required 
	 * Only if the row can be reused or required for key search if a purge is
	 * rolled back;(rollback can occur if the system crashes in the middle of
	 * purges or some unexpected error condiditions  rolled back.
	 * For example: 
	 * 1)Btree expects the data to be there if a purge is rolled back;
     *   needDataLogged=true
	 * 2)Heaps does not care if data exist because only operation that can occur
	 * on a row whose purge rolled back is purging again.(needDataLogged=false)
	 * 
     * MT - latched
     *
     *
     * @param slot	            the starting slot number
     * @param numpurges	        number of slots to purge.  If <= 0, 
     *                          just returns as a no-op.
	 * @param needDataLogged    if set to true data is logged for purges else 
     *                          only headers.
	 *
     * @exception StandardException	Standard Cloudscape error policy
     * @see LockingPolicy
     **/
	public void purgeAtSlot(
    int     slot, 
    int     numpurges,
	boolean needDataLogged) 
        throws StandardException;


    /**
     * move rows from one page to another, purging in the process.
     * <p>
     *
     * Move from this page slot[src_slot] to slot[src_slot+num_rows-1] to 
     * destPage slot[dest_slot] to slot[dest_slot + num_rows - 1], in that 
     * order. Both this page and destPage must be latched and from the same 
     * container with the same page and record format.
     *
     * <BR>Slot[src_slot] to slot[src_slot+numrows-1] will be purged from this 
     * page.  RecordId on the dest page will be brand new and not in any 
     * particular order or range.  RecordId of the purged rows in this page is 
     * never reused.  Deleted and undeleted rows are copied over just the same.
     *
     * Exception will be thrown if this page does not have all the rows in the 
     * moved over range.  
     *
     * <BR><B>RESOLVE: reserve space now not copied over because in btree, a
     * row never shrinks.  When this routine is called by heap or by some page
     * which will have shrunken row, then we need to add that </B>
     *
     * <BR>DestPage must have at least dest_slot row occupying slot[0] to
     * slot[dest_slot-1].  DestPage must have enough space to take the copied
     * over data.  Rows that occupied slot number > dest_slot will be moved up
     * the slot (I.e., slot[dest_slot] -> slot[dest_slot + num_rows]).  
     *
     * <BR>If this operation rolls back, this page (the src page) will get the
     * rows back and the dest page will purge the rows that were copied - this
     * is as if the rows were inserted into the dest page with 
     * INSERT_UNDO_WITH_PURGE.
     *
     * <P>
     * <B>Locking Policy</B>
     * <P>
     * Calls the lockRecordForWrite() method of the LockingPolicy object
     * passed to the openContainer() call before the rows are copied over and 
     * bore the records are purged.  I.e, for num_rows moved, there will be
     * 2*num_rows calls to lockRecordForWrite.
     * <P>
     *
     * <P><B>Use with caution</B>
     * <BR>As with a normal purge, no space is reserved on this page for 
     * rollback of the purge, so you must commit before inserting any rows 
     * onto this page - unless those inserts are INSERT_UNDO_WITH_PURGE.
     *
     * @param destPage the page to copy to
     * @param src_slot start copying from this slot
     * @param num_rows copy and purge this many rows from this page
     * @param dest_slot copying into this slot of destPage
     *
     * @exception StandardException Standard Cloudscape error policy
     **/
	public void copyAndPurge(
    Page    destPage, 
    int     src_slot, 
    int     num_rows, 
    int     dest_slot)
		 throws StandardException;

	/**
		Update the complete record identified by the slot.

		<P>
		<B>Locking Policy</B>
		<P>
		Calls the lockRecordForWrite() method of the LockingPolicy object
		passed to the openContainer() call before the record is undeleted.
		If record already deleted, an exception is thrown.

		<BR>
		It is guaranteed that the page latch is not released by this method

		@return a Handle to the updated record.
		@param slot is the slot number
		@param validColumns a bit map of which columns in the row is valid.
		ValidColumns will not be changed by RawStore.

		@exception StandardException	Standard Cloudscape error policy
		@exception StandardException The container was not opened in update mode.
		@exception StandardException if the slot is not on the page.

		@see Page#update
	*/
	RecordHandle updateAtSlot(
    int                     slot, 
    Object[]   row, 
    FormatableBitSet                 validColumns)
		throws StandardException;

	/*
		Page operations
	*/

	/**
		Unlatch me, the page is exclusivly latched by its current user until
		this method call is made.
		<BR>
		After using this method the caller must throw away the
		reference to the Page object, e.g.
		<PRE>
			ref.unlatch();
			ref = null;
		</PRE>
		<BR>
		The page will be released automatically at the close of the
		container if this method is not called explictly.

		<BR>
		MT - latched

	*/
	public void unlatch();



	/**
		Return the number of records on the page. The returned count includes rows that are deleted,
		i.e. it is the same as the number of slots on the page.

		<BR>
		MT - latched

		@exception StandardException	Standard Cloudscape error policy
	*/

	public int recordCount() throws StandardException;

	/**
		Return the number of records on this page that are <B> not </B> marked as deleted.
		
		 <BR>
		MT - latched

		@exception StandardException	Standard Cloudscape error policy
	*/

	public int nonDeletedRecordCount() throws StandardException;

	/**
	  Set the aux object for this page.
	  To clear the auxObject in the page, pass in a null AuxObject.
	  If the AuxObject has already been set, this method will
	  call auxObjectInvalidated() on the old aux objkect and replace it with aux.

		<BR>
		MT - latched

	  @see AuxObject
	**/
	public void setAuxObject(AuxObject aux);

	/**
	  Retrieve this page's aux object, returning null if there isn't one. The reference returned
	  must only be used while the page is latched, once unlatch is called the reference to the
	  aux object must be discarded.

		<BR> MT - latched

	  @see AuxObject
	**/
	public AuxObject getAuxObject();

	/**
		Returns true if the page is latched. Only intended to be used as a Sanity check. Callers must
		discard Page references once unlatch is called.

		<BR>
		MT - latched
	*/


	/*
	 * time stamp - for those implmentation that supports it
	 */

	/**
		Set the time stamp to what is on page at this instance.  No op if this
		page does not support time stamp.

		@exception StandardException Standard Cloudscape error policy.
	*/
	void setTimeStamp(PageTimeStamp ts) throws StandardException;


	/**
		Return a time stamp that can be used to identify the page of this
		specific instance.  For pages that don't support timestamp, returns
		null.
	*/
	PageTimeStamp currentTimeStamp();

	/**
		See if timeStamp for this page is the same as the current
		instance of the page.  Null timeStamp never equals the instance of the
		page.

		@param ts the time stamp gotten from an earlier call to this page's
		getTimeStamp
		@return true if timestamp is the same
		@exception StandardException Standard Cloudscape error policy.

		@see PageTimeStamp
	*/
	boolean equalTimeStamp(PageTimeStamp ts) throws StandardException;

	public boolean isLatched();

    public static final String DIAG_PAGE_SIZE        = "pageSize";
    public static final String DIAG_RESERVED_SPACE   = "reserveSpace";
    public static final String DIAG_MINIMUM_REC_SIZE = "minRecSize";
    public static final String DIAG_BYTES_FREE       = "bytesFree";
    public static final String DIAG_BYTES_RESERVED   = "bytesReserved";
    public static final String DIAG_NUMOVERFLOWED    = "numOverFlowed";
    public static final String DIAG_ROWSIZE          = "rowSize";
    public static final String DIAG_MINROWSIZE       = "minRowSize";
    public static final String DIAG_MAXROWSIZE       = "maxRowSize";
    public static final String DIAG_PAGEOVERHEAD     = "pageOverhead";
    public static final String DIAG_SLOTTABLE_SIZE   = "slotTableSize";
}