--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.raw.Page\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.raw;\r
+\r
+import org.apache.derby.iapi.services.io.FormatableBitSet;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import org.apache.derby.iapi.store.access.conglomerate.LogicalUndo;\r
+\r
+import org.apache.derby.iapi.store.access.Qualifier;\r
+\r
+import org.apache.derby.iapi.types.DataValueDescriptor;\r
+\r
+\r
+/**\r
+ A Page contains an ordered set of records which are the stored form of rows.\r
+ A record is a stream of bytes created from a row array. The record\r
+ contains one or more fields, fields have a one to one correlation with\r
+ the DataValueDescriptor's contained within a row array.\r
+ <P>\r
+ A Page represents <B>exclusive</B> access to a data page within a container.\r
+ Exclusive access is released by calling the unlatch() method, once that \r
+ occurs the caller must no longer use the Page reference.\r
+ <P>\r
+ Several of the methods in Page take a RecordHandle as an argument. \r
+ RecordHandles are obtained from a Page, while holding exclusive access of \r
+ Page or a from a previous exclusive access of a Page representing the same \r
+ data page.\r
+ All RecordHandle's used as arguments to methods (with the exception of \r
+ recordExists()) must be valid for the current state of the page. If they \r
+ are not valid then the method will throw an exception. A caller can ensure \r
+ that a record handle is valid by:\r
+ <UL>\r
+ <LI> Obtaining the handle during this exclusive access of this page\r
+ <LI> Checking the record still exists with the method recordExists()\r
+ <LI> Not using a handle after a deleteAtSlot().\r
+ </UL>\r
+ <P>\r
+ Several of the methods in Page take a slot number as an argument. A slot \r
+ always correspond to a record, which may be deleted or undeleted.\r
+\r
+ <BR>\r
+ MT - Latched - In general every method requires the page to be latched.\r
+\r
+ <P>\r
+ <B>Latching</B>\r
+ <P>\r
+ All page methods which are not valid for a latched page throw an\r
+ exception if the page is not latched. [@exception clauses on all\r
+ the methods should be updated to reflect this].\r
+\r
+ <P>\r
+ <B>Aux Objects</B>\r
+ <BR>\r
+ The page cache will manage a client object along with the page as long\r
+ as it remains in cache. This object is called the "aux object". The \r
+ aux object is associated with the page with setAuxObject(), and can be\r
+ retreived later with getAuxObject(). The aux object will remain valid\r
+ as long as the page is latched, but callers cannot assume that an aux\r
+ object will ever stick around once the page is unlatched. However, the\r
+ page manager promises to call pageBeingEvicted() once before clearing\r
+ the aux reference from the page.\r
+\r
+ @see Object\r
+ @see ContainerHandle\r
+ @see RecordHandle\r
+ @see AuxObject\r
+*/\r
+\r
+public interface Page \r
+{\r
+\r
+ /**************************************************************************\r
+ * Constants of the class\r
+ **************************************************************************\r
+ */\r
+\r
+ /**\r
+ * The slot number of the first slot. This is guaranteed to be zero.\r
+ **/\r
+ public static final int FIRST_SLOT_NUMBER = 0;\r
+ \r
+ /**\r
+ * A slot number guaranteed to be invalid.\r
+ **/\r
+ public static final int INVALID_SLOT_NUMBER = -1;\r
+ \r
+ /**\r
+ * Return the page number of this page. \r
+ * <p>\r
+ * Page numbers are unique within a container and start at \r
+ * ContainerHandle.FIRST_PAGE_NUMBER and increment by 1 regardless of the \r
+ * page size.\r
+ * <p>\r
+ *\r
+ * <BR> MT - Latched\r
+ *\r
+ * @see ContainerHandle\r
+ *\r
+ * @return The page number of this page.\r
+ **/\r
+ public long getPageNumber();\r
+\r
+ /**************************************************************************\r
+ * Public Methods of This class: record handle interface.\r
+ * the following interfaces to page use the record Id or record handle\r
+ * (rather than the slot interface).\r
+ **************************************************************************\r
+ */\r
+\r
+ /**\r
+ * Return an invalid record handle.\r
+ * <p>\r
+ *\r
+ * @return an invalid record handle.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public RecordHandle getInvalidRecordHandle();\r
+\r
+ /**\r
+ * Return a record handle for the given constant record id.\r
+ * <p>\r
+ * Return a record handle that doesn't represent a record but rather has \r
+ * a special meaning. Used for special cases like creating a key \r
+ * specific to the page, but not specific to a row on the page.\r
+ * <p>\r
+ * See RecordHandle interface for a list of "special record handles."\r
+ *\r
+ * @see RecordHandle\r
+ *\r
+ * @return The created record handle.\r
+ *\r
+ * @param recordHandleConstant the special recordId\r
+ *\r
+ * @exception StandardException if input is not a special record identifier.\r
+ **/\r
+ public RecordHandle makeRecordHandle(int recordHandleConstant) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Get a record handle from a previously stored record id.\r
+ * <p>\r
+ * Get a record handle from a previously stored record identifier that was\r
+ * obtained from a RecordHandle.\r
+ * <p>\r
+ * <BR> MT - Latched\r
+ *\r
+ * @return A valid record handle or null if the record no longer exists.\r
+ *\r
+ * @param recordId previously stored recordId.\r
+ *\r
+ * @see RecordHandle#getId\r
+ **/\r
+ RecordHandle getRecordHandle(int recordId);\r
+\r
+ /**\r
+ * does the record still exist on the page?\r
+ * <p>\r
+ * If "ignoreDelete" is true and the record handle represents a record on \r
+ * the page (either marked deleted or not) return true. If "ignoreDelete" \r
+ * is false return true if the record handle represents a record on the \r
+ * page and the record is not marked as deleted. Return false otherwise.\r
+ *\r
+ * <BR> MT - Latched\r
+ *\r
+ * @return boolean indicating if the record still exists on the page.\r
+ *\r
+ * @param handle handle of the record to look for.\r
+ * @param ignoreDelete if true, then routine will return true even if the\r
+ * row is marked deleted.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean recordExists(RecordHandle handle, boolean ignoreDelete) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Is it likely that an insert will fit on this page?\r
+ * <p>\r
+ * Return true if there is a good chance an insert will fit on this page, \r
+ * false otherwise. If this returns true then an insert may still fail by \r
+ * throwing an exception or by returning null, see insertAtSlot for details.\r
+ * It is very probable that this call is much faster than the version that \r
+ * takes a row. In situations where it is expected that the \r
+ * majority of times a row will fit on a page this method should be used \r
+ * and the null return handled from insert/insertAtSlot.\r
+ *\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @return true if it is likely an insert will fit on the page.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean spaceForInsert() \r
+ throws StandardException;\r
+\r
+ /**\r
+ * will insert of this row fit on this page?\r
+ * <p>\r
+ * Return true if this record is guaranteed to be inserted successfully \r
+ * using insert() or insertAtSlot(). This guarantee is only valid if the \r
+ * following conditions are fulfilled before an insert is called with t\r
+ * his row.\r
+ * <UL>\r
+ * <LI> The page is not unlatched\r
+ * <LI> The page is not modified in any way, ie. no updates or other inserts\r
+ * <LI> The row is not modified in such a way that would change its \r
+ * storage size\r
+ * </UL>\r
+ *\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @return true if insert of this row will fit on this page.\r
+ *\r
+ * @param row The row to check for insert.\r
+ * @param validColumns bit map to interpret valid columns in row.\r
+ * @param overflowThreshold The percentage of the page to use for the\r
+ * insert. 100 means use 100% of the page,\r
+ * 50 means use 50% of page (ie. make sure\r
+ * 2 rows fit per page).\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ boolean spaceForInsert(\r
+ Object[] row, \r
+ FormatableBitSet validColumns, \r
+ int overflowThreshold) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Insert a record anywhere on the page.\r
+ * <P>\r
+ *\r
+ * <B>Locking Policy</B>\r
+ * <BR>\r
+ * Calls the lockRecordForWrite() method of the LockingPolicy object\r
+ * passed to the openContainer() call before the record is inserted.\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @param row The row version of the data\r
+ * @param validColumns a bit map of which columns in the row is valid. \r
+ * ValidColumns will not be changed by RawStore.\r
+ * @param insertFlag see values for insertFlag below.\r
+ *\r
+ * @return A RecordHandle representing the new record.\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ * @exception StandardException The container was not opened in update mode.\r
+ * @exception StandardException Row cannot fit on the page or row is null.\r
+ **/\r
+ RecordHandle insert(\r
+ Object[] row, \r
+ FormatableBitSet validColumns,\r
+ byte insertFlag, \r
+ int overflowThreshold)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Move record to a page toward the beginning of the file.\r
+ * <p>\r
+ * As part of compressing the table records need to be moved from the\r
+ * end of the file toward the beginning of the file. Only the \r
+ * contiguous set of free pages at the very end of the file can\r
+ * be given back to the OS. This call is used to purge the row from\r
+ * the current page, insert it into a previous page, and return the\r
+ * new row location \r
+ * Mark the record identified by position as deleted. The record may be \r
+ * undeleted sometime later using undelete() by any transaction that sees \r
+ * the record.\r
+ * <p>\r
+ * The interface is optimized to work on a number of rows at a time, \r
+ * optimally processing all rows on the page at once. The call will \r
+ * process either all rows on the page, or the number of slots in the\r
+ * input arrays - whichever is smaller.\r
+ * <B>Locking Policy</B>\r
+ * <P>\r
+ * MUST be called with table locked, not locks are requested. Because\r
+ * it is called with table locks the call will go ahead and purge any\r
+ * row which is marked deleted. It will also use purge rather than\r
+ * delete to remove the old row after it moves it to a new page. This\r
+ * is ok since the table lock insures that no other transaction will\r
+ * use space on the table before this transaction commits.\r
+ *\r
+ * <BR>\r
+ * A page latch on the new page will be requested and released.\r
+ *\r
+ * @param slot Slot of row to move.\r
+ * @param row A template to read the current row into as part\r
+ * of moving it.\r
+ * @param old_handle An array to be filled in by the call with the \r
+ * old handles of all rows moved.\r
+ * @param new_handle An array to be filled in by the call with the \r
+ * new handles of all rows moved.\r
+ *\r
+ * @return the number of rows processed.\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ *\r
+ * @see LockingPolicy\r
+ **/\r
+ public int moveRecordForCompressAtSlot(\r
+ int slot,\r
+ Object[] row,\r
+ RecordHandle[] old_handle,\r
+ RecordHandle[] new_handle)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Fetch the number of fields in a record. \r
+ * <p>\r
+ * <B>Locking Policy</B>\r
+ * <P>\r
+ * No locks are obtained.\r
+ *\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @param handle record handle to deleted or non-deleted record\r
+ *\r
+ * @return the number of fields in the record\r
+ *\r
+ * @exception StandardException Standard Derby error policy, a \r
+ * statement level exception is thrown if the \r
+ * record handle does not match a record on \r
+ * the page.\r
+ **/\r
+ public int fetchNumFields(RecordHandle handle)\r
+ throws StandardException;\r
+\r
+ /**************************************************************************\r
+ * Public Methods of This class: slot interface.\r
+ * the following interfaces to page use the slot number \r
+ * (rather than the record handle interface).\r
+ **************************************************************************\r
+ */\r
+\r
+\r
+ /**\r
+ * Get the slot number.\r
+ * <p>\r
+ * Get the slot number of a record on a latched page using its record \r
+ * handle.\r
+ *\r
+ * <P><B>Note</B>\r
+ * The slot number is only good for as long as the page is latched.\r
+ *\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @param handle the record handle\r
+ *\r
+ * @return the slot number\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ **/\r
+ int getSlotNumber(RecordHandle handle) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Get the record handle of row at slot.\r
+ * <p>\r
+ * Get the record handle of a record on a latched page using its slot \r
+ * number.\r
+ *\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @param slot the slot number\r
+ *\r
+ * @return the record handle.\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ **/\r
+ RecordHandle getRecordHandleAtSlot(int slot) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Find slot for record with an id greater than the passed in identifier.\r
+ * <p>\r
+ * Find the slot for the first record on the page with an id greater than \r
+ * the passed in identifier.\r
+ *\r
+ * <BR>\r
+ * Returns the slot of the first record on the page with an id greater than\r
+ * the one passed in. Usefulness of this functionality depends on the \r
+ * client's use of the raw store interfaces. If all "new" records are \r
+ * always inserted at the end of the page, and the raw store continues to\r
+ * guarantee that all record id's will be allocated in increasing order on \r
+ * a given page (assuming a PAGE_REUSABLE_RECORD_ID container), then a page\r
+ * is always sorted in record id order. For instance current heap tables \r
+ * function this way. If the client ever inserts at a particular slot \r
+ * number, rather than at the "end" then the record id's will not be sorted.\r
+ * <BR>\r
+ * In the case where all record id's are always sorted on a page, then this\r
+ * routine can be used by scan's which "lose" their position because the \r
+ * row they have as a position was purged. They can reposition their scan \r
+ * at the "next" row after the row that is now missing from the table.\r
+ * <BR>\r
+ * This method returns the record regardless of its deleted status.\r
+ * <BR>\r
+ * MT - latched\r
+ * \r
+ * @param handle record handle to find the next higher id.\r
+ *\r
+ * @return record id of the first record on the page with a record id \r
+ * higher than the one passed in. If no such record exists, \r
+ * -1 is returned.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ int getNextSlotNumber(RecordHandle handle) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * Insert a record at the specified slot. \r
+ * <p>\r
+ * All records that occupy FIRST_SLOT_NUMBER to (slot - 1) are not moved. \r
+ * <BR>\r
+ * All records that occupy slot to (recordCount() - 1) are moved up one \r
+ * slot. \r
+ * <BR>\r
+ * The new record is inserted at the specified slot. <BR>\r
+ * If slot == FIRST_SLOT_NUMBER, then the new record will be inserted at \r
+ * the first slot. <BR>\r
+ * If slot == recordCount(), then the record is inserted in a new slot, no\r
+ * records are moved. <BR>\r
+ *\r
+ * If slot is > recordCount() or if slot < FIRST_SLOT_NUMBER, an exception\r
+ * will be thrown.\r
+ *\r
+ * <P><B>Space Policy</B><BR>\r
+ * If the row will not fit on a page then:\r
+ * <UL>\r
+ * <LI> an exception is thrown if the page has no other rows, this is an \r
+ * indication that the row could never fit on a page in this container.\r
+ * <LI> null is returned if there are other rows on the page, this is an \r
+ * indication that the row can potentially be inserted successfully \r
+ * onto an empty page.\r
+ * </UL>\r
+ *\r
+ * <P>\r
+ * <B>Locking Policy</B>\r
+ * <BR>\r
+ * Calls the lockRecordForWrite() method of the LockingPolicy object passed\r
+ * to the openContainer() call before the record is inserted.\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @param slot The specified slot\r
+ * @param row The row version of the data\r
+ * @param undo if logical undo may be necessary, a function pointer\r
+ * to the access code where the logical undo logic \r
+ * resides. Null if logical undo is not necessary.\r
+ * @param validColumns a bit map of which columns in the row is valid. \r
+ * ValidColumns will not be changed by RawStore.\r
+ * @param insertFlag if INSERT_UNDO_WITH_PURGE set, then the undo of this\r
+ * insert will purge the row rather than mark it as \r
+ * deleted, which is the default bahavior for \r
+ * insertAtSlot and insert.\r
+ *\r
+ * @return A RecordHandle representing the new record, or null if the row \r
+ * will not fit on a non-empty page.\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ * @exception StandardException The container was not opened in update mode.\r
+ * @exception StandardException The row cannot fit on the page\r
+ *\r
+ * @see LogicalUndo\r
+ * @see LogicalUndoable\r
+ **/\r
+ RecordHandle insertAtSlot(\r
+ int slot, \r
+ Object[] row, \r
+ FormatableBitSet validColumns, \r
+ LogicalUndo undo,\r
+ byte insertFlag, \r
+ int overflowThreshold)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Values for insertFlag.\r
+ * <p>\r
+ *\r
+ * INSERT_INITIAL - flag initializer\r
+ *\r
+ * INSERT_DEFAULT - default insert behavior, if the record does\r
+ * not fit on the page where the insert \r
+ * operation is called, an error will be \r
+ * returned, instead of overflowing the record.\r
+ *\r
+ * INSERT_UNDO_WITH_PURGE - if this is set, then the undo of this insert \r
+ * will purge the row rather than mark it as \r
+ * deleted, which is the default behaviro for \r
+ * insertAtSlot and insert.\r
+ *\r
+ * INSERT_CONDITIONAL - if this flag is set, then, the overflow is \r
+ * conditional. The record will be overflowed \r
+ * only if it exceeds the threshold specified \r
+ * by the properties, or the parameter.\r
+ *\r
+ * INSERT_OVERFLOW - if this flag is set, then the insert \r
+ * operation will overflow the record if it does\r
+ * not fit on the page. \r
+ *\r
+ * INSERT_FOR_SPLIT - a record is being updated that causes new \r
+ * portions to be inserted *and* the last new \r
+ * portion needs to point to an existing portion.\r
+ *\r
+ * Rules for the insert flags:\r
+ * 1. If INSERT_DEFAULT is set, INSERT_CONDITIONAL and INSERT_OVERFLOW \r
+ * will be ignored\r
+ * 2. INSERT_UNDO_WITH_PURGE can be set with any of the other 3 flags.\r
+ * 3. If INSERT_OVERFLOW is not set, INSERT_CONDITIONAL will be ignored. \r
+ * But, it is not necessary to set INSERT_CONDITIONAL when setting \r
+ * INSERT_OVERFLOW.\r
+ * 4. If INSERT_DEFAULT, INSERT_OVERFLOW both are not set, then, default \r
+ * insert action will be taken, i.e. no overflow will be allowed.\r
+ **/\r
+ static final byte INSERT_INITIAL = (byte) 0x00; // init the flag\r
+ static final byte INSERT_DEFAULT = (byte) 0x01; // default flag\r
+ static final byte INSERT_UNDO_WITH_PURGE = (byte) 0x02; // purge row on undo\r
+ static final byte INSERT_CONDITIONAL = (byte) 0x04; // conditional \r
+ // insert\r
+ static final byte INSERT_OVERFLOW = (byte) 0x08; // insert with \r
+ // possible overflow\r
+ static final byte INSERT_FOR_SPLIT = (byte) 0x10; // rawstore only\r
+\r
+\r
+ /**\r
+ * Fetch a record located in the passed in slot.\r
+ * <p>\r
+ * Fetch a record located in the passed in slot and fill-in the passed in \r
+ * StorebleRow and the Object columns contained within. If row\r
+ * is null then the record is locked but is not fetched.\r
+ * <BR>\r
+ * This interface allows the caller to either return a deleted row or not. \r
+ * If "ignoreDelete" is set to true, fetch the record regardless of whether \r
+ * it is deleted or not (same as above fetchFromSlot). However, if \r
+ * "ignoreDelete" is set to false and the and the slot correspond to a \r
+ * deleted row, null is returned.\r
+ * <BR>\r
+ * If a non-null Qualifier list is provided then the qualifier array will \r
+ * be applied to the row and the row will only be returned if the row \r
+ * qualifies, otherwise null will be returned. Values in the columns of \r
+ * row may or may not be altered while trying to apply the qualifiers, if \r
+ * null is returned the state of the columns is undefined. If a null \r
+ * Qualifier list is provided then no qualification is applied.\r
+ * <BR>\r
+ * If a non-null record handle is passed in, it is assumed that the record \r
+ * handle corresponds to the record in the slot. If record handle is null,\r
+ * a record handle will be manufactured and returned if the record is not \r
+ * deleted or if "ignoreDelete" is true. This parameter is here for the \r
+ * case where the caller have already manufactured the record handle for \r
+ * locking or other purposes so it would make sense for the page to avoid \r
+ * creating a new record handle object if possible.\r
+ *\r
+ *\r
+ * @param rh the record handle of the row. If non-null it must \r
+ * refer to the same record as the slot. \r
+ * @param slot the slot number\r
+ * @param row Row to be filled in with information from record.\r
+ * @param fetchDesc A structure to efficiently carry a set of parameters\r
+ * needed to describe the fetch, these include:\r
+ * \r
+ * validColumns - A bit map of which columns in the \r
+ * row to be fetched. ValidColumns will not be \r
+ * changed by RawStore.\r
+ *\r
+ * qualifier_list - \r
+ * A list of Qualifiers to apply to the row to see if\r
+ * the row should be returned.\r
+ *\r
+ * An array of qualifiers which restrict whether or not\r
+ * the row should be returned by the fetch. Rows for \r
+ * which any one of the qualifiers returns false are \r
+ * not returned by the fetch. If null, no qualification\r
+ * is done and the requested columns of the rows are \r
+ * returned. Qualifiers can only reference columns \r
+ * which are included in the scanColumnList. The \r
+ * column id that a qualifier returns is the column id\r
+ * the table, not the column id in the partial row \r
+ * being returned. \r
+ * qualifier_scratch_space - \r
+ * An array of int's that matches the size of the \r
+ * row[] array. Used to process qualifiers, if no\r
+ * qualifiers are input then array need not be \r
+ * input. Passed in rather than allocated so that\r
+ * space can be allocated a single time in a scan.\r
+ * If not passed in then raw store will allocate and\r
+ * deallocate per call.\r
+ *\r
+ * @param ignoreDelete if true, return row regardless of whether it is \r
+ * deleted or not. If false, only return non-deleted \r
+ * row.\r
+ *\r
+ * @return A handle to the record.\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ *\r
+ * @see LockingPolicy\r
+ **/\r
+ public RecordHandle fetchFromSlot(\r
+ RecordHandle rh, \r
+ int slot, \r
+ Object[] row,\r
+ FetchDescriptor fetchDesc,\r
+ boolean ignoreDelete)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ Fetch a single field from a deleted or non-deleted record.\r
+ Fills in the passed in Object column with the field\r
+ identified by fieldid if column is not null, otherwise the record\r
+ is locked but not fetched.\r
+ <BR>\r
+ The fieldId of the first field is 0.\r
+ If the fieldId is >= the number of fields on the record, \r
+ column is restored to null\r
+ <P>\r
+ <B>Locking Policy</B>\r
+ <BR>\r
+ No locks are obtained. \r
+ It is up to the caller to obtain the correct locks.\r
+ <BR>\r
+\r
+ It is guaranteed that the page latch is not released by this method\r
+\r
+ @param slot is the slot number\r
+ @param fieldId is the column id\r
+ @param column is to be filled in with information from the record.\r
+\r
+ @return the Handle to the record that is locked\r
+\r
+ @exception StandardException Standard Derby error policy, a \r
+ statement level exception is thrown if\r
+ the slot is not on the page.\r
+\r
+ @see Page#fetchFromSlot\r
+ @see LockingPolicy\r
+ */\r
+ public RecordHandle fetchFieldFromSlot(\r
+ int slot, \r
+ int fieldId, \r
+ Object column)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Test if a record is deleted.\r
+ * <p>\r
+ *\r
+ * <P>\r
+ * <B>Locking Policy</B>\r
+ * <BR>\r
+ * No locks are obtained.\r
+ *\r
+ * <BR>\r
+ * It is guaranteed that the page latch is not released by this method\r
+ *\r
+ * @param slot slot of record to be tested.\r
+ *\r
+ * @exception StandardException Standard Derby error policy, a \r
+ * statement level exception is thrown if the \r
+ * slot is not on the page.\r
+ **/\r
+ public boolean isDeletedAtSlot(int slot)\r
+ throws StandardException;\r
+\r
+ /** \r
+ Update a field within the record, replacing its current value with\r
+ the stored representation of newValue. Record is identified by slot.\r
+ If the field does not exist then it is added to the record, but only if\r
+ (fieldId - 1) exists.\r
+\r
+ <BR><B>RESOLVE</B> right now it throws an exception if fieldId is not \r
+ already on the record, not add the next one as advertised.\r
+\r
+ <P>\r
+ <B>Locking Policy</B>\r
+ <P>\r
+ Calls the lockRecordForWrite() method of the LockingPolicy object\r
+ passed to the openContainer() call before the record is updated.\r
+\r
+ <BR>\r
+ It is guaranteed that the page latch is not released by this method\r
+ \r
+\r
+ @param slot is the slot number\r
+ @param fieldId is the column id\r
+ @param newValue has the new colum value to be stored in the record\r
+ @param undo if logical undo may be necessary, a function pointer to the\r
+ access code where the logical undo logic resides. Null if logical undo\r
+ is not necessary.\r
+\r
+ @return a Handle to the updated record.\r
+\r
+ @exception StandardException Standard Derby error policy, a\r
+ statement level exception is thrown if\r
+ the slot is not on the page, or if the \r
+ record is deleted, or if the fieldId \r
+ is not on the record and (fieldId - 1)\r
+ does not exist.\r
+\r
+ @exception StandardException \r
+ The container was not opened in update mode.\r
+\r
+ @see LockingPolicy\r
+ @see LogicalUndo\r
+ @see LogicalUndoable\r
+\r
+ */\r
+ public RecordHandle updateFieldAtSlot(\r
+ int slot, \r
+ int fieldId, \r
+ Object newValue, \r
+ LogicalUndo undo)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ * Fetch the number of fields in a record.\r
+ * <p>\r
+ *\r
+ * <P>\r
+ * <B>Locking Policy</B>\r
+ * <P>\r
+ * No locks are obtained.\r
+ *\r
+ * <BR>\r
+ * It is guaranteed that the page latch is not released by this method\r
+ *\r
+ * @param slot is the slot number\r
+ *\r
+ * @return the number of fields in the record\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ **/\r
+ public int fetchNumFieldsAtSlot(int slot)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Mark the record at slot as deleted or undeleted according to delete flag.\r
+ * <p>\r
+ *\r
+ * <P>\r
+ * <B>Locking Policy</B>\r
+ * <P>\r
+ * Calls the lockRecordForWrite() method of the LockingPolicy object passed\r
+ * to the openContainer() call before the record is deleted. If record \r
+ * already deleted, and an attempt is made to delete it, an exception is \r
+ * thrown. If record not deleted, and an attempt is made to undelete it, \r
+ * an exception is thrown.\r
+ *\r
+ * <BR>\r
+ * MT - latched\r
+ *\r
+ * @return a Handle to the deleted/undeleted record.\r
+ *\r
+ * @param slot is the slot number\r
+ * @param delete true if this record is to be deleted false if this \r
+ * deleted record is to be marked undeleted\r
+ * @param undo if logical undo may be necessary, a function pointer to\r
+ * the access code where the logical undo logic resides.\r
+ * Null if logical undo is not necessary.\r
+ * \r
+ * @exception StandardException Standard Derby error policy\r
+ * @exception StandardException The container was not opened in update mode.\r
+ * @exception StandardException A statement level exception is thrown when \r
+ * trying to delete an already deleted record,\r
+ * or undelete a not deleted record.\r
+ *\r
+ * @exception StandardException A statement level exception is thrown if \r
+ * the slot is not on the page.\r
+ *\r
+ * @see LockingPolicy\r
+ * @see LogicalUndo\r
+ * @see LogicalUndoable\r
+ *\r
+ **/\r
+ public RecordHandle deleteAtSlot(\r
+ int slot, \r
+ boolean delete, \r
+ LogicalUndo undo)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ * Purge the row(s) from page.\r
+ * <p>\r
+ * Purge the row(s) from page, get rid of the row(s) and slot(s) - \r
+ * <B>USE WITH CAUTION</B>, \r
+ * please see entire description of this operation before attempting to \r
+ * use this.\r
+ *\r
+ * Starting from the specified slot, n rows will be purged. That is, rows \r
+ * that occupies from slot to slot+n-1 will be purged from the page.\r
+ *\r
+ * <P>\r
+ * <B>Locking Policy</B>\r
+ * <P>\r
+ * Calls the lockRecordForWrite() method of the LockingPolicy object passed\r
+ * to the openContainer() call before the records are purged.\r
+ * <P>\r
+ *\r
+ * <B>NOTE : CAVEAT</B><BR>\r
+ * This operation will physically get rid of the row from the page, so if a\r
+ * subsequent operation on this page uses a slot that has been purged, then\r
+ * the undo of this operation will fail. It is only safe to use this \r
+ * operation if the caller knows that it has exclusive access to the page \r
+ * for the duration of the transaction, i.e, effectively holding a page \r
+ * lock on the page\r
+ * <P>\r
+ * <B>NOTE</B><BR>\r
+ * Outstanding handles to purged rows are no longer valid, accessing them \r
+ * will cause an exception to be thrown.\r
+ *\r
+ * <BR>\r
+ *<B>NOTE : Data Logging for Purges</B><BR>\r
+ * needDataLogged is used to specify whether data is required to be\r
+ * logged for purge operatios. Data Logging is required \r
+ * Only if the row can be reused or required for key search if a purge is\r
+ * rolled back;(rollback can occur if the system crashes in the middle of\r
+ * purges or some unexpected error condiditions rolled back.\r
+ * For example: \r
+ * 1)Btree expects the data to be there if a purge is rolled back;\r
+ * needDataLogged=true\r
+ * 2)Heaps does not care if data exist because only operation that can occur\r
+ * on a row whose purge rolled back is purging again.(needDataLogged=false)\r
+ * \r
+ * MT - latched\r
+ *\r
+ *\r
+ * @param slot the starting slot number\r
+ * @param numpurges number of slots to purge. If <= 0, \r
+ * just returns as a no-op.\r
+ * @param needDataLogged if set to true data is logged for purges else \r
+ * only headers.\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ * @see LockingPolicy\r
+ **/\r
+ public void purgeAtSlot(\r
+ int slot, \r
+ int numpurges,\r
+ boolean needDataLogged) \r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ * move rows from one page to another, purging in the process.\r
+ * <p>\r
+ *\r
+ * Move from this page slot[src_slot] to slot[src_slot+num_rows-1] to \r
+ * destPage slot[dest_slot] to slot[dest_slot + num_rows - 1], in that \r
+ * order. Both this page and destPage must be latched and from the same \r
+ * container with the same page and record format.\r
+ *\r
+ * <BR>Slot[src_slot] to slot[src_slot+numrows-1] will be purged from this \r
+ * page. RecordId on the dest page will be brand new and not in any \r
+ * particular order or range. RecordId of the purged rows in this page is \r
+ * never reused. Deleted and undeleted rows are copied over just the same.\r
+ *\r
+ * Exception will be thrown if this page does not have all the rows in the \r
+ * moved over range. \r
+ *\r
+ * <BR><B>RESOLVE: reserve space now not copied over because in btree, a\r
+ * row never shrinks. When this routine is called by heap or by some page\r
+ * which will have shrunken row, then we need to add that </B>\r
+ *\r
+ * <BR>DestPage must have at least dest_slot row occupying slot[0] to\r
+ * slot[dest_slot-1]. DestPage must have enough space to take the copied\r
+ * over data. Rows that occupied slot number > dest_slot will be moved up\r
+ * the slot (I.e., slot[dest_slot] -> slot[dest_slot + num_rows]). \r
+ *\r
+ * <BR>If this operation rolls back, this page (the src page) will get the\r
+ * rows back and the dest page will purge the rows that were copied - this\r
+ * is as if the rows were inserted into the dest page with \r
+ * INSERT_UNDO_WITH_PURGE.\r
+ *\r
+ * <P>\r
+ * <B>Locking Policy</B>\r
+ * <P>\r
+ * Calls the lockRecordForWrite() method of the LockingPolicy object\r
+ * passed to the openContainer() call before the rows are copied over and \r
+ * bore the records are purged. I.e, for num_rows moved, there will be\r
+ * 2*num_rows calls to lockRecordForWrite.\r
+ * <P>\r
+ *\r
+ * <P><B>Use with caution</B>\r
+ * <BR>As with a normal purge, no space is reserved on this page for \r
+ * rollback of the purge, so you must commit before inserting any rows \r
+ * onto this page - unless those inserts are INSERT_UNDO_WITH_PURGE.\r
+ *\r
+ * @param destPage the page to copy to\r
+ * @param src_slot start copying from this slot\r
+ * @param num_rows copy and purge this many rows from this page\r
+ * @param dest_slot copying into this slot of destPage\r
+ *\r
+ * @exception StandardException Standard Derby error policy\r
+ **/\r
+ public void copyAndPurge(\r
+ Page destPage, \r
+ int src_slot, \r
+ int num_rows, \r
+ int dest_slot)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Update the complete record identified by the slot.\r
+\r
+ <P>\r
+ <B>Locking Policy</B>\r
+ <P>\r
+ Calls the lockRecordForWrite() method of the LockingPolicy object\r
+ passed to the openContainer() call before the record is undeleted.\r
+ If record already deleted, an exception is thrown.\r
+\r
+ <BR>\r
+ It is guaranteed that the page latch is not released by this method\r
+\r
+ @return a Handle to the updated record.\r
+ @param slot is the slot number\r
+ @param validColumns a bit map of which columns in the row is valid.\r
+ ValidColumns will not be changed by RawStore.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+ @exception StandardException The container was not opened in update mode.\r
+ @exception StandardException if the slot is not on the page.\r
+\r
+ */\r
+ RecordHandle updateAtSlot(\r
+ int slot, \r
+ Object[] row, \r
+ FormatableBitSet validColumns)\r
+ throws StandardException;\r
+\r
+ /*\r
+ Page operations\r
+ */\r
+\r
+ /**\r
+ Unlatch me, the page is exclusivly latched by its current user until\r
+ this method call is made.\r
+ <BR>\r
+ After using this method the caller must throw away the\r
+ reference to the Page object, e.g.\r
+ <PRE>\r
+ ref.unlatch();\r
+ ref = null;\r
+ </PRE>\r
+ <BR>\r
+ The page will be released automatically at the close of the\r
+ container if this method is not called explictly.\r
+\r
+ <BR>\r
+ MT - latched\r
+\r
+ */\r
+ public void unlatch();\r
+\r
+\r
+\r
+ /**\r
+ Return the number of records on the page. The returned count includes rows that are deleted,\r
+ i.e. it is the same as the number of slots on the page.\r
+\r
+ <BR>\r
+ MT - latched\r
+\r
+ @exception StandardException Standard Derby error policy\r
+ */\r
+\r
+ public int recordCount() throws StandardException;\r
+\r
+ /**\r
+ Return the number of records on this page that are <B> not </B> marked as deleted.\r
+ \r
+ <BR>\r
+ MT - latched\r
+\r
+ @exception StandardException Standard Derby error policy\r
+ */\r
+\r
+ public int nonDeletedRecordCount() throws StandardException;\r
+\r
+ /**\r
+ * Is this page/deleted row a candidate for immediate reclaim space.\r
+ * <p>\r
+ * Used by access methods after executing a delete on "slot_just_deleted"\r
+ * to ask whether a post commit should be queued to try to reclaim space\r
+ * after the delete commits. \r
+ * <p>\r
+ * Will return true if the number of non-deleted rows on the page is\r
+ * <= "num_non_deleted_rows". For instance 0 means schedule reclaim\r
+ * only if all rows are deleted, 1 if all rows but one are deleted. \r
+ * <p>\r
+ * Will return true if the row just deleted is either a long row or long\r
+ * column. In this case doing a reclaim space on the single row may\r
+ * reclaim multiple pages of free space, so better to do it now rather\r
+ * than wait for all rows on page to be deleted. This case is to address\r
+ * the worst case scenario of all rows with long columns, but very short\r
+ * rows otherwise. In this case there could be 1000's of rows on the \r
+ * main page with many gigabytes of data on overflow pages in deleted space\r
+ * that would not be reclaimed until all rows on the page were deleted.\r
+ *\r
+ * @return true if a reclaim space should be scheduled post commit on this\r
+ * page, false otherwise.\r
+ *\r
+ * @param num_non_deleted_rows threshold number of non-deleted rows to\r
+ * schedule reclaim space.\r
+ * @param slot_just_deleted row on page to check for long row/long column\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public boolean shouldReclaimSpace(\r
+ int num_non_deleted_rows,\r
+ int slot_just_deleted)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Set the aux object for this page.\r
+ To clear the auxObject in the page, pass in a null AuxObject.\r
+ If the AuxObject has already been set, this method will\r
+ call auxObjectInvalidated() on the old aux objkect and replace it with aux.\r
+\r
+ <BR>\r
+ MT - latched\r
+\r
+ @see AuxObject\r
+ **/\r
+ public void setAuxObject(AuxObject aux);\r
+\r
+ /**\r
+ Retrieve this page's aux object, returning null if there isn't one. The reference returned\r
+ must only be used while the page is latched, once unlatch is called the reference to the\r
+ aux object must be discarded.\r
+\r
+ <BR> MT - latched\r
+\r
+ @see AuxObject\r
+ **/\r
+ public AuxObject getAuxObject();\r
+\r
+ /**\r
+ Returns true if the page is latched. Only intended to be used as a Sanity check. Callers must\r
+ discard Page references once unlatch is called.\r
+\r
+ <BR>\r
+ MT - latched\r
+ */\r
+\r
+\r
+ /*\r
+ * time stamp - for those implmentation that supports it\r
+ */\r
+\r
+ /**\r
+ Set the time stamp to what is on page at this instance. No op if this\r
+ page does not support time stamp.\r
+\r
+ @exception StandardException Standard Derby error policy.\r
+ */\r
+ void setTimeStamp(PageTimeStamp ts) throws StandardException;\r
+\r
+\r
+ /**\r
+ Return a time stamp that can be used to identify the page of this\r
+ specific instance. For pages that don't support timestamp, returns\r
+ null.\r
+ */\r
+ PageTimeStamp currentTimeStamp();\r
+\r
+ /**\r
+ See if timeStamp for this page is the same as the current\r
+ instance of the page. Null timeStamp never equals the instance of the\r
+ page.\r
+\r
+ @param ts the time stamp gotten from an earlier call to this page's\r
+ getTimeStamp\r
+ @return true if timestamp is the same\r
+ @exception StandardException Standard Derby error policy.\r
+\r
+ @see PageTimeStamp\r
+ */\r
+ boolean equalTimeStamp(PageTimeStamp ts) throws StandardException;\r
+\r
+ public boolean isLatched();\r
+\r
+ public static final String DIAG_PAGE_SIZE = "pageSize";\r
+ public static final String DIAG_RESERVED_SPACE = "reserveSpace";\r
+ public static final String DIAG_MINIMUM_REC_SIZE = "minRecSize";\r
+ public static final String DIAG_BYTES_FREE = "bytesFree";\r
+ public static final String DIAG_BYTES_RESERVED = "bytesReserved";\r
+ public static final String DIAG_NUMOVERFLOWED = "numOverFlowed";\r
+ public static final String DIAG_ROWSIZE = "rowSize";\r
+ public static final String DIAG_MINROWSIZE = "minRowSize";\r
+ public static final String DIAG_MAXROWSIZE = "maxRowSize";\r
+ public static final String DIAG_PAGEOVERHEAD = "pageOverhead";\r
+ public static final String DIAG_SLOTTABLE_SIZE = "slotTableSize";\r
+}\r
projects / Benchmarks_CSolver.git / blobdiff