page.java

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

     *
     * @return A RecordHandle representing the new record.
     *
     * @exception StandardException	Standard Cloudscape error policy
     * @exception StandardException The container was not opened in update mode.
     * @exception StandardException Row cannot fit on the page or row is null.
     **/
	RecordHandle insert(
    Object[]            row, 
    FormatableBitSet    validColumns,
    byte                insertFlag, 
    int                 overflowThreshold)
		throws StandardException;

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

	*/
    /**
     * Update the record identified by the record handle.
     * <p>
     * Update the record, the new column values are found in row[] and if
     * validColumns is not-null, only use the columns indicated as valid in
     * the bit set.
     * <p>
     * <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        the record handle
     * @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.
     *
     * @return true if the record is updated.  
     *         False if it is not because the record is already deleted.
     *
     * @exception StandardException	Standard Cloudscape error policy
     * @exception StandardException The container was not opened in update mode.
     * @exception StandardException If the record handle does not match 
     *                              a record on the page.
     *
     * @see Page#updateAtSlot
     *
	 * @exception  StandardException  Standard exception policy.
     **/
	boolean update(
    RecordHandle        handle, 
    Object[]            row, 
    FormatableBitSet                 validColumns)
		throws StandardException;

    /**
     * Mark the record identified by position as deleted.
     * <p>
     * Mark the record identified by position as deleted. The record may be 
     * undeleted sometime later using undelete() by any transaction that sees 
     * the record.
     * <p>
     * <B>Locking Policy</B>
     * <P>
     * Calls the lockRecordForWrite() method of the LockingPolicy object
     * passed to the openContainer() call before the record is deleted.
     *
     * <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    record Handle to record
     * @param undo      if logical undo may be necessary, a function pointer to
     *                  the access code where the logical undo logic resides.
     *                  Null if logical undo is not necessary.
     *
     * @return true if the record was updated.  
     *         False if it wasn't because it is already deleted.
     *
     * @exception StandardException	Standard Cloudscape error policy
     * @exception StandardException The container was not opened in update mode.
     * @exception StandardException If the record handle does not match 
     *                              a record on the page.
     *
     * @see Page#deleteAtSlot
     * @see LockingPolicy
     **/
	public boolean delete(
    RecordHandle    handle, 
    LogicalUndo     undo)
		throws StandardException;

    /**
     * Move record to a page toward the beginning of the file.
     * <p>
     * As part of compressing the table records need to be moved from the
     * end of the file toward the beginning of the file.  Only the 
     * contiguous set of free pages at the very end of the file can
     * be given back to the OS.  This call is used to purge the row from
     * the current page, insert it into a previous page, and return the
     * new row location 
     * Mark the record identified by position as deleted. The record may be 
     * undeleted sometime later using undelete() by any transaction that sees 
     * the record.
     * <p>
     * The interface is optimized to work on a number of rows at a time, 
     * optimally processing all rows on the page at once.  The call will 
     * process either all rows on the page, or the number of slots in the
     * input arrays - whichever is smaller.
     * <B>Locking Policy</B>
     * <P>
     * MUST be called with table locked, not locks are requested.  Because
     * it is called with table locks the call will go ahead and purge any
     * row which is marked deleted.  It will also use purge rather than
     * delete to remove the old row after it moves it to a new page.  This
     * is ok since the table lock insures that no other transaction will
     * use space on the table before this transaction commits.
     *
     * <BR>
     * A page latch on the new page will be requested and released.
     *
     * @param slot           Slot of row to move.
     * @param row            A template to read the current row into as part
     *                       of moving it.
     * @param old_handle     An array to be filled in by the call with the 
     *                       old handles of all rows moved.
     * @param new_handle     An array to be filled in by the call with the 
     *                       new handles of all rows moved.
     *
     * @return the number of rows processed.
     *
     * @exception StandardException	Standard Cloudscape error policy
     *
     * @see LockingPolicy
     **/
	public int moveRecordForCompressAtSlot(
    int             slot,
    Object[]        row,
    RecordHandle[]  old_handle,
    RecordHandle[]  new_handle)
		throws StandardException;

    /**
     * Fetch the number of fields in a record. 
     * <p>
     * <B>Locking Policy</B>
     * <P>
     * No locks are obtained.
     *
     * <BR>
     * MT - latched
     *
     * @param handle    record handle to deleted or non-deleted record
     *
     * @return the number of fields in the record
     *
     * @exception StandardException	Standard Cloudscape error policy, a 
     *                              statement level exception is thrown if the 
     *                              record handle does not match a record on 
     *                              the page.
     **/
	public int fetchNumFields(RecordHandle handle)
		 throws StandardException;

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


    /**
     * Get the slot number.
     * <p>
     * Get the slot number of a record on a latched page using its record 
     * handle.
     *
     * <P><B>Note</B>
     * The slot number is only good for as long as the page is latched.
     *
     * <BR>
     * MT - latched
     *
     * @param handle the record handle
     *
     * @return the slot number
     *
     * @exception StandardException	Standard Cloudscape error policy
     **/
    int getSlotNumber(RecordHandle handle) 
        throws StandardException;

    /**
     * Get the record handle of row at slot.
     * <p>
     * Get the record handle of a record on a latched page using its slot 
     * number.
     *
     * <BR>
     * MT - latched
     *
     * @param slot the slot number
     *
     * @return the record handle.
     *
     * @exception StandardException	Standard Cloudscape error policy
     **/
	RecordHandle getRecordHandleAtSlot(int slot) 
        throws StandardException;

    /**
     * Find slot for record with an id greater than the passed in identifier.
     * <p>
     * Find the slot for the first record on the page with an id greater than 
     * the passed in identifier.
     *
     * <BR>
     * Returns the slot of the first record on the page with an id greater than
     * the one passed in.  Usefulness of this functionality depends on the 
     * client's use of the raw store interfaces.  If all "new" records are 
     * always inserted at the end of the page, and the raw store continues to
     * guarantee that all record id's will be allocated in increasing order on 
     * a given page (assuming a PAGE_REUSABLE_RECORD_ID container), then a page
     * is always sorted in record id order.  For instance current heap tables 
     * function this way.  If the client ever inserts at a particular slot 
     * number, rather than at the "end" then the record id's will not be sorted.
     * <BR>
     * In the case where all record id's are always sorted on a page, then this
     * routine can be used by scan's which "lose" their position because the 
     * row they have as a position was purged.  They can reposition their scan 
     * at the "next" row after the row that is now missing from the table.
     * <BR>
     * This method returns the record regardless of its deleted status.
     * <BR>
     * MT - latched
     * 
     * @param handle record handle to find the next higher id.
     *
     * @return  record id of the first record on the page with a record id 
     *          higher than the one passed in.  If no such record exists, 
     *          -1 is returned.
     *
	 * @exception  StandardException  Standard exception policy.
     **/
	int getNextSlotNumber(RecordHandle handle) 
        throws StandardException;

	/**
		Insert a record at the specified slot. 
		<P>
	 */
    /**
     * Insert a record at the specified slot. 
     * <p>
     * All records that occupy FIRST_SLOT_NUMBER to (slot - 1) are not moved. 
     * <BR>
     * All records that occupy slot to (recordCount() - 1) are moved up one 
     * slot. 
     * <BR>
     * The new record is inserted at the specified slot. <BR>
     * If slot == FIRST_SLOT_NUMBER, then the new record will be inserted at 
     * the first slot. <BR>
     * If slot == recordCount(), then the record is inserted in a new slot, no
     * records are moved. <BR>
     *
     * If slot is > recordCount() or if slot < FIRST_SLOT_NUMBER, an exception
     * will be thrown.
     *
     * <P><B>Space Policy</B><BR>
     * If the row will not fit on a page then:
     * <UL>
     * <LI> an exception is thrown if the page has no other rows, this is an 
     *      indication that the row could never fit on a page in this container.
     * <LI> null is returned if there are other rows on the page, this is an 
     *      indication that the row can potentially be inserted successfully 
     *      onto an empty page.
     * </UL>
     *
     * <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 slot          The specified slot
     * @param row           The row version of the data
     * @param undo          if logical undo may be necessary, a function pointer
     *                      to the access code where the logical undo logic 
     *                      resides. Null if logical undo is not necessary.
     * @param validColumns  a bit map of which columns in the row is valid.  
     *                      ValidColumns will not be changed by RawStore.
     * @param insertFlag    if INSERT_UNDO_WITH_PURGE set, then the undo of this
     *                      insert will purge the row rather than mark it as 
     *                      deleted, which is the default bahavior for 
     *                      insertAtSlot and insert.
     *
     * @return A RecordHandle representing the new record, or null if the row 
     *         will not fit on a non-empty page.
     *
     * @exception StandardException	Standard Cloudscape error policy
     * @exception StandardException The container was not opened in update mode.
     * @exception StandardException The row cannot fit on the page
     *
     * @see LogicalUndo
     * @see LogicalUndoable