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

Class AllocPage

java.lang.Object

org.apache.derby.impl.store.raw.data.CachedPage

org.apache.derby.impl.store.raw.data.StoredPage

org.apache.derby.impl.store.raw.data.AllocPage

All Implemented Interfaces:

java.util.Observer, Cacheable, TypedFormat, Page

public class AllocPage
extends StoredPage

An allocation page of the file container.

This class extends a normal Stored page, with the exception that a hunk of space may be 'borrowed' by the file container to store the file header.

The borrowed space is not visible to the alloc page even though it is present in the page data array. It is accessed directly by the FileContainer. Any change made to the borrowed space is not managed or seen by the allocation page.

The reason for having this borrowed space is so that the container header does not need to have a page of its own.

Page Format
An allocation page extends a stored page, the on disk format is different from a stored page in that N bytes are 'borrowed' by the container and the page header of an allocation page will be slightly bigger than a normal stored page. This N bytes are stored between the page header and the record space.

The reason why this N bytes can't simply be a row is because it needs to be statically accessible by the container object to avoid a chicken and egg problem of the container object needing to instantiate an alloc page object before it can be objectified, and an alloc page object needing to instantiate a container object before it can be objectified. So this N bytes must be stored outside of the normal record interface yet it must be settable because only the first alloc page has this borrowed space. Other (non-first) alloc page have N == 0.

                             <-- borrowed ->
        +----------+-------------+---+---------+-------------------+-------------+--------+
        | FormatId | page header | N | N bytes | alloc extend rows | slot offset |checksum|
        +----------+-------------+---+---------+-------------------+-------------+--------+
        

N is a byte that indicates the size of the borrowed space. Once an alloc page is initialized, the value of N cannot change.

The maximum space that can be borrowed by the container is 256 bytes.

The allocation page are of the same page size as any other pages in the container. The first allocation page of the FileContainer starts at the first physical byte of the container. Subsequent allocation pages are chained via the nextAllocPageOffset. Each allocation page is expected to manage at least 1000 user pages (for 1K page size) so this chaining may not be a severe performance hit. The logical -> physical mapping of an allocation page is stored in the previous allocation page. The container object will need to maintain this mapping.

The following fields are stored in the page header

See Also:

AllocExtent

Field Summary

Fields

Modifier and Type	Field and Description
static int	FORMAT_NUMBER
static int	INIT_PAGE_OVERFLOW
static int	INIT_PAGE_REUSE Init page flag.
static int	INIT_PAGE_REUSE_RECORDID
static byte	INVALID_PAGE
static int	LOG_RECORD_DEFAULT Log Record flag.
static int	LOG_RECORD_FOR_PURGE
static int	LOG_RECORD_FOR_UPDATE
static java.lang.String	TEST_MULTIPLE_ALLOC_PAGE Extent Testing Use these strings to simulate error conditions for testing purposes.
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 class org.apache.derby.impl.store.raw.data.CachedPage

WRITE_NO_SYNC, WRITE_SYNC

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

Constructors

Constructor and Description
AllocPage()

Method Summary

