org.apache.derby.impl.store.raw.data
Class BasePage

java.lang.Object
  extended byorg.apache.derby.impl.store.raw.data.BasePage
All Implemented Interfaces:
Lockable, java.util.Observer, Page, TypedFormat
Direct Known Subclasses:
CachedPage

public abstract class BasePage
extends java.lang.Object
implements Page, Lockable, java.util.Observer, TypedFormat

This class implements all the the generic locking behaviour for a Page. It leaves method used to log and store the records up to sub-classes. It is intended that the object can represent multiple pages from different containers during its lifetime.

A page contains a set of records, which can be accessed by "slot", which defines the order of the records on the page, or by "id" which defines the identity of the records on the page. Clients access records by both slot and id, depending on their needs.

BasePage implements Observer to watch the ContainerHandle which notifies its Observers when it is closing.
MT - mutable


Field Summary
private  AuxObject auxObj
          auxiliary object MT - mutable - content dynamic : single thread required.
private  StoredRecordHeader[] headers
          In-memory slot table, array of StoredRecordHeaders.
protected  PageKey identity
          this page's identity
MT - immutable - content dynamic : single thread required
protected  boolean inClean
           
static int INIT_PAGE_OVERFLOW
           
static int INIT_PAGE_REUSE
          Init page flag.
static int INIT_PAGE_REUSE_RECORDID
           
static byte INVALID_PAGE
           
private static RecordHandle InvalidRecordHandle
           
private  LogInstant lastLog
          Instant of last log record that updated this page.
static int LOG_RECORD_DEFAULT
          Log Record flag.
static int LOG_RECORD_FOR_PURGE
           
static int LOG_RECORD_FOR_UPDATE
           
private  Latch myLatch
          LockManager held latch during exclusive access.
private  int nestedLatch
          Count of times a latch is held nested during an abort
protected  BaseContainerHandle owner
          Page owner during exclusive access.
private  byte pageStatus
          Status of the page
private  long pageVersion
          Version of the page.
protected  boolean preLatch
          Used to determine latch state of a page.
private  int recordCount
           
static byte VALID_PAGE
          Values for pageStatus flag page goes thru the following transition: VALID_PAGE <-> deallocated page -> free page <-> VALID_PAGE deallocated and free page are both INVALID_PAGE as far as BasePage is concerned.
 
Fields inherited from interface org.apache.derby.iapi.store.raw.Page
DIAG_BYTES_FREE, DIAG_BYTES_RESERVED, DIAG_MAXROWSIZE, DIAG_MINIMUM_REC_SIZE, DIAG_MINROWSIZE, DIAG_NUMOVERFLOWED, DIAG_PAGE_SIZE, DIAG_PAGEOVERHEAD, DIAG_RESERVED_SPACE, DIAG_ROWSIZE, DIAG_SLOTTABLE_SIZE, FIRST_SLOT_NUMBER, INSERT_CONDITIONAL, INSERT_DEFAULT, INSERT_FOR_SPLIT, INSERT_INITIAL, INSERT_OVERFLOW, INSERT_UNDO_WITH_PURGE, INVALID_SLOT_NUMBER
 
Constructor Summary
protected BasePage()
          Create a new, empty page.
 
Method Summary
abstract  boolean allowInsert()
          Returns false if an insert is not to be allowed in the page.
abstract  int appendOverflowFieldHeader(DynamicByteArrayOutputStream logBuffer, RecordHandle overflowHandle)
          Append an overflow pointer to a partly logged row, to point to a long column that just been logged.
protected  long bumpPageVersion()
          increment the version by one and return the new version.
protected  void bumpRecordCount(int number)
           
private  void checkSlotOnPage(int slot)
          Is the given slot number on the page?
protected  void cleanPageForReuse()
          Initialized this page for reuse or first use
 void clearIdentity()
           
protected  void clearLastLogInstant()
           
protected abstract  void compactRecord(RawTransaction t, int slot, int recordId)
          Subclass implementation of compactRecord.
 void compactRecord(RecordHandle handle)
          Try to compact this record.
 void copyAndPurge(Page destPage, int src_slot, int num_rows, int dest_slot)
          move rows from one page to another, purging in the process.
private  void copyInto(BasePage srcPage, int src_slot, int num_rows, int dest_slot)
          Copy num_rows from srcPage, src_slot into this page starting at dest_slot.
 void deallocatePage()
          Mark this page as being deallocated
 boolean delete(RecordHandle handle, LogicalUndo undo)
          Mark the record identified by position as deleted.
 RecordHandle deleteAtSlot(int slot, boolean delete, LogicalUndo undo)
          Mark the record at slot as deleted or undeleted according to delete flag.
abstract  void doUpdateAtSlot(RawTransaction t, int slot, int id, java.lang.Object[] row, FormatableBitSet validColumns)
           
abstract  boolean entireRecordOnPage(int slot)
          Returns true if the entire record of that slot fits inside of this page.
 RecordHandle fetch(RecordHandle handle, java.lang.Object[] row, FormatableBitSet validColumns, boolean forUpdate)
           Lock the record (according to the locking policy) If the record is deleted then return null.
 RecordHandle fetchFieldFromSlot(int slot, int fieldId, java.lang.Object column)
          Fetch a single field from a deleted or non-deleted record.
 RecordHandle fetchFromSlot(RecordHandle rh, int slot, java.lang.Object[] row, FetchDescriptor fetchDesc, boolean ignoreDelete)
          Fetch a record located in the passed in slot.
 int fetchNumFields(RecordHandle handle)
          Fetch the number of fields in a record.
 int fetchNumFieldsAtSlot(int slot)
          Fetch the number of fields in a record.
protected  void fillInIdentity(PageKey key)
           
private  int findNextRecordById(int recordId)
          Find the slot for the first record on the page with an id greater than the passed in identifier.
 int findRecordById(int recordId, int slotHint)
          Find the slot for the record with the passed in identifier.
 AuxObject getAuxObject()
          Get the aux object.
 StoredRecordHeader getHeaderAtSlot(int slot)
           
 java.lang.Object getIdentity()
          OK to hand object outside to cache..
 RecordHandle getInvalidRecordHandle()
          Return an invalid record handle.
 LogInstant getLastLogInstant()
           
protected abstract  BasePage getNewOverflowPage()
           
 int getNextSlotNumber(RecordHandle handle)
          Find slot for record with an id greater than the passed in identifier.
abstract  BasePage getOverflowPageForInsert(int slot, java.lang.Object[] row, FormatableBitSet validColumns, int startColumn)
           
 PageKey getPageId()
          Get the Page identifer
MT - RESOLVE
 long getPageNumber()
          Return the page number of this page.
 byte getPageStatus()
          Get the page status, one of the values in the above page status flag
 long getPageVersion()
          Return the current page version.
 RecordHandle getRecordHandle(int recordId)
          Get a record handle from a previously stored record id.
 RecordHandle getRecordHandleAtSlot(int slot)
          Get the record handle of row at slot.
abstract  int getRecordLength(int slot)
          Get the stored length of a record.
abstract  int getReservedCount(int slot)
          Return the total number of bytes reserved by the record at this slot.
 int getSlotNumber(RecordHandle handle)
          Get the slot number.
abstract  int getTotalSpace(int slot)
          Return the total number of bytes used, reserved, or wasted by the record at this slot.
protected  void initialize()
          Initialized the BasePage.
protected  void initializeHeaders(int numRecords)
          Must be called by a sub-class before calling setHeaderAtSlot.
 void initPage(int initFlag, long pageOffset)
          Mark this page as being allocated and initialize it to a pristine page
abstract  void initPage(LogInstant instant, byte status, int recordId, boolean overflow, boolean reuse)
          initialize a page for the first time or for reuse All subtypes are expected to overwrite this method if it has something to clean up
 RecordHandle insert(java.lang.Object[] row, FormatableBitSet validColumns, byte insertFlag, int overflowThreshold)
          Insert a record anywhere on the page.
 RecordHandle insertAllowOverflow(int slot, java.lang.Object[] row, FormatableBitSet validColumns, int startColumn, byte insertFlag, int overflowThreshold, RecordHandle nextPortionHandle)
          Insert a row allowing overflow.
 RecordHandle insertAtSlot(int slot, java.lang.Object[] row, FormatableBitSet validColumns, LogicalUndo undo, byte insertFlag, int overflowThreshold)
          Insert a record at the specified slot.
