0001: /*
0002:
0003: Derby - Class org.apache.derby.iapi.store.raw.Page
0004:
0005: Licensed to the Apache Software Foundation (ASF) under one or more
0006: contributor license agreements. See the NOTICE file distributed with
0007: this work for additional information regarding copyright ownership.
0008: The ASF licenses this file to you under the Apache License, Version 2.0
0009: (the "License"); you may not use this file except in compliance with
0010: the License. You may obtain a copy of the License at
0011:
0012: http://www.apache.org/licenses/LICENSE-2.0
0013:
0014: Unless required by applicable law or agreed to in writing, software
0015: distributed under the License is distributed on an "AS IS" BASIS,
0016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0017: See the License for the specific language governing permissions and
0018: limitations under the License.
0019:
0020: */
0021:
0022: package org.apache.derby.iapi.store.raw;
0023:
0024: import org.apache.derby.iapi.services.io.FormatableBitSet;
0025:
0026: import org.apache.derby.iapi.error.StandardException;
0027:
0028: import org.apache.derby.iapi.store.access.conglomerate.LogicalUndo;
0029:
0030: import org.apache.derby.iapi.store.access.Qualifier;
0031:
0032: import org.apache.derby.iapi.types.DataValueDescriptor;
0033:
0034: /**
0035: A Page contains an ordered set of records which are the stored form of rows.
0036: A record is a stream of bytes created from a row array. The record
0037: contains one or more fields, fields have a one to one correlation with
0038: the DataValueDescriptor's contained within a row array.
0039: <P>
0040: A Page represents <B>exclusive</B> access to a data page within a container.
0041: Exclusive access is released by calling the unlatch() method, once that
0042: occurs the caller must no longer use the Page reference.
0043: <P>
0044: Several of the methods in Page take a RecordHandle as an argument.
0045: RecordHandles are obtained from a Page, while holding exclusive access of
0046: Page or a from a previous exclusive access of a Page representing the same
0047: data page.
0048: All RecordHandle's used as arguments to methods (with the exception of
0049: recordExists()) must be valid for the current state of the page. If they
0050: are not valid then the method will throw an exception. A caller can ensure
0051: that a record handle is valid by:
0052: <UL>
0053: <LI> Obtaining the handle during this exclusive access of this page
0054: <LI> Checking the record still exists with the method recordExists()
0055: <LI> Not using a handle after a delete().
0056: </UL>
0057: <P>
0058: Several of the methods in Page take a slot number as an argument. A slot
0059: always correspond to a record, which may be deleted or undeleted.
0060:
0061: <BR>
0062: MT - Latched - In general every method requires the page to be latched.
0063:
0064: <P>
0065: <B>Latching</B>
0066: <P>
0067: All page methods which are not valid for a latched page throw an
0068: exception if the page is not latched. [@exception clauses on all
0069: the methods should be updated to reflect this].
0070:
0071: <P>
0072: <B>Aux Objects</B>
0073: <BR>
0074: The page cache will manage a client object along with the page as long
0075: as it remains in cache. This object is called the "aux object". The
0076: aux object is associated with the page with setAuxObject(), and can be
0077: retreived later with getAuxObject(). The aux object will remain valid
0078: as long as the page is latched, but callers cannot assume that an aux
0079: object will ever stick around once the page is unlatched. However, the
0080: page manager promises to call pageBeingEvicted() once before clearing
0081: the aux reference from the page.
0082:
0083: @see Object
0084: @see ContainerHandle
0085: @see RecordHandle
0086: @see AuxObject
0087: */
0088:
0089: public interface Page {
0090:
0091: /**************************************************************************
0092: * Constants of the class
0093: **************************************************************************
0094: */
0095:
0096: /**
0097: * The slot number of the first slot. This is guaranteed to be zero.
0098: **/
0099: public static final int FIRST_SLOT_NUMBER = 0;
0100:
0101: /**
0102: * A slot number guaranteed to be invalid.
0103: **/
0104: public static final int INVALID_SLOT_NUMBER = -1;
0105:
0106: /**
0107: * Return the page number of this page.
0108: * <p>
0109: * Page numbers are unique within a container and start at
0110: * ContainerHandle.FIRST_PAGE_NUMBER and increment by 1 regardless of the
0111: * page size.
0112: * <p>
0113: *
0114: * <BR> MT - Latched
0115: *
0116: * @see ContainerHandle
0117: *
0118: * @return The page number of this page.
0119: **/
0120: public long getPageNumber();
0121:
0122: /**************************************************************************
0123: * Public Methods of This class: record handle interface.
0124: * the following interfaces to page use the record Id or record handle
0125: * (rather than the slot interface).
0126: **************************************************************************
0127: */
0128:
0129: /**
0130: * Return an invalid record handle.
0131: * <p>
0132: *
0133: * @return an invalid record handle.
0134: *
0135: * @exception StandardException Standard exception policy.
0136: **/
0137: public RecordHandle getInvalidRecordHandle();
0138:
0139: /**
0140: * Return a record handle for the given constant record id.
0141: * <p>
0142: * Return a record handle that doesn't represent a record but rather has
0143: * a special meaning. Used for special cases like creating a key
0144: * specific to the page, but not specific to a row on the page.
0145: * <p>
0146: * See RecordHandle interface for a list of "special record handles."
0147: *
0148: * @see RecordHandle
0149: *
0150: * @return The created record handle.
0151: *
0152: * @param recordHandleConstant the special recordId
0153: *
0154: * @exception StandardException if input is not a special record identifier.
0155: **/
0156: public RecordHandle makeRecordHandle(int recordHandleConstant)
0157: throws StandardException;
0158:
0159: /**
0160: * Get a record handle from a previously stored record id.
0161: * <p>
0162: * Get a record handle from a previously stored record identifier that was
0163: * obtained from a RecordHandle.
0164: * <p>
0165: * <BR> MT - Latched
0166: *
0167: * @return A valid record handle or null if the record no longer exists.
0168: *
0169: * @param recordId previously stored recordId.
0170: *
0171: * @see RecordHandle#getId
0172: **/
0173: RecordHandle getRecordHandle(int recordId);
0174:
0175: /**
0176: * does the record still exist on the page?
0177: * <p>
0178: * If "ignoreDelete" is true and the record handle represents a record on
0179: * the page (either marked deleted or not) return true. If "ignoreDelete"
0180: * is false return true if the record handle represents a record on the
0181: * page and the record is not marked as deleted. Return false otherwise.
0182: *
0183: * <BR> MT - Latched
0184: *
0185: * @return boolean indicating if the record still exists on the page.
0186: *
0187: * @param handle handle of the record to look for.
0188: * @param ignoreDelete if true, then routine will return true even if the
0189: * row is marked deleted.
0190: *
0191: * @exception StandardException Standard exception policy.
0192: **/
0193: boolean recordExists(RecordHandle handle, boolean ignoreDelete)
0194: throws StandardException;
0195:
0196: /**
0197: * Fetch and lock a non-deleted record.
0198: * <p>
0199: * Lock and fetch a non-deleted record identified by a RecordHandle.
0200: * Reads data from the page into row.
0201: * <P>
0202: * <B>Locking Policy</B>
0203: * <BR>
0204: * Calls the lockRecordForRead() method of the LockingPolicy object
0205: * passed to the openContainer() call before the record is accessed.
0206: * <BR>
0207: * The page latch may be released and re-latched within this method.
0208: * This will occur if the record lock has to be waited for.
0209: *
0210: * @param handle Handle to record.
0211: * @param row Row to be filled in with data from the record.
0212: * @param validColumns a bit map of which columns in the row is to be
0213: * fetched. ValidColumns will not be changed by
0214: * RawStore.
0215: * @param forUpdate true if the intention is to update this record,
0216: * false otherwise.
0217: *
0218: * @return A handle to the record, null if the record has been deleted.
0219: *
0220: * @exception StandardException Standard Cloudscape error policy,
0221: * a statemente level exception is thrown if
0222: * the record handle does not match a record
0223: * on the page.
0224: *
0225: * @see Page#delete
0226: * @see LockingPolicy
0227: **/
0228: RecordHandle fetch(RecordHandle handle, Object[] row,
0229: FormatableBitSet validColumns, boolean forUpdate)
0230: throws StandardException;
0231:
0232: /**
0233: * Is it likely that an insert will fit on this page?
0234: * <p>
0235: * Return true if there is a good chance an insert will fit on this page,
0236: * false otherwise. If this returns true then an insert may still fail by
0237: * throwing an exception or by returning null, see insertAtSlot for details.
0238: * It is very probable that this call is much faster than the version that
0239: * takes a row. In situations where it is expected that the
0240: * majority of times a row will fit on a page this method should be used
0241: * and the null return handled from insert/insertAtSlot.
0242: *
0243: * <BR>
0244: * MT - latched
0245: *
0246: * @return true if it is likely an insert will fit on the page.
0247: *
0248: * @exception StandardException Standard exception policy.
0249: **/
0250: boolean spaceForInsert() throws StandardException;
0251:
0252: /**
0253: * will insert of this row fit on this page?
0254: * <p>
0255: * Return true if this record is guaranteed to be inserted successfully
0256: * using insert() or insertAtSlot(). This guarantee is only valid if the
0257: * following conditions are fulfilled before an insert is called with t
0258: * his row.
0259: * <UL>
0260: * <LI> The page is not unlatched
0261: * <LI> The page is not modified in any way, ie. no updates or other inserts
0262: * <LI> The row is not modified in such a way that would change its
0263: * storage size
0264: * </UL>
0265: *
0266: * <BR>
0267: * MT - latched
0268: *
0269: * @return true if insert of this row will fit on this page.
0270: *
0271: * @param row The row to check for insert.
0272: * @param validColumns bit map to interpret valid columns in row.
0273: * @param overflowThreshold The percentage of the page to use for the
0274: * insert. 100 means use 100% of the page,
0275: * 50 means use 50% of page (ie. make sure
0276: * 2 rows fit per page).
0277: *
0278: * @exception StandardException Standard exception policy.
0279: **/
0280: boolean spaceForInsert(Object[] row, FormatableBitSet validColumns,
0281: int overflowThreshold) throws StandardException;
0282:
0283: /**
0284: * Insert a record anywhere on the page.
0285: * <P>
0286: *
0287: * <B>Locking Policy</B>
0288: * <BR>
0289: * Calls the lockRecordForWrite() method of the LockingPolicy object
0290: * passed to the openContainer() call before the record is inserted.
0291: * <BR>
0292: * MT - latched
0293: *
0294: * @param row The row version of the data
0295: * @param validColumns a bit map of which columns in the row is valid.
0296: * ValidColumns will not be changed by RawStore.
0297: * @param insertFlag see values for insertFlag below.
0298: *
0299: * @return A RecordHandle representing the new record.
0300: *
0301: * @exception StandardException Standard Cloudscape error policy
0302: * @exception StandardException The container was not opened in update mode.
0303: * @exception StandardException Row cannot fit on the page or row is null.
0304: **/
0305: RecordHandle insert(Object[] row, FormatableBitSet validColumns,
0306: byte insertFlag, int overflowThreshold)
0307: throws StandardException;
0308:
0309: /**
0310: * Update the record identified by the record handle.
0311: * <p>
0312: * Update the record, the new column values are found in row[] and if
0313: * validColumns is not-null, only use the columns indicated as valid in
0314: * the bit set.
0315: * <p>
0316: * <BR>
0317: * The page latch may be released and re-latched within this method.
0318: * This will occur if the record lock has to be waited for.
0319: *
0320: * @param handle the record handle
0321: * @param row The row version of the data
0322: * @param validColumns A bit map of which columns in the row is valid.
0323: * ValidColumns will not be changed by RawStore.
0324: *
0325: * @return true if the record is updated.
0326: * False if it is not because the record is already deleted.
0327: *
0328: * @exception StandardException Standard Cloudscape error policy
0329: * @exception StandardException The container was not opened in update mode.
0330: * @exception StandardException If the record handle does not match
0331: * a record on the page.
0332: *
0333: * @see Page#updateAtSlot
0334: *
0335: * @exception StandardException Standard exception policy.
0336: **/
0337: boolean update(RecordHandle handle, Object[] row,
0338: FormatableBitSet validColumns) throws StandardException;
0339:
0340: /**
0341: * Mark the record identified by position as deleted.
0342: * <p>
0343: * Mark the record identified by position as deleted. The record may be
0344: * undeleted sometime later using undelete() by any transaction that sees
0345: * the record.
0346: * <p>
0347: * <B>Locking Policy</B>
0348: * <P>
0349: * Calls the lockRecordForWrite() method of the LockingPolicy object
0350: * passed to the openContainer() call before the record is deleted.
0351: *
0352: * <BR>
0353: * The page latch may be released and re-latched within this method.
0354: * This will occur if the record lock has to be waited for.
0355: *
0356: * @param handle record Handle to record
0357: * @param undo if logical undo may be necessary, a function pointer to
0358: * the access code where the logical undo logic resides.
0359: * Null if logical undo is not necessary.
0360: *
0361: * @return true if the record was updated.
0362: * False if it wasn't because it is already deleted.
0363: *
0364: * @exception StandardException Standard Cloudscape error policy
0365: * @exception StandardException The container was not opened in update mode.
0366: * @exception StandardException If the record handle does not match
0367: * a record on the page.
0368: *
0369: * @see Page#deleteAtSlot
0370: * @see LockingPolicy
0371: **/
0372: public boolean delete(RecordHandle handle, LogicalUndo undo)
0373: throws StandardException;
0374:
0375: /**
0376: * Move record to a page toward the beginning of the file.
0377: * <p>
0378: * As part of compressing the table records need to be moved from the
0379: * end of the file toward the beginning of the file. Only the
0380: * contiguous set of free pages at the very end of the file can
0381: * be given back to the OS. This call is used to purge the row from
0382: * the current page, insert it into a previous page, and return the
0383: * new row location
0384: * Mark the record identified by position as deleted. The record may be
0385: * undeleted sometime later using undelete() by any transaction that sees
0386: * the record.
0387: * <p>
0388: * The interface is optimized to work on a number of rows at a time,
0389: * optimally processing all rows on the page at once. The call will
0390: * process either all rows on the page, or the number of slots in the
0391: * input arrays - whichever is smaller.
0392: * <B>Locking Policy</B>
0393: * <P>
0394: * MUST be called with table locked, not locks are requested. Because
0395: * it is called with table locks the call will go ahead and purge any
0396: * row which is marked deleted. It will also use purge rather than
0397: * delete to remove the old row after it moves it to a new page. This
0398: * is ok since the table lock insures that no other transaction will
0399: * use space on the table before this transaction commits.
0400: *
0401: * <BR>
0402: * A page latch on the new page will be requested and released.
0403: *
0404: * @param slot Slot of row to move.
0405: * @param row A template to read the current row into as part
0406: * of moving it.
0407: * @param old_handle An array to be filled in by the call with the
0408: * old handles of all rows moved.
0409: * @param new_handle An array to be filled in by the call with the
0410: * new handles of all rows moved.
0411: *
0412: * @return the number of rows processed.
0413: *
0414: * @exception StandardException Standard Cloudscape error policy
0415: *
0416: * @see LockingPolicy
0417: **/
0418: public int moveRecordForCompressAtSlot(int slot, Object[] row,
0419: RecordHandle[] old_handle, RecordHandle[] new_handle)
0420: throws StandardException;
0421:
0422: /**
0423: * Fetch the number of fields in a record.
0424: * <p>
0425: * <B>Locking Policy</B>
0426: * <P>
0427: * No locks are obtained.
0428: *
0429: * <BR>
0430: * MT - latched
0431: *
0432: * @param handle record handle to deleted or non-deleted record
0433: *
0434: * @return the number of fields in the record
0435: *
0436: * @exception StandardException Standard Cloudscape error policy, a
0437: * statement level exception is thrown if the
0438: * record handle does not match a record on
0439: * the page.
0440: **/
0441: public int fetchNumFields(RecordHandle handle)
0442: throws StandardException;
0443:
0444: /**************************************************************************
0445: * Public Methods of This class: slot interface.
0446: * the following interfaces to page use the slot number
0447: * (rather than the record handle interface).
0448: **************************************************************************
0449: */
0450:
0451: /**
0452: * Get the slot number.
0453: * <p>
0454: * Get the slot number of a record on a latched page using its record
0455: * handle.
0456: *
0457: * <P><B>Note</B>
0458: * The slot number is only good for as long as the page is latched.
0459: *
0460: * <BR>
0461: * MT - latched
0462: *
0463: * @param handle the record handle
0464: *
0465: * @return the slot number
0466: *
0467: * @exception StandardException Standard Cloudscape error policy
0468: **/
0469: int getSlotNumber(RecordHandle handle) throws StandardException;
0470:
0471: /**
0472: * Get the record handle of row at slot.
0473: * <p>
0474: * Get the record handle of a record on a latched page using its slot
0475: * number.
0476: *
0477: * <BR>
0478: * MT - latched
0479: *
0480: * @param slot the slot number
0481: *
0482: * @return the record handle.
0483: *
0484: * @exception StandardException Standard Cloudscape error policy
0485: **/
0486: RecordHandle getRecordHandleAtSlot(int slot)
0487: throws StandardException;
0488:
0489: /**
0490: * Find slot for record with an id greater than the passed in identifier.
0491: * <p>
0492: * Find the slot for the first record on the page with an id greater than
0493: * the passed in identifier.
0494: *
0495: * <BR>
0496: * Returns the slot of the first record on the page with an id greater than
0497: * the one passed in. Usefulness of this functionality depends on the
0498: * client's use of the raw store interfaces. If all "new" records are
0499: * always inserted at the end of the page, and the raw store continues to
0500: * guarantee that all record id's will be allocated in increasing order on
0501: * a given page (assuming a PAGE_REUSABLE_RECORD_ID container), then a page
0502: * is always sorted in record id order. For instance current heap tables
0503: * function this way. If the client ever inserts at a particular slot
0504: * number, rather than at the "end" then the record id's will not be sorted.
0505: * <BR>
0506: * In the case where all record id's are always sorted on a page, then this
0507: * routine can be used by scan's which "lose" their position because the
0508: * row they have as a position was purged. They can reposition their scan
0509: * at the "next" row after the row that is now missing from the table.
0510: * <BR>
0511: * This method returns the record regardless of its deleted status.
0512: * <BR>
0513: * MT - latched
0514: *
0515: * @param handle record handle to find the next higher id.
0516: *
0517: * @return record id of the first record on the page with a record id
0518: * higher than the one passed in. If no such record exists,
0519: * -1 is returned.
0520: *
0521: * @exception StandardException Standard exception policy.
0522: **/
0523: int getNextSlotNumber(RecordHandle handle) throws StandardException;
0524:
0525: /**
0526: * Insert a record at the specified slot.
0527: * <p>
0528: * All records that occupy FIRST_SLOT_NUMBER to (slot - 1) are not moved.
0529: * <BR>
0530: * All records that occupy slot to (recordCount() - 1) are moved up one
0531: * slot.
0532: * <BR>
0533: * The new record is inserted at the specified slot. <BR>
0534: * If slot == FIRST_SLOT_NUMBER, then the new record will be inserted at
0535: * the first slot. <BR>
0536: * If slot == recordCount(), then the record is inserted in a new slot, no
0537: * records are moved. <BR>
0538: *
0539: * If slot is > recordCount() or if slot < FIRST_SLOT_NUMBER, an exception
0540: * will be thrown.
0541: *
0542: * <P><B>Space Policy</B><BR>
0543: * If the row will not fit on a page then:
0544: * <UL>
0545: * <LI> an exception is thrown if the page has no other rows, this is an
0546: * indication that the row could never fit on a page in this container.
0547: * <LI> null is returned if there are other rows on the page, this is an
0548: * indication that the row can potentially be inserted successfully
0549: * onto an empty page.
0550: * </UL>
0551: *
0552: * <P>
0553: * <B>Locking Policy</B>
0554: * <BR>
0555: * Calls the lockRecordForWrite() method of the LockingPolicy object passed
0556: * to the openContainer() call before the record is inserted.
0557: * <BR>
0558: * MT - latched
0559: *
0560: * @param slot The specified slot
0561: * @param row The row version of the data
0562: * @param undo if logical undo may be necessary, a function pointer
0563: * to the access code where the logical undo logic
0564: * resides. Null if logical undo is not necessary.
0565: * @param validColumns a bit map of which columns in the row is valid.
0566: * ValidColumns will not be changed by RawStore.
0567: * @param insertFlag if INSERT_UNDO_WITH_PURGE set, then the undo of this
0568: * insert will purge the row rather than mark it as
0569: * deleted, which is the default bahavior for
0570: * insertAtSlot and insert.
0571: *
0572: * @return A RecordHandle representing the new record, or null if the row
0573: * will not fit on a non-empty page.
0574: *
0575: * @exception StandardException Standard Cloudscape error policy
0576: * @exception StandardException The container was not opened in update mode.
0577: * @exception StandardException The row cannot fit on the page
0578: *
0579: * @see LogicalUndo
0580: * @see LogicalUndoable
0581: **/
0582: RecordHandle insertAtSlot(int slot, Object[] row,
0583: FormatableBitSet validColumns, LogicalUndo undo,
0584: byte insertFlag, int overflowThreshold)
0585: throws StandardException;
0586:
0587: /**
0588: * Values for insertFlag.
0589: * <p>
0590: *
0591: * INSERT_INITIAL - flag initializer
0592: *
0593: * INSERT_DEFAULT - default insert behavior, if the record does
0594: * not fit on the page where the insert
0595: * operation is called, an error will be
0596: * returned, instead of overflowing the record.
0597: *
0598: * INSERT_UNDO_WITH_PURGE - if this is set, then the undo of this insert
0599: * will purge the row rather than mark it as
0600: * deleted, which is the default behaviro for
0601: * insertAtSlot and insert.
0602: *
0603: * INSERT_CONDITIONAL - if this flag is set, then, the overflow is
0604: * conditional. The record will be overflowed
0605: * only if it exceeds the threshold specified
0606: * by the properties, or the parameter.
0607: *
0608: * INSERT_OVERFLOW - if this flag is set, then the insert
0609: * operation will overflow the record if it does
0610: * not fit on the page.
0611: *
0612: * INSERT_FOR_SPLIT - a record is being updated that causes new
0613: * portions to be inserted *and* the last new
0614: * portion needs to point to an existing portion.
0615: *
0616: * Rules for the insert flags:
0617: * 1. If INSERT_DEFAULT is set, INSERT_CONDITIONAL and INSERT_OVERFLOW
0618: * will be ignored
0619: * 2. INSERT_UNDO_WITH_PURGE can be set with any of the other 3 flags.
0620: * 3. If INSERT_OVERFLOW is not set, INSERT_CONDITIONAL will be ignored.
0621: * But, it is not necessary to set INSERT_CONDITIONAL when setting
0622: * INSERT_OVERFLOW.
0623: * 4. If INSERT_DEFAULT, INSERT_OVERFLOW both are not set, then, default
0624: * insert action will be taken, i.e. no overflow will be allowed.
0625: **/
0626: static final byte INSERT_INITIAL = (byte) 0x00; // init the flag
0627: static final byte INSERT_DEFAULT = (byte) 0x01; // default flag
0628: static final byte INSERT_UNDO_WITH_PURGE = (byte) 0x02; // purge row on undo
0629: static final byte INSERT_CONDITIONAL = (byte) 0x04; // conditional
0630: // insert
0631: static final byte INSERT_OVERFLOW = (byte) 0x08; // insert with
0632: // possible overflow
0633: static final byte INSERT_FOR_SPLIT = (byte) 0x10; // rawstore only
0634:
0635: /**
0636: * Fetch a record located in the passed in slot.
0637: * <p>
0638: * Fetch a record located in the passed in slot and fill-in the passed in
0639: * StorebleRow and the Object columns contained within. If row
0640: * is null then the record is locked but is not fetched.
0641: * <BR>
0642: * This interface allows the caller to either return a deleted row or not.
0643: * If "ignoreDelete" is set to true, fetch the record regardless of whether
0644: * it is deleted or not (same as above fetchFromSlot). However, if
0645: * "ignoreDelete" is set to false and the and the slot correspond to a
0646: * deleted row, null is returned.
0647: * <BR>
0648: * If a non-null Qualifier list is provided then the qualifier array will
0649: * be applied to the row and the row will only be returned if the row
0650: * qualifies, otherwise null will be returned. Values in the columns of
0651: * row may or may not be altered while trying to apply the qualifiers, if
0652: * null is returned the state of the columns is undefined. If a null
0653: * Qualifier list is provided then no qualification is applied.
0654: * <BR>
0655: * If a non-null record handle is passed in, it is assumed that the record
0656: * handle corresponds to the record in the slot. If record handle is null,
0657: * a record handle will be manufactured and returned if the record is not
0658: * deleted or if "ignoreDelete" is true. This parameter is here for the
0659: * case where the caller have already manufactured the record handle for
0660: * locking or other purposes so it would make sense for the page to avoid
0661: * creating a new record handle object if possible.
0662: *
0663: *
0664: * @param rh the record handle of the row. If non-null it must
0665: * refer to the same record as the slot.
0666: * @param slot the slot number
0667: * @param row Row to be filled in with information from record.
0668: * @param fetchDesc A structure to efficiently carry a set of parameters
0669: * needed to describe the fetch, these include:
0670: *
0671: * validColumns - A bit map of which columns in the
0672: * row to be fetched. ValidColumns will not be
0673: * changed by RawStore.
0674: *
0675: * qualifier_list -
0676: * A list of Qualifiers to apply to the row to see if
0677: * the row should be returned.
0678: *
0679: * An array of qualifiers which restrict whether or not
0680: * the row should be returned by the fetch. Rows for
0681: * which any one of the qualifiers returns false are
0682: * not returned by the fetch. If null, no qualification
0683: * is done and the requested columns of the rows are
0684: * returned. Qualifiers can only reference columns
0685: * which are included in the scanColumnList. The
0686: * column id that a qualifier returns is the column id
0687: * the table, not the column id in the partial row
0688: * being returned.
0689: * qualifier_scratch_space -
0690: * An array of int's that matches the size of the
0691: * row[] array. Used to process qualifiers, if no
0692: * qualifiers are input then array need not be
0693: * input. Passed in rather than allocated so that
0694: * space can be allocated a single time in a scan.
0695: * If not passed in then raw store will allocate and
0696: * deallocate per call.
0697: *
0698: * @param ignoreDelete if true, return row regardless of whether it is
0699: * deleted or not. If false, only return non-deleted
0700: * row.
0701: *
0702: * @return A handle to the record.
0703: *
0704: * @exception StandardException Standard Cloudscape error policy
0705: *
0706: * @see LockingPolicy
0707: **/
0708: public RecordHandle fetchFromSlot(RecordHandle rh, int slot,
0709: Object[] row, FetchDescriptor fetchDesc,
0710: boolean ignoreDelete) throws StandardException;
0711:
0712: /**
0713: Fetch a single field from a deleted or non-deleted record.
0714: Fills in the passed in Object column with the field
0715: identified by fieldid if column is not null, otherwise the record
0716: is locked but not fetched.
0717: <BR>
0718: The fieldId of the first field is 0.
0719: If the fieldId is >= the number of fields on the record,
0720: column is restored to null
0721: <P>
0722: <B>Locking Policy</B>
0723: <BR>
0724: No locks are obtained.
0725: It is up to the caller to obtain the correct locks.
0726: <BR>
0727:
0728: It is guaranteed that the page latch is not released by this method
0729:
0730: @param slot is the slot number
0731: @param fieldId is the column id
0732: @param column is to be filled in with information from the record.
0733:
0734: @return the Handle to the record that is locked
0735:
0736: @exception StandardException Standard Cloudscape error policy, a
0737: statement level exception is thrown if
0738: the slot is not on the page.
0739:
0740: @see Page#fetchFromSlot
0741: @see LockingPolicy
0742: */
0743: public RecordHandle fetchFieldFromSlot(int slot, int fieldId,
0744: Object column) throws StandardException;
0745:
0746: /**
0747: * Test if a record is deleted.
0748: * <p>
0749: *
0750: * <P>
0751: * <B>Locking Policy</B>
0752: * <BR>
0753: * No locks are obtained.
0754: *
0755: * <BR>
0756: * It is guaranteed that the page latch is not released by this method
0757: *
0758: * @param slot slot of record to be tested.
0759: *
0760: * @exception StandardException Standard Cloudscape error policy, a
0761: * statement level exception is thrown if the
0762: * slot is not on the page.
0763: **/
0764: public boolean isDeletedAtSlot(int slot) throws StandardException;
0765:
0766: /**
0767: Update a field within the record, replacing its current value with
0768: the stored representation of newValue. Record is identified by slot.
0769: If the field does not exist then it is added to the record, but only if
0770: (fieldId - 1) exists.
0771:
0772: <BR><B>RESOLVE</B> right now it throws an exception if fieldId is not
0773: already on the record, not add the next one as advertised.
0774:
0775: <P>
0776: <B>Locking Policy</B>
0777: <P>
0778: Calls the lockRecordForWrite() method of the LockingPolicy object
0779: passed to the openContainer() call before the record is updated.
0780:
0781: <BR>
0782: It is guaranteed that the page latch is not released by this method
0783:
0784:
0785: @param slot is the slot number
0786: @param fieldId is the column id
0787: @param newValue has the new colum value to be stored in the record
0788: @param undo if logical undo may be necessary, a function pointer to the
0789: access code where the logical undo logic resides. Null if logical undo
0790: is not necessary.
0791:
0792: @return a Handle to the updated record.
0793:
0794: @exception StandardException Standard Cloudscape error policy, a
0795: statement level exception is thrown if
0796: the slot is not on the page, or if the
0797: record is deleted, or if the fieldId
0798: is not on the record and (fieldId - 1)
0799: does not exist.
0800:
0801: @exception StandardException
0802: The container was not opened in update mode.
0803:
0804: @see LockingPolicy
0805: @see LogicalUndo
0806: @see LogicalUndoable
0807:
0808: */
0809: public RecordHandle updateFieldAtSlot(int slot, int fieldId,
0810: Object newValue, LogicalUndo undo) throws StandardException;
0811:
0812: /**
0813: * Fetch the number of fields in a record.
0814: * <p>
0815: *
0816: * <P>
0817: * <B>Locking Policy</B>
0818: * <P>
0819: * No locks are obtained.
0820: *
0821: * <BR>
0822: * It is guaranteed that the page latch is not released by this method
0823: *
0824: * @param slot is the slot number
0825: *
0826: * @return the number of fields in the record
0827: *
0828: * @exception StandardException Standard Cloudscape error policy
0829: **/
0830: public int fetchNumFieldsAtSlot(int slot) throws StandardException;
0831:
0832: /**
0833: Mark the record identified by slot as deleted or undeleted according to the
0834: delete flag.
0835:
0836:
0837: */
0838: /**
0839: * Mark the record at slot as deleted or undeleted according to delete flag.
0840: * <p>
0841: *
0842: * <P>
0843: * <B>Locking Policy</B>
0844: * <P>
0845: * Calls the lockRecordForWrite() method of the LockingPolicy object passed
0846: * to the openContainer() call before the record is deleted. If record
0847: * already deleted, and an attempt is made to delete it, an exception is
0848: * thrown. If record not deleted, and an attempt is made to undelete it,
0849: * an exception is thrown.
0850: *
0851: * <BR>
0852: * MT - latched
0853: *
0854: * @return a Handle to the deleted/undeleted record.
0855: *
0856: * @param slot is the slot number
0857: * @param delete true if this record is to be deleted false if this
0858: * deleted record is to be marked undeleted
0859: * @param undo if logical undo may be necessary, a function pointer to
0860: * the access code where the logical undo logic resides.
0861: * Null if logical undo is not necessary.
0862: *
0863: * @exception StandardException Standard Cloudscape error policy
0864: * @exception StandardException The container was not opened in update mode.
0865: * @exception StandardException A statement level exception is thrown when
0866: * trying to delete an already deleted record,
0867: * or undelete a not deleted record.
0868: *
0869: * @exception StandardException A statement level exception is thrown if
0870: * the slot is not on the page.
0871: *
0872: * @see LockingPolicy
0873: * @see Page#delete
0874: * @see LogicalUndo
0875: * @see LogicalUndoable
0876: *
0877: **/
0878: public RecordHandle deleteAtSlot(int slot, boolean delete,
0879: LogicalUndo undo) throws StandardException;
0880:
0881: /**
0882: * Purge the row(s) from page.
0883: * <p>
0884: * Purge the row(s) from page, get rid of the row(s) and slot(s) -
0885: * <B>USE WITH CAUTION</B>,
0886: * please see entire description of this operation before attempting to
0887: * use this.
0888: *
0889: * Starting from the specified slot, n rows will be purged. That is, rows
0890: * that occupies from slot to slot+n-1 will be purged from the page.
0891: *
0892: * <P>
0893: * <B>Locking Policy</B>
0894: * <P>
0895: * Calls the lockRecordForWrite() method of the LockingPolicy object passed
0896: * to the openContainer() call before the records are purged.
0897: * <P>
0898: *
0899: * <B>NOTE : CAVEAT</B><BR>
0900: * This operation will physically get rid of the row from the page, so if a
0901: * subsequent operation on this page uses a slot that has been purged, then
0902: * the undo of this operation will fail. It is only safe to use this
0903: * operation if the caller knows that it has exclusive access to the page
0904: * for the duration of the transaction, i.e, effectively holding a page
0905: * lock on the page
0906: * <P>
0907: * <B>NOTE</B><BR>
0908: * Outstanding handles to purged rows are no longer valid, accessing them
0909: * will cause an exception to be thrown.
0910: *
0911: * <BR>
0912: *<B>NOTE : Data Logging for Purges</B><BR>
0913: * needDataLogged is used to specify whether data is required to be
0914: * logged for purge operatios. Data Logging is required
0915: * Only if the row can be reused or required for key search if a purge is
0916: * rolled back;(rollback can occur if the system crashes in the middle of
0917: * purges or some unexpected error condiditions rolled back.
0918: * For example:
0919: * 1)Btree expects the data to be there if a purge is rolled back;
0920: * needDataLogged=true
0921: * 2)Heaps does not care if data exist because only operation that can occur
0922: * on a row whose purge rolled back is purging again.(needDataLogged=false)
0923: *
0924: * MT - latched
0925: *
0926: *
0927: * @param slot the starting slot number
0928: * @param numpurges number of slots to purge. If <= 0,
0929: * just returns as a no-op.
0930: * @param needDataLogged if set to true data is logged for purges else
0931: * only headers.
0932: *
0933: * @exception StandardException Standard Cloudscape error policy
0934: * @see LockingPolicy
0935: **/
0936: public void purgeAtSlot(int slot, int numpurges,
0937: boolean needDataLogged) throws StandardException;
0938:
0939: /**
0940: * move rows from one page to another, purging in the process.
0941: * <p>
0942: *
0943: * Move from this page slot[src_slot] to slot[src_slot+num_rows-1] to
0944: * destPage slot[dest_slot] to slot[dest_slot + num_rows - 1], in that
0945: * order. Both this page and destPage must be latched and from the same
0946: * container with the same page and record format.
0947: *
0948: * <BR>Slot[src_slot] to slot[src_slot+numrows-1] will be purged from this
0949: * page. RecordId on the dest page will be brand new and not in any
0950: * particular order or range. RecordId of the purged rows in this page is
0951: * never reused. Deleted and undeleted rows are copied over just the same.
0952: *
0953: * Exception will be thrown if this page does not have all the rows in the
0954: * moved over range.
0955: *
0956: * <BR><B>RESOLVE: reserve space now not copied over because in btree, a
0957: * row never shrinks. When this routine is called by heap or by some page
0958: * which will have shrunken row, then we need to add that </B>
0959: *
0960: * <BR>DestPage must have at least dest_slot row occupying slot[0] to
0961: * slot[dest_slot-1]. DestPage must have enough space to take the copied
0962: * over data. Rows that occupied slot number > dest_slot will be moved up
0963: * the slot (I.e., slot[dest_slot] -> slot[dest_slot + num_rows]).
0964: *
0965: * <BR>If this operation rolls back, this page (the src page) will get the
0966: * rows back and the dest page will purge the rows that were copied - this
0967: * is as if the rows were inserted into the dest page with
0968: * INSERT_UNDO_WITH_PURGE.
0969: *
0970: * <P>
0971: * <B>Locking Policy</B>
0972: * <P>
0973: * Calls the lockRecordForWrite() method of the LockingPolicy object
0974: * passed to the openContainer() call before the rows are copied over and
0975: * bore the records are purged. I.e, for num_rows moved, there will be
0976: * 2*num_rows calls to lockRecordForWrite.
0977: * <P>
0978: *
0979: * <P><B>Use with caution</B>
0980: * <BR>As with a normal purge, no space is reserved on this page for
0981: * rollback of the purge, so you must commit before inserting any rows
0982: * onto this page - unless those inserts are INSERT_UNDO_WITH_PURGE.
0983: *
0984: * @param destPage the page to copy to
0985: * @param src_slot start copying from this slot
0986: * @param num_rows copy and purge this many rows from this page
0987: * @param dest_slot copying into this slot of destPage
0988: *
0989: * @exception StandardException Standard Cloudscape error policy
0990: **/
0991: public void copyAndPurge(Page destPage, int src_slot, int num_rows,
0992: int dest_slot) throws StandardException;
0993:
0994: /**
0995: Update the complete record identified by the slot.
0996:
0997: <P>
0998: <B>Locking Policy</B>
0999: <P>
1000: Calls the lockRecordForWrite() method of the LockingPolicy object
1001: passed to the openContainer() call before the record is undeleted.
1002: If record already deleted, an exception is thrown.
1003:
1004: <BR>
1005: It is guaranteed that the page latch is not released by this method
1006:
1007: @return a Handle to the updated record.
1008: @param slot is the slot number
1009: @param validColumns a bit map of which columns in the row is valid.
1010: ValidColumns will not be changed by RawStore.
1011:
1012: @exception StandardException Standard Cloudscape error policy
1013: @exception StandardException The container was not opened in update mode.
1014: @exception StandardException if the slot is not on the page.
1015:
1016: @see Page#update
1017: */
1018: RecordHandle updateAtSlot(int slot, Object[] row,
1019: FormatableBitSet validColumns) throws StandardException;
1020:
1021: /*
1022: Page operations
1023: */
1024:
1025: /**
1026: Unlatch me, the page is exclusivly latched by its current user until
1027: this method call is made.
1028: <BR>
1029: After using this method the caller must throw away the
1030: reference to the Page object, e.g.
1031: <PRE>
1032: ref.unlatch();
1033: ref = null;
1034: </PRE>
1035: <BR>
1036: The page will be released automatically at the close of the
1037: container if this method is not called explictly.
1038:
1039: <BR>
1040: MT - latched
1041:
1042: */
1043: public void unlatch();
1044:
1045: /**
1046: Return the number of records on the page. The returned count includes rows that are deleted,
1047: i.e. it is the same as the number of slots on the page.
1048:
1049: <BR>
1050: MT - latched
1051:
1052: @exception StandardException Standard Cloudscape error policy
1053: */
1054:
1055: public int recordCount() throws StandardException;
1056:
1057: /**
1058: Return the number of records on this page that are <B> not </B> marked as deleted.
1059:
1060: <BR>
1061: MT - latched
1062:
1063: @exception StandardException Standard Cloudscape error policy
1064: */
1065:
1066: public int nonDeletedRecordCount() throws StandardException;
1067:
1068: /**
1069: * Is this page/deleted row a candidate for immediate reclaim space.
1070: * <p>
1071: * Used by access methods after executing a delete on "slot_just_deleted"
1072: * to ask whether a post commit should be queued to try to reclaim space
1073: * after the delete commits.
1074: * <p>
1075: * Will return true if the number of non-deleted rows on the page is
1076: * <= "num_non_deleted_rows". For instance 0 means schedule reclaim
1077: * only if all rows are deleted, 1 if all rows but one are deleted.
1078: * <p>
1079: * Will return true if the row just deleted is either a long row or long
1080: * column. In this case doing a reclaim space on the single row may
1081: * reclaim multiple pages of free space, so better to do it now rather
1082: * than wait for all rows on page to be deleted. This case is to address
1083: * the worst case scenario of all rows with long columns, but very short
1084: * rows otherwise. In this case there could be 1000's of rows on the
1085: * main page with many gigabytes of data on overflow pages in deleted space
1086: * that would not be reclaimed until all rows on the page were deleted.
1087: *
1088: * @return true if a reclaim space should be scheduled post commit on this
1089: * page, false otherwise.
1090: *
1091: * @param num_non_deleted_rows threshold number of non-deleted rows to
1092: * schedule reclaim space.
1093: * @param slot_just_deleted row on page to check for long row/long column
1094: *
1095: * @exception StandardException Standard exception policy.
1096: **/
1097: public boolean shouldReclaimSpace(int num_non_deleted_rows,
1098: int slot_just_deleted) throws StandardException;
1099:
1100: /**
1101: Set the aux object for this page.
1102: To clear the auxObject in the page, pass in a null AuxObject.
1103: If the AuxObject has already been set, this method will
1104: call auxObjectInvalidated() on the old aux objkect and replace it with aux.
1105:
1106: <BR>
1107: MT - latched
1108:
1109: @see AuxObject
1110: **/
1111: public void setAuxObject(AuxObject aux);
1112:
1113: /**
1114: Retrieve this page's aux object, returning null if there isn't one. The reference returned
1115: must only be used while the page is latched, once unlatch is called the reference to the
1116: aux object must be discarded.
1117:
1118: <BR> MT - latched
1119:
1120: @see AuxObject
1121: **/
1122: public AuxObject getAuxObject();
1123:
1124: /**
1125: Returns true if the page is latched. Only intended to be used as a Sanity check. Callers must
1126: discard Page references once unlatch is called.
1127:
1128: <BR>
1129: MT - latched
1130: */
1131:
1132: /*
1133: * time stamp - for those implmentation that supports it
1134: */
1135:
1136: /**
1137: Set the time stamp to what is on page at this instance. No op if this
1138: page does not support time stamp.
1139:
1140: @exception StandardException Standard Cloudscape error policy.
1141: */
1142: void setTimeStamp(PageTimeStamp ts) throws StandardException;
1143:
1144: /**
1145: Return a time stamp that can be used to identify the page of this
1146: specific instance. For pages that don't support timestamp, returns
1147: null.
1148: */
1149: PageTimeStamp currentTimeStamp();
1150:
1151: /**
1152: See if timeStamp for this page is the same as the current
1153: instance of the page. Null timeStamp never equals the instance of the
1154: page.
1155:
1156: @param ts the time stamp gotten from an earlier call to this page's
1157: getTimeStamp
1158: @return true if timestamp is the same
1159: @exception StandardException Standard Cloudscape error policy.
1160:
1161: @see PageTimeStamp
1162: */
1163: boolean equalTimeStamp(PageTimeStamp ts) throws StandardException;
1164:
1165: public boolean isLatched();
1166:
1167: public static final String DIAG_PAGE_SIZE = "pageSize";
1168: public static final String DIAG_RESERVED_SPACE = "reserveSpace";
1169: public static final String DIAG_MINIMUM_REC_SIZE = "minRecSize";
1170: public static final String DIAG_BYTES_FREE = "bytesFree";
1171: public static final String DIAG_BYTES_RESERVED = "bytesReserved";
1172: public static final String DIAG_NUMOVERFLOWED = "numOverFlowed";
1173: public static final String DIAG_ROWSIZE = "rowSize";
1174: public static final String DIAG_MINROWSIZE = "minRowSize";
1175: public static final String DIAG_MAXROWSIZE = "maxRowSize";
1176: public static final String DIAG_PAGEOVERHEAD = "pageOverhead";
1177: public static final String DIAG_SLOTTABLE_SIZE = "slotTableSize";
1178: }
|