Modifier and Type	Method and Description
void	addPage(org.apache.derby.impl.store.raw.data.FileContainer mycontainer, long newPageNumber, RawTransaction ntt, BaseContainerHandle userHandle) Add a page which is managed by this alloc page.
boolean	canAddFreePage(long lastAllocatedPage)
void	chainNewAllocPage(BaseContainerHandle allocHandle, long newAllocPageNum, long newAllocPageOffset)
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.
void	deallocatePage() Mark this page as being deallocated
void	deallocatePage(BaseContainerHandle userHandle, long pageNumber)
RecordHandle	deleteAtSlot(int slot, boolean delete, LogicalUndo undo) Mark the record at slot as deleted or undeleted according to delete flag.
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	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()
long	getLastPagenum()
long	getMaxPagenum()
long	getNextAllocPageNumber()
long	getNextAllocPageOffset()
int	getNextSlotNumber(RecordHandle handle) Find slot for record with an id greater than the passed in identifier.
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.
int	getSlotNumber(RecordHandle handle) Get the slot number.
int	getTypeFormatId() Return my format identifier.
void	initPage(int initFlag, long pageOffset) Mark this page as being allocated and initialize it to a pristine page
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.
boolean	isDeletedAtSlot(int slot) Test if a record is deleted.
boolean	isLast()
boolean	isLatched() Check whether the page is latched.
boolean	isRepositionNeeded(long version) Check if a B-tree scan positioned on this page needs to reposition.
RecordHandle	makeRecordHandle(int recordHandleConstant) Return a record handle for the given constant record id.
static RecordHandle	MakeRecordHandle(PageKey pkey, int recordHandleConstant)
long	nextFreePageNumber(long pnum) Return the next free page number after given page number
int	nonDeletedRecordCount() Return the number of records on this page that are not marked as deleted.
void	purgeAtSlot(int slot, int numpurges, boolean needDataLogged) Purge one or more rows on a non-overflow page.
static void	ReadContainerInfo(byte[] containerInfo, byte[] epage) Extract the container information from epage.
int	recordCount() Return the number of records on the page.
boolean	recordExists(RecordHandle handle, boolean ignoreDelete) does the record still exist on the page?
void	setAuxObject(AuxObject obj) Set the aux object.
int	setDeleteStatus(int slot, boolean delete) Mark the record at the passed in slot as deleted.
void	setPageVersion(long v) set it when the page is read from disk.
void	setRepositionNeeded() Set a hint in this page to make B-tree scans positioned on it reposition before they continue.
boolean	shouldReclaimSpace(int num_non_deleted_rows, int slot_just_deleted) Is this page/deleted row a candidate for immediate reclaim space.
java.lang.String	toString() debugging, print this page
void	unlatch() Unlatch the page.
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.
RecordHandle	updateAtSlot(int slot, java.lang.Object[] row, FormatableBitSet validColumns) Update the complete record identified by the slot.
static void	WriteContainerInfo(byte[] containerInfo, byte[] epage, boolean create) Write the container information into the container information area.

Methods inherited from class org.apache.derby.impl.store.raw.data.StoredPage

allowInsert, appendOverflowFieldHeader, currentTimeStamp, doUpdateAtSlot, entireRecordOnPage, equalTimeStamp, fetchNumFieldsAtSlot, getOverflowPageForInsert, getOverflowPageForInsert, getPageSize, getRecordLength, getReservedCount, getTotalSpace, initPage, insertAtSlot, isOverflowPage, logAction, logColumn, logField, logLongColumn, logRecord, logRow, moveRecordForCompressAtSlot, newRecordId, newRecordIdAndBump, purgeRecord, recordHeaderOnDemand, reserveSpaceForSlot, restorePortionLongColumn, restoreRecordFromStream, setDeleteStatus, setPageStatus, setReservedSpace, setTimeStamp, skipField, skipRecord, spaceForCopy, spaceForInsert, spaceForInsert, storeField, storeRecord, toUncheckedString, unfilled, updateFieldAtSlot, updateFieldOverflowDetails, updateOverflowDetails

Methods inherited from class org.apache.derby.impl.store.raw.data.CachedPage

clean, clearIdentity, createIdentity, isActuallyDirty, isDirty, preDirty, setContainerRowCount, setFactory, setIdentity

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.derby.iapi.services.cache.Cacheable

getIdentity

Field Detail

FORMAT_NUMBER

public static final int FORMAT_NUMBER

See Also:

Constant Field Values

TEST_MULTIPLE_ALLOC_PAGE

public static final java.lang.String TEST_MULTIPLE_ALLOC_PAGE

Extent Testing Use these strings to simulate error conditions for testing purposes.

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

Constructor Detail

AllocPage

public AllocPage()

Method Detail

getTypeFormatId

public int getTypeFormatId()

Return my format identifier.

Specified by:

getTypeFormatId in interface TypedFormat

Overrides:

getTypeFormatId in class StoredPage

Returns:

The identifier. (A UUID stuffed in an array of 16 bytes).

WriteContainerInfo

public static void WriteContainerInfo(byte[] containerInfo,
                                      byte[] epage,
                                      boolean create)
                               throws StandardException

Write the container information into the container information area.

Parameters:

containerInfo - the container information

epage - the allocation page data which may not be fully formed, but is guarenteed to be big enough to cover the area inhibited by the container info

create - if create, write out the length of the container info also. Else check to make sure epage's original container info is of the same length

Throws:

StandardException - standard Derby error policy

ReadContainerInfo

public static void ReadContainerInfo(byte[] containerInfo,
                                     byte[] epage)
                              throws StandardException

Extract the container information from epage.

Parameters:

containerInfo - where to put the extracted information

epage - the allocation page which has the container information. Epage may not be fully formed, but is guarenteed to be big enough to cover the area inhibited by the container info

Throws:

StandardException

nextFreePageNumber

public long nextFreePageNumber(long pnum)

Return the next free page number after given page number

addPage