protected  RecordHandle insertLongColumn(BasePage mainChainPage, LongColumnException lce, byte insertFlag)
          When we update a column, it turned into a long column.
protected  RecordHandle insertNoOverflow(int slot, java.lang.Object[] row, FormatableBitSet validColumns, LogicalUndo undo, byte insertFlag, int overflowThreshold)
           
protected abstract  int internalDeletedRecordCount()
          get record count without checking for latch
protected  int internalNonDeletedRecordCount()
          get record count without checking for latch
 boolean isDeletedAtSlot(int slot)
          Test if a record is deleted.
protected  boolean isDeletedOnPage(int slot)
           
 boolean isLatched()
           
abstract  boolean isOverflowPage()
          Return true if the page is an overflow page, false if not.
 boolean lockAttributes(int flag, java.util.Hashtable attributes)
          This lockable wants to participate in the Virtual Lock table.
 boolean lockerAlwaysCompatible()
          Is another request compatible, no never.
 void lockEvent(Latch lockInfo)
          Latch me.
abstract  void logColumn(int slot, int fieldId, java.lang.Object column, DynamicByteArrayOutputStream out, int overflowThreshold)
          Log a to be stored column.
abstract  void logField(int slot, int fieldNumber, java.io.OutputStream out)
          Log a currently stored field.
abstract  int logLongColumn(int slot, int recordId, java.lang.Object column, DynamicByteArrayOutputStream out)
          Log a to be stored long column.
abstract  void logRecord(int slot, int flag, int recordId, FormatableBitSet validColumns, java.io.OutputStream out, RecordHandle headRowHandle)
          Log a currently stored record to the output stream.
abstract  int logRow(int slot, boolean forInsert, int recordId, java.lang.Object[] row, FormatableBitSet validColumns, DynamicByteArrayOutputStream out, int startColumn, byte insertFlag, int realStartColumn, int realSpaceOnPage, int overflowThreshold)
          Log the row that will be stored at the given slot to the given OutputStream.
 RecordHandle makeRecordHandle(int recordHandleConstant)
          Return a record handle for the given constant record id.
static RecordHandle MakeRecordHandle(PageKey pkey, int recordHandleConstant)
           
abstract  int newRecordId()
          Create a new record identifier.
protected abstract  int newRecordId(int recordId)
          Create a new record identifier, the passed in one is the last one created.
abstract  int newRecordIdAndBump()
          Create a new record identifier, and bump to next recordid.
 int nonDeletedRecordCount()
          Return the number of records on this page that are not marked as deleted.
abstract  void preDirty()
          The page or its header is about to be modified.
 void purgeAtSlot(int slot, int numpurges, boolean needDataLogged)
          Purge one or more rows on a non-overflow page.
abstract  void purgeRecord(LogInstant instant, int slot, int recordId)
          Purge a record from the page.
protected abstract  void purgeRowPieces(RawTransaction t, int slot, RecordHandle headRowHandle, boolean needDataLogged)
          Purge all the overflow columns and overflow rows of the record at slot.
 int recordCount()
          Return the number of records on the page.
 boolean recordExists(RecordHandle handle, boolean ignoreDelete)
          does the record still exist on the page?
abstract  StoredRecordHeader recordHeaderOnDemand(int slot)
           
protected  void releaseExclusive()
          Release the exclusive latch on the page.
protected  void removeAndShiftDown(int slot)
          Remove record at slot.
 boolean requestCompatible(java.lang.Object requestedQualifier, java.lang.Object grantedQualifier)
          Is another request compatible, no never.
abstract  void reserveSpaceForSlot(LogInstant instant, int slot, int spaceToReserve)
          Reserve the required number of bytes for the record in the specified slot.
protected abstract  void restorePortionLongColumn(OverflowInputStream fetchStream)
          Read portion of a log record at the given slot into the given byteHolder.
protected abstract  boolean restoreRecordFromSlot(int slot, java.lang.Object[] row, FetchDescriptor fetchDesc, RecordHandle rh, StoredRecordHeader recordHeader, boolean isHeadRow)
          Read the record at the given slot into the given row.
abstract  void restoreRecordFromStream(LimitObjectInput in, java.lang.Object[] row)
          Restore a storable row from a InputStream that was used to store the row after a logRecord call.
 void setAuxObject(AuxObject obj)
          Set the aux object.
abstract  void setContainerRowCount(long count)
          Set the number of rows in the container - the page uses this to decide whether it needs to aggressive set the container's row count when it changes.
 int setDeleteStatus(int slot, boolean delete)
          Mark the record at the passed in slot as deleted.
abstract  void setDeleteStatus(LogInstant instant, int slot, boolean delete)
          Set the delete status of a record from the page.
 void setExclusive(BaseContainerHandle requester)
          Get an exclusive latch on the page.
(package private)  boolean setExclusiveNoWait(BaseContainerHandle requester)
          Get an exclusive latch on the page, but only if I don't have to wait.
protected  void setHeaderAtSlot(int slot, StoredRecordHeader rh)
          Must be called by any non-abstract sub-class to initialise the slot table.
protected  void setPageStatus(byte status)
          Set page status based on passed in status flag.
abstract  void setPageStatus(LogInstant instant, byte status)
          Set the page status underneath a log record
MT - latched - page latch must be held
 void setPageVersion(long v)
          set it when the page is read from disk.
abstract  void setReservedSpace(LogInstant instant, int slot, int value)
          Set the reserved space for this row to value.
protected  StoredRecordHeader shiftUp(int low)
          Shift all records in the in-memory slot table up one slot, starting at and including the record in slot 'low' A new slot is added to accomdate the move.
abstract  void skipField(java.io.ObjectInput in)
          Skip a previously stored field written by logField or logColumn.
abstract  void skipRecord(java.io.ObjectInput in)
           
protected  java.lang.String slotTableToString()
          Debugging, print slot table information
abstract  boolean spaceForCopy(int num_rows, int[] spaceNeeded)
          Is there space for copying this many rows which takes this many bytes on the page
MT - latched, page is latched when this methods is called.
abstract  void storeField(LogInstant instant, int slot, int fieldId, java.io.ObjectInput in)
          Read a previously stored field written by logField or logColumn and store it on the data page at thge given slot with the given record identifier and field number.
abstract  void storeRecord(LogInstant instant, int slot, boolean forInsert, java.io.ObjectInput in)
          Read a previously stored record written by logRecord or logRow and store it on the data page at the given slot with the given record identifier.
abstract  boolean unfilled()
          Returns true if an insert is allowed in the page and the page is relatively unfilled - let specific implementation decide what relatively unfilled means
 void unlatch()
          Unlatch the page.
 void unlockEvent(Latch lockInfo)
          Unlatch me, only to be called from lock manager.
 void update(java.util.Observable obj, java.lang.Object arg)
          This object is set to observe the BaseContainerHandle it was obtained by, that handle will notify its observers when it is being closed.
 boolean update(RecordHandle handle, java.lang.Object[] row, FormatableBitSet validColumns)
          Update the record identified by the record handle.
 RecordHandle updateAtSlot(int slot, java.lang.Object[] row, FormatableBitSet validColumns)
          Update the complete record identified by the slot.
 RecordHandle updateFieldAtSlot(int slot, int fieldId, java.lang.Object newValue, LogicalUndo undo)
          Update a field within the record, replacing its current value with the stored representation of newValue.
abstract  void updateFieldOverflowDetails(RecordHandle handle, RecordHandle overflowHandle)
          Update the overflow pointer for a long column
MT - latched - page latch must be held
protected  void updateLastLogInstant(LogInstant instant)
           
abstract  void updateOverflowDetails(RecordHandle handle, RecordHandle overflowHandle)
          Update the overflow pointer for a long row
MT - latched - page latch must be held
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.derby.iapi.store.raw.Page
currentTimeStamp, equalTimeStamp, moveRecordForCompressAtSlot, setTimeStamp, spaceForInsert, spaceForInsert
 