public void addPage(org.apache.derby.impl.store.raw.data.FileContainer mycontainer,
                    long newPageNumber,
                    RawTransaction ntt,
                    BaseContainerHandle userHandle)
             throws StandardException

Add a page which is managed by this alloc page. Return the page number of the newly added page.
MT - thread aware (latched)

Parameters:

mycontainer - (future) allows the alloc page to call back to the container to grow the container by creating and syncing multiple pages at once

ntt - the nested top action that is the allocation transaction. NTT will comit before the user transaction

userHandle - the container handle that is opened by the user transaction. Use the userHandle to latch the new page so that it may remain latched after NTT is committed so the user transaction can guarentee to have an empty page

Throws:

StandardException - If the page cannot be added

deallocatePage

public void deallocatePage(BaseContainerHandle userHandle,
                           long pageNumber)
                    throws StandardException

Throws:

StandardException

canAddFreePage

public boolean canAddFreePage(long lastAllocatedPage)

getNextAllocPageOffset

public long getNextAllocPageOffset()

chainNewAllocPage

public void chainNewAllocPage(BaseContainerHandle allocHandle,
                              long newAllocPageNum,
                              long newAllocPageOffset)
                       throws StandardException

Throws:

StandardException

getNextAllocPageNumber

public long getNextAllocPageNumber()

isLast

public boolean isLast()

getLastPagenum

public long getLastPagenum()

getMaxPagenum

public long getMaxPagenum()

toString

public java.lang.String toString()

Description copied from class: StoredPage

debugging, print this page

Overrides:

toString in class StoredPage

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)

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 Derby 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 Derby 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)

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 Derby 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 Derby error policy

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 Derby 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)

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)

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)

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 final boolean isLatched()

Check whether the page is latched.

Specified by:

isLatched in interface Page

Returns:

true if the page is latched, false otherwise

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()

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()

shouldReclaimSpace

public boolean shouldReclaimSpace(int num_non_deleted_rows,
                                  int slot_just_deleted)
                           throws StandardException

Is this page/deleted row a candidate for immediate reclaim space.

Used by access methods after executing a delete on "slot_just_deleted" to ask whether a post commit should be queued to try to reclaim space after the delete commits.

Will return true if the number of non-deleted rows on the page is <= "num_non_deleted_rows". For instance 0 means schedule reclaim only if all rows are deleted, 1 if all rows but one are deleted.

Will return true if the row just deleted is either a long row or long column. In this case doing a reclaim space on the single row may reclaim multiple pages of free space, so better to do it now rather than wait for all rows on page to be deleted. This case is to address the worst case scenario of all rows with long columns, but very short rows otherwise. In this case there could be 1000's of rows on the main page with many gigabytes of data on overflow pages in deleted space that would not be reclaimed until all rows on the page were deleted.

Specified by:

shouldReclaimSpace in interface Page

Parameters:

num_non_deleted_rows - threshold number of non-deleted rows to schedule reclaim space.

slot_just_deleted - row on page to check for long row/long column

Returns:

true if a reclaim space should be scheduled post commit on this page, false otherwise.

Throws:

StandardException - Standard exception policy.

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()

setRepositionNeeded

public void setRepositionNeeded()

Set a hint in this page to make B-tree scans positioned on it reposition before they continue. This method is typically called when rows are removed from a B-tree leaf page (for instance in a page split).

Specified by:

setRepositionNeeded in interface Page

isRepositionNeeded

public boolean isRepositionNeeded(long version)

Check if a B-tree scan positioned on this page needs to reposition.

Specified by:

isRepositionNeeded in interface Page

Parameters:

version - the last version on which the B-tree scan had a valid position on this page

Returns:

true if a repositioning is needed because the row on the current position may have been removed from this page after the specified version; false otherwise

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 final PageKey getPageId()

Get the Page identifer
MT - RESOLVE

getHeaderAtSlot

public final StoredRecordHeader getHeaderAtSlot(int slot)

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 Derby error policy

java.io.IOException - IO error accessing page

deallocatePage

public void deallocatePage()
                    throws StandardException

Mark this page as being deallocated

Throws:

StandardException - Derby 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 - Derby 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.

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 Derby error policy

See Also:

ContainerHandle.compactRecord(org.apache.derby.iapi.store.raw.RecordHandle)

getLastLogInstant

public final LogInstant getLastLogInstant()

getPageVersion

public final long getPageVersion()

Return the current page version.

Specified by:

getPageVersion in interface Page

Returns:

page version number

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.

getPageStatus

public byte getPageStatus()

Get the page status, one of the values in the above page status flag