Methods inherited from interface org.apache.derby.iapi.services.io.TypedFormat
getTypeFormatId
 

Field Detail

auxObj

private AuxObject auxObj
auxiliary object MT - mutable - content dynamic : single thread required. This reference is set while the page is latched and returned to callers of page while the page is latched. For correct MT behaviour it is assumed that the caller discards any reference to an auxiliary object once the page is unlatched. The reference mya be cleared while the page is latched, or while the page is being cleaned from the cache. In the latter case the cache manager ensures that only a single thread can access this object.


identity

protected PageKey identity
this page's identity
MT - immutable - content dynamic : single thread required


headers

private StoredRecordHeader[] headers
In-memory slot table, array of StoredRecordHeaders.
MT - Immutable - Content Dynamic : Single thread required.


recordCount

private int recordCount

owner

protected BaseContainerHandle owner
Page owner during exclusive access. MT - mutable : single thread required, provided by Lockable single thread required.


nestedLatch

private int nestedLatch
Count of times a latch is held nested during an abort


myLatch

private Latch myLatch
LockManager held latch during exclusive access. When this is not null, latch.getQualifier() == owner


inClean

protected boolean inClean

preLatch

protected boolean preLatch
Used to determine latch state of a page. MT - mutable There are 3 latch states for a page: UNLATCHED - (owner == null) PRELATCH - (owner != null) && preLatch LATCHED - (owner != null) && !preLatch A page may be "cleaned" while it is either UNLATCHED, or PRELATCH, but it must wait for it to be not LATCHED. A page may move from UNLATCHED to PRELATCH, while being cleaned. A page must wait for !inClean before it can move from PRELATCH to LATCHED.


lastLog

private LogInstant lastLog
Instant of last log record that updated this page.
MT - mutable : latched


pageVersion

private long pageVersion
Version of the page.
MT - mutable : single thread required - The page must be latched to access this variable or the page muts be in the noidentiy state.


pageStatus

private byte pageStatus
Status of the page


VALID_PAGE

public static final byte VALID_PAGE
Values for pageStatus flag page goes thru the following transition: VALID_PAGE <-> deallocated page -> free page <-> VALID_PAGE deallocated and free page are both INVALID_PAGE as far as BasePage is concerned. When a page is deallocated, it transitioned from VALID to INVALID. When a page is allocated, it trnasitioned from INVALID to VALID.

See Also:
Constant Field Values

INVALID_PAGE

public static final byte INVALID_PAGE
See Also:
Constant Field Values

INIT_PAGE_REUSE

public static final int INIT_PAGE_REUSE
Init page flag. INIT_PAGE_REUSE - set if page is being initialized for reuse INIT_PAGE_OVERFLOW - set if page will be an overflow page INIT_PAGE_REUSE_RECORDID - set if page is being reused and its record id can be reset to RecordHandle.FIRST_RECORD_ID, rather to 1+ next recordId on the page

See Also:
Constant Field Values

INIT_PAGE_OVERFLOW

public static final int INIT_PAGE_OVERFLOW
See Also:
Constant Field Values

INIT_PAGE_REUSE_RECORDID

public static final int INIT_PAGE_REUSE_RECORDID
See Also:
Constant Field Values

LOG_RECORD_DEFAULT

public static final int LOG_RECORD_DEFAULT
Log Record flag. Why the before image of this record is being logged LOG_RECORD_FOR_UPDATE - set if the record is being logged for update. LOG_RECORD_DEFAULT - for non update. LOG_RECORD_FOR_PURGE - set if the record is being logged for purges and no data required to ve logged. The other cases (copy, purge, delete), we don't need to distinguish, leave no bit set.

See Also:
Constant Field Values

LOG_RECORD_FOR_UPDATE

public static final int LOG_RECORD_FOR_UPDATE
See Also:
Constant Field Values

LOG_RECORD_FOR_PURGE

public static final int LOG_RECORD_FOR_PURGE
See Also:
Constant Field Values

InvalidRecordHandle

private static final RecordHandle InvalidRecordHandle
Constructor Detail

BasePage

protected BasePage()
Create a new, empty page.

Method Detail

initialize

protected void initialize()
Initialized the BasePage.

Initialize the object, ie. perform work normally perfomed in constructor. Called by setIdentity() and createIdentity().


initializeHeaders

protected void initializeHeaders(int numRecords)
Must be called by a sub-class before calling setHeaderAtSlot.


fillInIdentity

protected void fillInIdentity(PageKey key)

clearIdentity

public void clearIdentity()

cleanPageForReuse

protected void cleanPageForReuse()
Initialized this page for reuse or first use


getIdentity

public java.lang.Object getIdentity()
OK to hand object outside to cache..


getInvalidRecordHandle

public final RecordHandle getInvalidRecordHandle()
Description copied from interface: Page
Return an invalid record handle.

Specified by:
getInvalidRecordHandle in interface Page
Returns:
an invalid record handle.

MakeRecordHandle

public static final RecordHandle MakeRecordHandle(PageKey pkey,
                                                  int recordHandleConstant)
                                           throws StandardException
Throws:
StandardException

makeRecordHandle

public final RecordHandle makeRecordHandle(int recordHandleConstant)
                                    throws StandardException
Description copied from interface: Page
Return a record handle for the given constant record id.

Return a record handle that doesn't represent a record but rather has a special meaning. Used for special cases like creating a key specific to the page, but not specific to a row on the page.

See RecordHandle interface for a list of "special record handles."

Specified by:
makeRecordHandle in interface Page
Parameters:
recordHandleConstant - the special recordId
Returns:
The created record handle.
Throws:
StandardException - if input is not a special record identifier.
See Also:
RecordHandle

getPageNumber

public final long getPageNumber()
Description copied from interface: Page
Return the page number of this page.

Page numbers are unique within a container and start at ContainerHandle.FIRST_PAGE_NUMBER and increment by 1 regardless of the page size.


MT - Latched

Specified by:
getPageNumber in interface Page
Returns:
The page number of this page.
See Also:
Page.getPageNumber()

getRecordHandle

public final RecordHandle getRecordHandle(int recordId)
Description copied from interface: Page
Get a record handle from a previously stored record id.

Get a record handle from a previously stored record identifier that was obtained from a RecordHandle.


MT - Latched

Specified by:
getRecordHandle in interface Page
Parameters:
recordId - previously stored recordId.
Returns:
A valid record handle or null if the record no longer exists.
See Also:
RecordHandle.getId()

getRecordHandleAtSlot

public final RecordHandle getRecordHandleAtSlot(int slot)
Description copied from interface: Page
Get the record handle of row at slot.

Get the record handle of a record on a latched page using its slot number.
MT - latched

Specified by:
getRecordHandleAtSlot in interface Page
Parameters:
slot - the slot number
Returns:
the record handle.

recordExists

public final boolean recordExists(RecordHandle handle,
                                  boolean ignoreDelete)
                           throws StandardException
Description copied from interface: Page
does the record still exist on the page?

If "ignoreDelete" is true and the record handle represents a record on the page (either marked deleted or not) return true. If "ignoreDelete" is false return true if the record handle represents a record on the page and the record is not marked as deleted. Return false otherwise.
MT - Latched

Specified by:
recordExists in interface Page
Parameters:
handle - handle of the record to look for.
ignoreDelete - if true, then routine will return true even if the row is marked deleted.
Returns:
boolean indicating if the record still exists on the page.
Throws:
StandardException - recordHandle is not a valid record handle
See Also:
Page.recordExists(org.apache.derby.iapi.store.raw.RecordHandle, boolean)

fetch

public RecordHandle fetch(RecordHandle handle,
                          java.lang.Object[] row,
                          FormatableBitSet validColumns,
                          boolean forUpdate)
                   throws StandardException
  1. Lock the record (according to the locking policy)
  2. If the record is deleted then return null. We must check after we hold the lock to ensure that we don't look at the delete status of an uncommitted record.
  3. Fetch the record
  4. Unlock the record (according to the locking policy)

Specified by:
fetch in interface Page
Parameters:
handle - Handle to record.
row - Row to be filled in with data from the record.
validColumns - a bit map of which columns in the row is to be fetched. ValidColumns will not be changed by RawStore.
forUpdate - true if the intention is to update this record, false otherwise.
Returns:
A handle to the record, null if the record has been deleted.
Throws:
StandardException - messageId equals StandardException.newException(SQLState.RECORD_VANISHED If the record identfied by handle does not exist on this page.
StandardException - Standard Cloudscape error policy
StandardException - record is not on page with message id equal to StandardException.newException(SQLState.RECORD_VANISHED.
See Also:
Page.fetch(org.apache.derby.iapi.store.raw.RecordHandle, java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet, boolean)

fetchFromSlot

public RecordHandle fetchFromSlot(RecordHandle rh,
                                  int slot,
                                  java.lang.Object[] row,
                                  FetchDescriptor fetchDesc,
                                  boolean ignoreDelete)
                           throws StandardException
Description copied from interface: Page
Fetch a record located in the passed in slot.

Fetch a record located in the passed in slot and fill-in the passed in StorebleRow and the Object columns contained within. If row is null then the record is locked but is not fetched.
This interface allows the caller to either return a deleted row or not. If "ignoreDelete" is set to true, fetch the record regardless of whether it is deleted or not (same as above fetchFromSlot). However, if "ignoreDelete" is set to false and the and the slot correspond to a deleted row, null is returned.
If a non-null Qualifier list is provided then the qualifier array will be applied to the row and the row will only be returned if the row qualifies, otherwise null will be returned. Values in the columns of row may or may not be altered while trying to apply the qualifiers, if null is returned the state of the columns is undefined. If a null Qualifier list is provided then no qualification is applied.
If a non-null record handle is passed in, it is assumed that the record handle corresponds to the record in the slot. If record handle is null, a record handle will be manufactured and returned if the record is not deleted or if "ignoreDelete" is true. This parameter is here for the case where the caller have already manufactured the record handle for locking or other purposes so it would make sense for the page to avoid creating a new record handle object if possible.

Specified by:
fetchFromSlot in interface Page
Parameters:
rh - the record handle of the row. If non-null it must refer to the same record as the slot.
slot - the slot number
row - Row to be filled in with information from record.
fetchDesc - A structure to efficiently carry a set of parameters needed to describe the fetch, these include: validColumns - A bit map of which columns in the row to be fetched. ValidColumns will not be changed by RawStore. qualifier_list - A list of Qualifiers to apply to the row to see if the row should be returned. An array of qualifiers which restrict whether or not the row should be returned by the fetch. Rows for which any one of the qualifiers returns false are not returned by the fetch. If null, no qualification is done and the requested columns of the rows are returned. Qualifiers can only reference columns which are included in the scanColumnList. The column id that a qualifier returns is the column id the table, not the column id in the partial row being returned. qualifier_scratch_space - An array of int's that matches the size of the row[] array. Used to process qualifiers, if no qualifiers are input then array need not be input. Passed in rather than allocated so that space can be allocated a single time in a scan. If not passed in then raw store will allocate and deallocate per call.
ignoreDelete - if true, return row regardless of whether it is deleted or not. If false, only return non-deleted row.
Returns:
A handle to the record.
Throws:
StandardException - Standard Cloudscape error policy
See Also:
LockingPolicy

fetchFieldFromSlot

public final RecordHandle fetchFieldFromSlot(int slot,
                                             int fieldId,
                                             java.lang.Object column)
                                      throws StandardException
Description copied from interface: Page
Fetch a single field from a deleted or non-deleted record. Fills in the passed in Object column with the field identified by fieldid if column is not null, otherwise the record is locked but not fetched.
The fieldId of the first field is 0. If the fieldId is >= the number of fields on the record, column is restored to null

Locking Policy
No locks are obtained. It is up to the caller to obtain the correct locks.
It is guaranteed that the page latch is not released by this method

Specified by:
fetchFieldFromSlot in interface Page
Parameters:
slot - is the slot number
fieldId - is the column id
column - is to be filled in with information from the record.
Returns:
the Handle to the record that is locked
Throws:
StandardException - Standard Cloudscape error policy
See Also:
Page.fetchFieldFromSlot(int, int, java.lang.Object)

getSlotNumber

public final int getSlotNumber(RecordHandle handle)
                        throws StandardException
Description copied from interface: Page
Get the slot number.

Get the slot number of a record on a latched page using its record handle.

Note The slot number is only good for as long as the page is latched.
MT - latched

Specified by:
getSlotNumber in interface Page
Parameters:
handle - the record handle
Returns:
the slot number
Throws:
StandardException - Record does not exist on this page.
See Also:
Page.getSlotNumber(org.apache.derby.iapi.store.raw.RecordHandle)

getNextSlotNumber

public final int getNextSlotNumber(RecordHandle handle)
                            throws StandardException
Description copied from interface: Page
Find slot for record with an id greater than the passed in identifier.

Find the slot for the first record on the page with an id greater than the passed in identifier.
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.
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.
This method returns the record regardless of its deleted status.
MT - latched

Specified by:
getNextSlotNumber in interface Page
Parameters:
handle - record handle to find the next higher id.
Returns:
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.
Throws:
StandardException - Record does not exist on this page.
See Also:
Page.getNextSlotNumber(org.apache.derby.iapi.store.raw.RecordHandle)

insertAtSlot

public RecordHandle insertAtSlot(int slot,
                                 java.lang.Object[] row,
                                 FormatableBitSet validColumns,
                                 LogicalUndo undo,
                                 byte insertFlag,
                                 int overflowThreshold)
                          throws StandardException
Description copied from interface: Page
Insert a record at the specified slot.

All records that occupy FIRST_SLOT_NUMBER to (slot - 1) are not moved.
All records that occupy slot to (recordCount() - 1) are moved up one slot.
The new record is inserted at the specified slot.
If slot == FIRST_SLOT_NUMBER, then the new record will be inserted at the first slot.
If slot == recordCount(), then the record is inserted in a new slot, no records are moved.
If slot is > recordCount() or if slot < FIRST_SLOT_NUMBER, an exception will be thrown.

Space Policy
If the row will not fit on a page then:

Locking Policy
Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is inserted.
MT - latched

Specified by:
insertAtSlot in interface Page
Parameters:
slot - The specified slot
row - The row version of the data
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.
validColumns - a bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
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.
Returns:
A RecordHandle representing the new record, or null if the row will not fit on a non-empty page.
Throws:
StandardException - Standard Cloudscape error policy
See Also:
Page.insertAtSlot(int, java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet, org.apache.derby.iapi.store.access.conglomerate.LogicalUndo, byte, int)

insertNoOverflow

protected RecordHandle insertNoOverflow(int slot,
                                        java.lang.Object[] row,
                                        FormatableBitSet validColumns,
                                        LogicalUndo undo,
                                        byte insertFlag,
                                        int overflowThreshold)
                                 throws StandardException
Throws:
StandardException

insert

public final RecordHandle insert(java.lang.Object[] row,
                                 FormatableBitSet validColumns,
                                 byte insertFlag,
                                 int overflowThreshold)
                          throws StandardException
Description copied from interface: Page
Insert a record anywhere on the page.

Locking Policy
Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is inserted.
MT - latched

Specified by:
insert in interface Page
Parameters:
row - The row version of the data
validColumns - a bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
insertFlag - see values for insertFlag below.
Returns:
A RecordHandle representing the new record.
Throws:
StandardException - Standard Cloudscape error policy
See Also:
Page.insert(java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet, byte, int)

insertAllowOverflow

public RecordHandle insertAllowOverflow(int slot,
                                        java.lang.Object[] row,
                                        FormatableBitSet validColumns,
                                        int startColumn,
                                        byte insertFlag,
                                        int overflowThreshold,
                                        RecordHandle nextPortionHandle)
                                 throws StandardException
Insert a row allowing overflow. If handle is supplied then the record at that hanlde will be updated to indicate it is a partial row and it has an overflow portion.

Throws:
StandardException - Standard Cloudscape error policy

insertLongColumn

protected RecordHandle insertLongColumn(BasePage mainChainPage,
                                        LongColumnException lce,
                                        byte insertFlag)
                                 throws StandardException
When we update a column, it turned into a long column. Need to change the update to effectively insert a new long column chain.

Throws:
StandardException - Unexpected exception from the implementation

preDirty

public abstract void preDirty()
The page or its header is about to be modified. Loggable actions use this to make sure the page gets cleaned if a checkpoint is taken after any log record is sent to the log stream but before the page is actually dirtied.


updateOverflowDetails

public abstract void updateOverflowDetails(RecordHandle handle,
                                           RecordHandle overflowHandle)
                                    throws StandardException
Update the overflow pointer for a long row
MT - latched - page latch must be held

Parameters:
handle - handle of the record for long row
overflowHandle - the overflow (continuation) pointer for the long row
Throws:
StandardException - Standard Cloudscape error policy

updateFieldOverflowDetails

public abstract void updateFieldOverflowDetails(RecordHandle handle,
                                                RecordHandle overflowHandle)
                                         throws StandardException
Update the overflow pointer for a long column
MT - latched - page latch must be held

Parameters:
handle - handle of the record for long row
overflowHandle - the overflow (continuation) pointer for the long row
Throws:
StandardException - Standard Cloudscape error policy

appendOverflowFieldHeader

public abstract int appendOverflowFieldHeader(DynamicByteArrayOutputStream logBuffer,
                                              RecordHandle overflowHandle)
                                       throws StandardException,
                                              java.io.IOException
Append an overflow pointer to a partly logged row, to point to a long column that just been logged.
MT - latched - page latch must be held

Parameters:
logBuffer - The buffer that contains the partially logged row.
overflowHandle - the overflow (continuation) pointer to the beginning of the long column
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

getOverflowPageForInsert

public abstract BasePage getOverflowPageForInsert(int slot,
                                                  java.lang.Object[] row,
                                                  FormatableBitSet validColumns,
                                                  int startColumn)
                                           throws StandardException
Throws:
StandardException

getNewOverflowPage

protected abstract BasePage getNewOverflowPage()
                                        throws StandardException
Throws:
StandardException

update

public final boolean update(RecordHandle handle,
                            java.lang.Object[] row,
                            FormatableBitSet validColumns)
                     throws StandardException
Description copied from interface: Page
Update the record identified by the record handle.

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.


The page latch may be released and re-latched within this method. This will occur if the record lock has to be waited for.

Specified by:
update in interface Page
Parameters:
handle - the record handle
row - The row version of the data
validColumns - A bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
Returns:
true if the record is updated. False if it is not because the record is already deleted.
Throws:
StandardException - Standard Cloudscape error policy
See Also:
Page.updateAtSlot(int, java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet)

delete

public boolean delete(RecordHandle handle,
                      LogicalUndo undo)
               throws StandardException
Description copied from interface: Page
Mark the record identified by position as deleted.

Mark the record identified by position as deleted. The record may be undeleted sometime later using undelete() by any transaction that sees the record.

Locking Policy

Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is deleted.
The page latch may be released and re-latched within this method. This will occur if the record lock has to be waited for.

Specified by:
delete in interface Page
Parameters:
handle - record Handle to record
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.
Returns:
true if the record was updated. False if it wasn't because it is already deleted.
Throws:
StandardException - Standard exception policy.
See Also:
Page.delete(org.apache.derby.iapi.store.raw.RecordHandle, org.apache.derby.iapi.store.access.conglomerate.LogicalUndo), deleteAtSlot(int, boolean, org.apache.derby.iapi.store.access.conglomerate.LogicalUndo)

updateAtSlot

public final RecordHandle updateAtSlot(int slot,
                                       java.lang.Object[] row,
                                       FormatableBitSet validColumns)
                                throws StandardException
Description copied from interface: Page
Update the complete record identified by the slot.

Locking Policy

Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is undeleted. If record already deleted, an exception is thrown.
It is guaranteed that the page latch is not released by this method

Specified by:
updateAtSlot in interface Page
Parameters:
slot - is the slot number
validColumns - a bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
Returns:
a Handle to the updated record.
Throws:
StandardException - Standard Cloudscape error policy
StandardException - StandardException.newException(SQLState.UPDATE_DELETED_RECORD if the record is already deleted
StandardException - StandardException.newException(SQLState.CONTAINER_READ_ONLY if the container is read only
See Also:
Page.updateAtSlot(int, java.lang.Object[], org.apache.derby.iapi.services.io.FormatableBitSet)

doUpdateAtSlot

public abstract void doUpdateAtSlot(RawTransaction t,
                                    int slot,
                                    int id,
                                    java.lang.Object[] row,
                                    FormatableBitSet validColumns)
                             throws StandardException
Throws:
StandardException

updateFieldAtSlot

public RecordHandle updateFieldAtSlot(int slot,
                                      int fieldId,
                                      java.lang.Object newValue,
                                      LogicalUndo undo)
                               throws StandardException
Description copied from interface: Page
Update a field within the record, replacing its current value with the stored representation of newValue. Record is identified by slot. If the field does not exist then it is added to the record, but only if (fieldId - 1) exists.
RESOLVE right now it throws an exception if fieldId is not already on the record, not add the next one as advertised.

Locking Policy

Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is updated.
It is guaranteed that the page latch is not released by this method

Specified by:
updateFieldAtSlot in interface Page
Parameters:
slot - is the slot number
fieldId - is the column id
newValue - has the new colum value to be stored in the record
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.
Returns:
a Handle to the updated record.
Throws:
StandardException - Standard Cloudscape error policy
StandardException - StandardException.newException(SQLState.UPDATE_DELETED_RECORD if the record is already deleted
StandardException - StandardException.newException(SQLState.CONTAINER_READ_ONLY if the container is read only
See Also:
Page.updateFieldAtSlot(int, int, java.lang.Object, org.apache.derby.iapi.store.access.conglomerate.LogicalUndo)

fetchNumFields

public final int fetchNumFields(RecordHandle handle)
                         throws StandardException
Description copied from interface: Page
Fetch the number of fields in a record.

Locking Policy

No locks are obtained.
MT - latched

Specified by:
fetchNumFields in interface Page
Parameters:
handle - record handle to deleted or non-deleted record
Returns:
the number of fields in the record
Throws:
StandardException - Standard exception policy.
See Also:
Page.fetchNumFields(org.apache.derby.iapi.store.raw.RecordHandle)

fetchNumFieldsAtSlot

public int fetchNumFieldsAtSlot(int slot)
                         throws StandardException
Description copied from interface: Page
Fetch the number of fields in a record.

Locking Policy

No locks are obtained.
It is guaranteed that the page latch is not released by this method

Specified by:
fetchNumFieldsAtSlot in interface Page
Parameters:
slot - is the slot number
Returns:
the number of fields in the record
Throws:
StandardException - Standard exception policy.
See Also:
Page.fetchNumFieldsAtSlot(int)

deleteAtSlot

public RecordHandle deleteAtSlot(int slot,
                                 boolean delete,
                                 LogicalUndo undo)
                          throws StandardException
Description copied from interface: Page
Mark the record at slot as deleted or undeleted according to delete flag.

Locking Policy

Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the record is deleted. If record already deleted, and an attempt is made to delete it, an exception is thrown. If record not deleted, and an attempt is made to undelete it, an exception is thrown.
MT - latched

Specified by:
deleteAtSlot in interface Page
Parameters:
slot - the slot number
delete - true if this record is to be deleted, false if this deleted record is to be marked undeleted
undo - logical undo logic if necessary
Returns:
a Handle to the deleted/undeleted record.
Throws:
StandardException - Standard exception policy.
StandardException - StandardException.newException(SQLState.UPDATE_DELETED_RECORD if an attempt to delete a record that is already deleted
StandardException - StandardException.newException(SQLState.UNDELETE_RECORD if an attempt to undelete a record that is not deleted
See Also:
Page.deleteAtSlot(int, boolean, org.apache.derby.iapi.store.access.conglomerate.LogicalUndo)

purgeAtSlot

public void purgeAtSlot(int slot,
                        int numpurges,
                        boolean needDataLogged)
                 throws StandardException
Purge one or more rows on a non-overflow page.

Specified by:
purgeAtSlot in interface Page
Parameters:
slot - the starting slot number
numpurges - number of slots to purge. If <= 0, just returns as a no-op.
needDataLogged - if set to true data is logged for purges else only headers.
Throws:
StandardException - Standard exception policy.
See Also:
Page.purgeAtSlot(int, int, boolean)

purgeRowPieces

protected abstract void purgeRowPieces(RawTransaction t,
                                       int slot,
                                       RecordHandle headRowHandle,
                                       boolean needDataLogged)
                                throws StandardException
Purge all the overflow columns and overflow rows of the record at slot.

Throws:
StandardException - Standard exception policy.

copyAndPurge

public void copyAndPurge(Page destPage,
                         int src_slot,
                         int num_rows,
                         int dest_slot)
                  throws StandardException
Description copied from interface: Page
move rows from one page to another, purging in the process.

Move from this page slot[src_slot] to slot[src_slot+num_rows-1] to destPage slot[dest_slot] to slot[dest_slot + num_rows - 1], in that order. Both this page and destPage must be latched and from the same container with the same page and record format.
Slot[src_slot] to slot[src_slot+numrows-1] will be purged from this page. RecordId on the dest page will be brand new and not in any particular order or range. RecordId of the purged rows in this page is never reused. Deleted and undeleted rows are copied over just the same. Exception will be thrown if this page does not have all the rows in the moved over range.
RESOLVE: reserve space now not copied over because in btree, a row never shrinks. When this routine is called by heap or by some page which will have shrunken row, then we need to add that
DestPage must have at least dest_slot row occupying slot[0] to slot[dest_slot-1]. DestPage must have enough space to take the copied over data. Rows that occupied slot number > dest_slot will be moved up the slot (I.e., slot[dest_slot] -> slot[dest_slot + num_rows]).
If this operation rolls back, this page (the src page) will get the rows back and the dest page will purge the rows that were copied - this is as if the rows were inserted into the dest page with INSERT_UNDO_WITH_PURGE.

Locking Policy

Calls the lockRecordForWrite() method of the LockingPolicy object passed to the openContainer() call before the rows are copied over and bore the records are purged. I.e, for num_rows moved, there will be 2*num_rows calls to lockRecordForWrite.

Use with caution
As with a normal purge, no space is reserved on this page for rollback of the purge, so you must commit before inserting any rows onto this page - unless those inserts are INSERT_UNDO_WITH_PURGE.

Specified by:
copyAndPurge in interface Page
Parameters:
destPage - the page to copy to
src_slot - start copying from this slot
num_rows - copy and purge this many rows from this page
dest_slot - copying into this slot of destPage
Throws:
StandardException - Standard exception policy.
See Also:
Page.copyAndPurge(org.apache.derby.iapi.store.raw.Page, int, int, int)

unlatch

public void unlatch()
Unlatch the page.

Specified by:
unlatch in interface Page
See Also:
Page.unlatch()

isLatched

public boolean isLatched()
Specified by:
isLatched in interface Page
See Also:
Page.isLatched()

recordCount

public final int recordCount()
Description copied from interface: Page
Return the number of records on the page. The returned count includes rows that are deleted, i.e. it is the same as the number of slots on the page.
MT - latched

Specified by:
recordCount in interface Page
See Also:
Page.recordCount()

internalDeletedRecordCount

protected abstract int internalDeletedRecordCount()
get record count without checking for latch


internalNonDeletedRecordCount

protected int internalNonDeletedRecordCount()
get record count without checking for latch


nonDeletedRecordCount

public int nonDeletedRecordCount()
Description copied from interface: Page
Return the number of records on this page that are not marked as deleted.
MT - latched

Specified by:
nonDeletedRecordCount in interface Page
See Also:
Page.nonDeletedRecordCount()

isDeletedOnPage

protected final boolean isDeletedOnPage(int slot)

isDeletedAtSlot

public boolean isDeletedAtSlot(int slot)
                        throws StandardException
Description copied from interface: Page
Test if a record is deleted.

Locking Policy
No locks are obtained.
It is guaranteed that the page latch is not released by this method

Specified by:
isDeletedAtSlot in interface Page
Parameters:
slot - slot of record to be tested.
Throws:
StandardException - Standard exception policy.
See Also:
Page.isDeletedAtSlot(int)

setAuxObject

public void setAuxObject(AuxObject obj)
Set the aux object.
MT - single thread required. Calls via the Page interface will have the page latched, thus providing single threadedness. Otherwise calls via this class are only made when the class has no-identity, thus only a single thread can see the object.

Specified by:
setAuxObject in interface Page
See Also:
Page.setAuxObject(org.apache.derby.iapi.store.raw.AuxObject)

getAuxObject

public AuxObject getAuxObject()
Get the aux object.
MT - latched - It is required the caller throws away the returned reference when the page is unlatched.

Specified by:
getAuxObject in interface Page
See Also:
Page.getAuxObject()

lockEvent

public void lockEvent(Latch lockInfo)
Latch me.
MT - single thread required (methods of Lockable)

Specified by:
lockEvent in interface Lockable
See Also:
Lockable.lockEvent(org.apache.derby.iapi.services.locks.Latch)

requestCompatible

public boolean requestCompatible(java.lang.Object requestedQualifier,
                                 java.lang.Object grantedQualifier)
Is another request compatible, no never.
MT - single thread required (methods of Lockable)

Specified by:
requestCompatible in interface Lockable
See Also:
Lockable.requestCompatible(java.lang.Object, java.lang.Object)

lockerAlwaysCompatible

public boolean lockerAlwaysCompatible()
Is another request compatible, no never.
MT - single thread required (methods of Lockable)

Specified by:
lockerAlwaysCompatible in interface Lockable
See Also:
Lockable.requestCompatible(java.lang.Object, java.lang.Object)

unlockEvent

public void unlockEvent(Latch lockInfo)
Unlatch me, only to be called from lock manager.
MT - single thread required (methods of Lockable)

Specified by:
unlockEvent in interface Lockable
See Also:
Lockable.requestCompatible(java.lang.Object, java.lang.Object)

update

public void update(java.util.Observable obj,
                   java.lang.Object arg)
This object is set to observe the BaseContainerHandle it was obtained by, that handle will notify its observers when it is being closed. In that case we will release the latch on the page held by that container.
MT - latched

Specified by:
update in interface java.util.Observer
See Also:
Observer.update(java.util.Observable, java.lang.Object)

getPageId

public PageKey getPageId()
Get the Page identifer
MT - RESOLVE


setExclusive

public void setExclusive(BaseContainerHandle requester)
                  throws StandardException
Get an exclusive latch on the page.
MT - thread safe

Throws:
StandardException - Standard Cloudscape policy.

setExclusiveNoWait

boolean setExclusiveNoWait(BaseContainerHandle requester)
                     throws StandardException
Get an exclusive latch on the page, but only if I don't have to wait.
MT - thread safe

Throws:
StandardException

releaseExclusive

protected void releaseExclusive()
Release the exclusive latch on the page.
MT - latched


setHeaderAtSlot

protected final void setHeaderAtSlot(int slot,
                                     StoredRecordHeader rh)
Must be called by any non-abstract sub-class to initialise the slot table.


bumpRecordCount

protected final void bumpRecordCount(int number)

getHeaderAtSlot

public final StoredRecordHeader getHeaderAtSlot(int slot)

entireRecordOnPage

public abstract boolean entireRecordOnPage(int slot)
                                    throws StandardException
Returns true if the entire record of that slot fits inside of this page. Returns false if part of the record on this slot overflows to other pages, either due to long row or long column.
MT - latched

Throws:
StandardException - Standard Cloudscape error policy

recordHeaderOnDemand

public abstract StoredRecordHeader recordHeaderOnDemand(int slot)

checkSlotOnPage

private final void checkSlotOnPage(int slot)
                            throws StandardException
Is the given slot number on the page?
MT - latched

Throws:
StandardException

setDeleteStatus

public int setDeleteStatus(int slot,
                           boolean delete)
                    throws StandardException,
                           java.io.IOException
Mark the record at the passed in slot as deleted. return code comes from StoredRecordHeader class: return 1, if delete status from not deleted to deleted return -1, if delete status from deleted to not deleted return 0, if status unchanged.
Any sub-class must call this method when deleting a record.
MT - latched

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - IO error accessing page

deallocatePage

public void deallocatePage()
                    throws StandardException
Mark this page as being deallocated

Throws:
StandardException - Cloudscape Standard error policy

initPage

public void initPage(int initFlag,
                     long pageOffset)
              throws StandardException
Mark this page as being allocated and initialize it to a pristine page

Throws:
StandardException - Cloudscape Standard error policy

findRecordById

public int findRecordById(int recordId,
                          int slotHint)
Find the slot for the record with the passed in identifier.
This method returns the record regardless of its deleted status.
The "slotHint" argument is a hint about what slot the record id might be in. Callers may save the last slot where the record was across latch/unlatches to the page, and then pass that slot back as a hint - if the page has not shuffled slots since the last reference then the hint will succeed and a linear search is saved. If the caller has no idea where it may be, then FIRST_SLOT_NUMBER is passed in and a linear search is performed.
MT - latched

Parameters:
recordId - record id of the record to search for.
slotHint - "hint" about which slot the record might be in.

findNextRecordById

private int findNextRecordById(int recordId)
Find the slot for the first record on the page with an id greater than the passed in identifier.
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 clients 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, 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.
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.
This method returns the record regardless of its deleted status.
MT - latched

Parameters:
recordId - 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.

copyInto

private void copyInto(BasePage srcPage,
                      int src_slot,
                      int num_rows,
                      int dest_slot)
               throws StandardException
Copy num_rows from srcPage, src_slot into this page starting at dest_slot. This is destination page of the the copy half of copy and Purge.

Returns:
An array of the new record identifiers.
Throws:
StandardException
See Also:
Page.copyAndPurge(org.apache.derby.iapi.store.raw.Page, int, int, int)

removeAndShiftDown

protected void removeAndShiftDown(int slot)
Remove record at slot.

Remove the slot at the in-memory slot table, i.e., slots from 0 to deleteSlot-1 is untouched, deleteSlot is removed from in memory slot table, deleteSlot+1 .. recordCount()-1 move to down one slot.
MT - latched


shiftUp

protected StoredRecordHeader shiftUp(int low)
Shift all records in the in-memory slot table up one slot, starting at and including the record in slot 'low' A new slot is added to accomdate the move.
MT - latched


compactRecord

public void compactRecord(RecordHandle handle)
                   throws StandardException
Try to compact this record. Deleted record are treated the same way as nondeleted record. This page must not be an overflow page. The record may already have been purged from the page.

Locking Policy

No locks are obtained.
MT - latched

NOTE : CAVEAT
This operation will physically get rid of any reserved space this record may have, or it may compact the record by merging strung out row pieces together. Since the freed reserved space is immediately usable by other transactions which latched the page, it is only safe to use this operation if the caller knows that it has exclusive access to the page for the duration of the transaction, i.e., effectively holding a page lock on the page, AND that the record has no uncommitted updates.

Parameters:
handle - Handle to deleted or non-deleted record
Throws:
StandardException - Standard Cloudscape error policy
See Also:
ContainerHandle.compactRecord(org.apache.derby.iapi.store.raw.RecordHandle)

getLastLogInstant

public final LogInstant getLastLogInstant()

clearLastLogInstant

protected final void clearLastLogInstant()

updateLastLogInstant

protected final void updateLastLogInstant(LogInstant instant)

getPageVersion

public final long getPageVersion()
Return the current page version.


bumpPageVersion

protected final long bumpPageVersion()
increment the version by one and return the new version.


setPageVersion

public final void setPageVersion(long v)
set it when the page is read from disk.
MT - single thread required - Only called while the page has no identity which requires that only a single caller can be accessing it.


setPageStatus

protected void setPageStatus(byte status)
Set page status based on passed in status flag.


getPageStatus

public byte getPageStatus()
Get the page status, one of the values in the above page status flag


restoreRecordFromSlot

protected abstract boolean restoreRecordFromSlot(int slot,
                                                 java.lang.Object[] row,
                                                 FetchDescriptor fetchDesc,
                                                 RecordHandle rh,
                                                 StoredRecordHeader recordHeader,
                                                 boolean isHeadRow)
                                          throws StandardException
Read the record at the given slot into the given row.

This reads and initializes the columns in the row array from the raw bytes stored in the page associated with the given slot. If validColumns is non-null then it will only read those columns indicated by the bit set, otherwise it will try to read into every column in row[].

If there are more columns than entries in row[] then it just stops after every entry in row[] is full.

If there are more entries in row[] than exist on disk, the requested excess columns will be set to null by calling the column's object's restoreToNull() routine (ie. ((Object) column).restoreToNull() ).

If a qualifier list is provided then the row will only be read from disk if all of the qualifiers evaluate true. Some of the columns may have been read into row[] in the process of evaluating the qualifier.
MT - latched, page is latched when this methods is called.

Parameters:
slot - the slot number
row - (out) filled in sparse row
fetchDesc - A set of information about the fetch: what columns to fetch, any qualifiers, ...
rh - the record handle for the row at top level, and is used in OverflowInputStream to lock the row for Blobs/Clobs.
isHeadRow - Is the head row portion of the row, false if a long row and the 2-N'th portion of the long row.
Returns:
false if a qualifier_list is provided and the row does not qualifier (no row read in that case), else true.
Throws:
StandardException - Standard Cloudscape error policy

restorePortionLongColumn

protected abstract void restorePortionLongColumn(OverflowInputStream fetchStream)
                                          throws StandardException,
                                                 java.io.IOException
Read portion of a log record at the given slot into the given byteHolder.
MT - latched, page is latched when this methods is called.

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

newRecordId

public abstract int newRecordId()
                         throws StandardException
Create a new record identifier.
MT - latched, page is latched when this methods is called.

Throws:
StandardException - Standard Cloudscape error policy

newRecordIdAndBump

public abstract int newRecordIdAndBump()
                                throws StandardException
Create a new record identifier, and bump to next recordid.
MT - latched, page is latched when this methods is called.

Throws:
StandardException - Standard Cloudscape error policy

newRecordId

protected abstract int newRecordId(int recordId)
                            throws StandardException
Create a new record identifier, the passed in one is the last one created. Use this method to collect and reserve multiple recordIds in one stroke. Given the same input recordId, the subclass MUST return the same recordId every time.
MT - latched, page is latched when this methods is called.

Throws:
StandardException - Standard Cloudscape error policy

spaceForCopy

public abstract boolean spaceForCopy(int num_rows,
                                     int[] spaceNeeded)
                              throws StandardException
Is there space for copying this many rows which takes this many bytes on the page
MT - latched, page is latched when this methods is called.

Throws:
StandardException - Standard Cloudscape policy.

getTotalSpace

public abstract int getTotalSpace(int slot)
                           throws StandardException
Return the total number of bytes used, reserved, or wasted by the record at this slot.
MT - latched, page is latched when this methods is called.

Throws:
StandardException - Standard Cloudscape policy.

getReservedCount

public abstract int getReservedCount(int slot)
                              throws java.io.IOException
Return the total number of bytes reserved by the record at this slot.
MT - latched, page is latched when this methods is called.

Throws:
java.io.IOException - Thrown by InputStream methods potential I/O errors

getRecordLength

public abstract int getRecordLength(int slot)
                             throws java.io.IOException
Get the stored length of a record. This must match the amount of data written by logColumn and logField.
MT - latched - page latch must be held

Throws:
java.io.IOException

restoreRecordFromStream

public abstract void restoreRecordFromStream(LimitObjectInput in,
                                             java.lang.Object[] row)
                                      throws StandardException,
                                             java.io.IOException
Restore a storable row from a InputStream that was used to store the row after a logRecord call.
MT - latched - page latch must be held

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - object exceeds the available data in the stream.

logRecord

public abstract void logRecord(int slot,
                               int flag,
                               int recordId,
                               FormatableBitSet validColumns,
                               java.io.OutputStream out,
                               RecordHandle headRowHandle)
                        throws StandardException,
                               java.io.IOException
Log a currently stored record to the output stream. The logged version of the record must be readable by storeRecord.
MT - latched - page latch must be held

Parameters:
slot - Slot number the record is stored in.
flag - LOG_RECORD_*, the reason for logging the record.
recordId - Record identifier of the record.
validColumns - which columns needs to be logged
out - Where to write the logged form.
headRowHandle - the recordHandle of the head row piece, used for post commit cleanup for update.
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

logRow

public abstract int logRow(int slot,
                           boolean forInsert,
                           int recordId,
                           java.lang.Object[] row,
                           FormatableBitSet validColumns,
                           DynamicByteArrayOutputStream out,
                           int startColumn,
                           byte insertFlag,
                           int realStartColumn,
                           int realSpaceOnPage,
                           int overflowThreshold)
                    throws StandardException,
                           java.io.IOException
Log the row that will be stored at the given slot to the given OutputStream. The logged form of the Row must be readable by storeRecord.
MT - latched - page latch must be held

Parameters:
slot - Slot number the record will be stored in.
forInsert - True if the row is being logged for an insert, false for an update.
recordId - Record identifier of the record.
row - The row version of the record.
validColumns - FormatableBitSet of which columns in row are valid, null indicates all are valid
out - Where to write the logged form.
startColumn - The first column that is being logged in this row. This is used when logging portion of long rows.
insertFlag - To indicate whether the insert would allow overflow.
realStartColumn - This is used when a long column is detected. Portion of the row may already be logged and stored in the 'out' buffer. After we log the long column, the saved buffer was passed here, and we need to continue to log the row. realStartColumn is the starting column for the continuation of the logRow operation. Pass in (-1) if realStartColumn is not significant.
realSpaceOnPage - Being used in conjunction with realStartColumn, to indicate the real free space left on the page.
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

logField

public abstract void logField(int slot,
                              int fieldNumber,
                              java.io.OutputStream out)
                       throws StandardException,
                              java.io.IOException
Log a currently stored field. The logged version of the field must be readable by storeField.
MT - latched - page latch must be held

Parameters:
slot - Slot number the record is stored in.
fieldNumber - Number of the field (starts at 0).
out - Where to write the logged form.
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

logColumn

public abstract void logColumn(int slot,
                               int fieldId,
                               java.lang.Object column,
                               DynamicByteArrayOutputStream out,
                               int overflowThreshold)
                        throws StandardException,
                               java.io.IOException
Log a to be stored column.
MT - latched - page latch must be held

Parameters:
slot - slot of the current record
fieldId - field number of the column being updated
column - column version of the field.
out - Where to write the logged form.
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

logLongColumn

public abstract int logLongColumn(int slot,
                                  int recordId,
                                  java.lang.Object column,
                                  DynamicByteArrayOutputStream out)
                           throws StandardException,
                                  java.io.IOException
Log a to be stored long column. return -1 when done.
MT - latched - page latch must be held

Parameters:
slot - slot of the current record
recordId - the id of the long column record
column - column version of the field.
out - Where to write the logged form.
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

storeRecord

public abstract void storeRecord(LogInstant instant,
                                 int slot,
                                 boolean forInsert,
                                 java.io.ObjectInput in)
                          throws StandardException,
                                 java.io.IOException
Read a previously stored record written by logRecord or logRow and store it on the data page at the given slot with the given record identifier. Any previously stored record must be replaced.
MT - latched - page latch must be held

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - Thrown by InputStream methods potential I/O errors while writing the page

storeField

public abstract void storeField(LogInstant instant,
                                int slot,
                                int fieldId,
                                java.io.ObjectInput in)
                         throws StandardException,
                                java.io.IOException
Read a previously stored field written by logField or logColumn and store it on the data page at thge given slot with the given record identifier and field number. Any previously stored field is replaced.
MT - latched - page latch must be held

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - Thrown by InputStream methods and potential I/O errors while writing the page.

reserveSpaceForSlot

public abstract void reserveSpaceForSlot(LogInstant instant,
                                         int slot,
                                         int spaceToReserve)
                                  throws StandardException,
                                         java.io.IOException
Reserve the required number of bytes for the record in the specified slot.
MT - latched - page latch must be held

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - Thrown by InputStream methods and potential I/O errors while writing the page.

skipField

public abstract void skipField(java.io.ObjectInput in)
                        throws StandardException,
                               java.io.IOException
Skip a previously stored field written by logField or logColumn.
MT - latched - page latch must be held

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - Thrown by InputStream methods

skipRecord

public abstract void skipRecord(java.io.ObjectInput in)
                         throws StandardException,
                                java.io.IOException
Throws:
StandardException
java.io.IOException

setDeleteStatus

public abstract void setDeleteStatus(LogInstant instant,
                                     int slot,
                                     boolean delete)
                              throws StandardException,
                                     java.io.IOException
Set the delete status of a record from the page.
MT - latched - page latch must be held

Parameters:
slot - the slot to delete or undelete
delete - set delete status to this value
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - IO error accessing page

purgeRecord

public abstract void purgeRecord(LogInstant instant,
                                 int slot,
                                 int recordId)
                          throws StandardException,
                                 java.io.IOException
Purge a record from the page.
MT - latched - page latch must be held

Parameters:
slot - the slot to purge
recordId - the id of the record that is to be purged
Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException - Thrown by potential I/O errors while writing the page.

compactRecord

protected abstract void compactRecord(RawTransaction t,
                                      int slot,
                                      int recordId)
                               throws StandardException
Subclass implementation of compactRecord.

Throws:
StandardException - Standard Cloudscape error policy
See Also:
compactRecord(org.apache.derby.iapi.store.raw.RecordHandle)

setPageStatus

public abstract void setPageStatus(LogInstant instant,
                                   byte status)
                            throws StandardException
Set the page status underneath a log record
MT - latched - page latch must be held

Parameters:
instant - the log instant of the log record
status - the page status
Throws:
StandardException - Standard Cloudscape error policy

initPage

public abstract void initPage(LogInstant instant,
                              byte status,
                              int recordId,
                              boolean overflow,
                              boolean reuse)
                       throws StandardException
initialize a page for the first time or for reuse All subtypes are expected to overwrite this method if it has something to clean up

Throws:
StandardException - Standard Cloudscape error policy

setReservedSpace

public abstract void setReservedSpace(LogInstant instant,
                                      int slot,
                                      int value)
                               throws StandardException,
                                      java.io.IOException
Set the reserved space for this row to value.

Throws:
StandardException - Standard Cloudscape error policy
java.io.IOException

isOverflowPage

public abstract boolean isOverflowPage()
Return true if the page is an overflow page, false if not. For implementation that don't have overflow pages, return false.


allowInsert

public abstract boolean allowInsert()
Returns false if an insert is not to be allowed in the page.


unfilled

public abstract boolean unfilled()
Returns true if an insert is allowed in the page and the page is relatively unfilled - let specific implementation decide what relatively unfilled means


setContainerRowCount

public abstract void setContainerRowCount(long count)
Set the number of rows in the container - the page uses this to decide whether it needs to aggressive set the container's row count when it changes.


slotTableToString

protected java.lang.String slotTableToString()
Debugging, print slot table information


lockAttributes

public boolean lockAttributes(int flag,
                              java.util.Hashtable attributes)
This lockable wants to participate in the Virtual Lock table.

Specified by:
lockAttributes in interface Lockable
Parameters:
flag - use the bits in this int to decide if the user is interested in this kind of lockable object. The bits are defined in VirtualLockTable. For instance, the user may only ask for TABLE_AND_ROWLOCK and if this is not a table or row lock, then don't paritipate.
attributes - if this decides to participate, put all relavent attributes into the Hashtable. The complete list of interesting attributes is listed in VirtualLockTable. The following attributes must be present for all participating lockables: VirtualLockTable.LOCKNAME, VirtualLockTable.LOCKTYPE, either VirtualLockTable.CONTAINERID or VirtualLockTable.CONGLOMID,

MT - this routine must be MP safe, caller will not be single threading the lock manager.

Returns:
true if this object has diagnostic information to add to the virtual lock table. If this object either does not want to participate in the diagnostic virtual lock table or none of the attributes requested are attributes of this lock, returns false.
See Also:
VirtualLockTable

Built on Tue 2006-10-10 19:23:47+0200, from revision exported

Apache Derby V10.1 Engine Documentation - Copyright © 1997,2005 The Apache Software Foundation or its licensors, as applicable.