| org.apache.derby.iapi.store.raw.Page
All known Subclasses: org.apache.derby.impl.store.raw.data.BasePage,
| Page | | public interface Page (Code) | | A Page contains an ordered set of records which are the stored form of rows.
A record is a stream of bytes created from a row array. The record
contains one or more fields, fields have a one to one correlation with
the DataValueDescriptor's contained within a row array.
A Page represents exclusive access to a data page within a container.
Exclusive access is released by calling the unlatch() method, once that
occurs the caller must no longer use the Page reference.
Several of the methods in Page take a RecordHandle as an argument.
RecordHandles are obtained from a Page, while holding exclusive access of
Page or a from a previous exclusive access of a Page representing the same
data page.
All RecordHandle's used as arguments to methods (with the exception of
recordExists()) must be valid for the current state of the page. If they
are not valid then the method will throw an exception. A caller can ensure
that a record handle is valid by:
- Obtaining the handle during this exclusive access of this page
- Checking the record still exists with the method recordExists()
- Not using a handle after a delete().
Several of the methods in Page take a slot number as an argument. A slot
always correspond to a record, which may be deleted or undeleted.
MT - Latched - In general every method requires the page to be latched.
Latching
All page methods which are not valid for a latched page throw an
exception if the page is not latched. [@exception clauses on all
the methods should be updated to reflect this].
Aux Objects
The page cache will manage a client object along with the page as long
as it remains in cache. This object is called the "aux object". The
aux object is associated with the page with setAuxObject(), and can be
retreived later with getAuxObject(). The aux object will remain valid
as long as the page is latched, but callers cannot assume that an aux
object will ever stick around once the page is unlatched. However, the
page manager promises to call pageBeingEvicted() once before clearing
the aux reference from the page.
See Also: Object
See Also: ContainerHandle
See Also: RecordHandle
See Also: AuxObject |
| Method Summary | |
| public void | copyAndPurge(Page destPage, int src_slot, int num_rows, int dest_slot)
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. | | PageTimeStamp | currentTimeStamp()
Return a time stamp that can be used to identify the page of this
specific instance. | | public boolean | delete(RecordHandle handle, LogicalUndo undo)
Mark the record identified by position as deleted.
Mark the record identified by position as deleted. | | public RecordHandle | deleteAtSlot(int slot, boolean delete, LogicalUndo undo)
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. | | boolean | equalTimeStamp(PageTimeStamp ts)
See if timeStamp for this page is the same as the current
instance of the page. | | RecordHandle | fetch(RecordHandle handle, Object[] row, FormatableBitSet validColumns, boolean forUpdate)
Fetch and lock a non-deleted record.
Lock and fetch a non-deleted record identified by a RecordHandle. | | public RecordHandle | fetchFieldFromSlot(int slot, int fieldId, Object column)
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. | | public RecordHandle | fetchFromSlot(RecordHandle rh, int slot, Object[] row, FetchDescriptor fetchDesc, boolean ignoreDelete)
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. | | public int | fetchNumFields(RecordHandle handle)
Fetch the number of fields in a record. | | public int | fetchNumFieldsAtSlot(int slot)
Fetch the number of fields in a record. | | public AuxObject | getAuxObject()
Retrieve this page's aux object, returning null if there isn't one. | | public RecordHandle | getInvalidRecordHandle()
Return an invalid record handle. | | int | getNextSlotNumber(RecordHandle handle)
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. | | public long | getPageNumber()
Return the page number of this page. | | 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. | | RecordHandle | insert(Object[] row, FormatableBitSet validColumns, byte insertFlag, int overflowThreshold)
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
Parameters:
row - The row version of the data
Parameters:
validColumns - a bit map of which columns in the row is valid. | | RecordHandle | insertAtSlot(int slot, Object[] row, FormatableBitSet validColumns, LogicalUndo undo, byte insertFlag, int overflowThreshold)
Insert a record at the specified slot. | | public boolean | isDeletedAtSlot(int slot)
Test if a record is deleted. | | public boolean | isLatched()
| | public RecordHandle | makeRecordHandle(int recordHandleConstant)
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. | | public int | moveRecordForCompressAtSlot(int slot, Object[] row, RecordHandle[] old_handle, RecordHandle[] new_handle)
Move record to a page toward the beginning of the file.
As part of compressing the table records need to be moved from the
end of the file toward the beginning of the file. | | public int | nonDeletedRecordCount()
Return the number of records on this page that are not marked as deleted. | | public void | purgeAtSlot(int slot, int numpurges, boolean needDataLogged)
Purge the row(s) from page.
Purge the row(s) from page, get rid of the row(s) and slot(s) -
USE WITH CAUTION,
please see entire description of this operation before attempting to
use this.
Starting from the specified slot, n rows will be purged. | | public int | recordCount()
Return the number of records on the page. | | boolean | recordExists(RecordHandle handle, boolean ignoreDelete)
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. | | public void | setAuxObject(AuxObject aux)
Set the aux object for this page. | | void | setTimeStamp(PageTimeStamp ts)
Set the time stamp to what is on page at this instance. | | public boolean | shouldReclaimSpace(int num_non_deleted_rows, int slot_just_deleted)
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. | | boolean | spaceForInsert()
Is it likely that an insert will fit on this page?
Return true if there is a good chance an insert will fit on this page,
false otherwise. | | boolean | spaceForInsert(Object[] row, FormatableBitSet validColumns, int overflowThreshold)
will insert of this row fit on this page?
Return true if this record is guaranteed to be inserted successfully
using insert() or insertAtSlot(). | | public void | unlatch()
Unlatch me, the page is exclusivly latched by its current user until
this method call is made. | | boolean | update(RecordHandle handle, Object[] row, FormatableBitSet validColumns)
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.
Parameters:
handle - the record handle
Parameters:
row - The row version of the data
Parameters:
validColumns - A bit map of which columns in the row is valid. | | RecordHandle | updateAtSlot(int slot, Object[] row, FormatableBitSet validColumns)
Update the complete record identified by the slot. | | public RecordHandle | updateFieldAtSlot(int slot, int fieldId, Object newValue, LogicalUndo undo)
Update a field within the record, replacing its current value with
the stored representation of newValue. |
| DIAG_BYTES_FREE | | final public static String DIAG_BYTES_FREE(Code) | | |
| DIAG_BYTES_RESERVED | | final public static String DIAG_BYTES_RESERVED(Code) | | |
| DIAG_MAXROWSIZE | | final public static String DIAG_MAXROWSIZE(Code) | | |
| DIAG_MINIMUM_REC_SIZE | | final public static String DIAG_MINIMUM_REC_SIZE(Code) | | |
| DIAG_MINROWSIZE | | final public static String DIAG_MINROWSIZE(Code) | | |
| DIAG_NUMOVERFLOWED | | final public static String DIAG_NUMOVERFLOWED(Code) | | |
| DIAG_PAGEOVERHEAD | | final public static String DIAG_PAGEOVERHEAD(Code) | | |
| DIAG_PAGE_SIZE | | final public static String DIAG_PAGE_SIZE(Code) | | |
| DIAG_RESERVED_SPACE | | final public static String DIAG_RESERVED_SPACE(Code) | | |
| DIAG_SLOTTABLE_SIZE | | final public static String DIAG_SLOTTABLE_SIZE(Code) | | |
| FIRST_SLOT_NUMBER | | final public static int FIRST_SLOT_NUMBER(Code) | | The slot number of the first slot. This is guaranteed to be zero.
|
| INSERT_CONDITIONAL | | final static byte INSERT_CONDITIONAL(Code) | | |
| INSERT_DEFAULT | | final static byte INSERT_DEFAULT(Code) | | |
| INSERT_FOR_SPLIT | | final static byte INSERT_FOR_SPLIT(Code) | | |
| INSERT_INITIAL | | final static byte INSERT_INITIAL(Code) | | Values for insertFlag.
INSERT_INITIAL - flag initializer
INSERT_DEFAULT - default insert behavior, if the record does
not fit on the page where the insert
operation is called, an error will be
returned, instead of overflowing the record.
INSERT_UNDO_WITH_PURGE - if this is set, then the undo of this insert
will purge the row rather than mark it as
deleted, which is the default behaviro for
insertAtSlot and insert.
INSERT_CONDITIONAL - if this flag is set, then, the overflow is
conditional. The record will be overflowed
only if it exceeds the threshold specified
by the properties, or the parameter.
INSERT_OVERFLOW - if this flag is set, then the insert
operation will overflow the record if it does
not fit on the page.
INSERT_FOR_SPLIT - a record is being updated that causes new
portions to be inserted *and* the last new
portion needs to point to an existing portion.
Rules for the insert flags:
1. If INSERT_DEFAULT is set, INSERT_CONDITIONAL and INSERT_OVERFLOW
will be ignored
2. INSERT_UNDO_WITH_PURGE can be set with any of the other 3 flags.
3. If INSERT_OVERFLOW is not set, INSERT_CONDITIONAL will be ignored.
But, it is not necessary to set INSERT_CONDITIONAL when setting
INSERT_OVERFLOW.
4. If INSERT_DEFAULT, INSERT_OVERFLOW both are not set, then, default
insert action will be taken, i.e. no overflow will be allowed.
|
| INSERT_OVERFLOW | | final static byte INSERT_OVERFLOW(Code) | | |
| INSERT_UNDO_WITH_PURGE | | final static byte INSERT_UNDO_WITH_PURGE(Code) | | |
| INVALID_SLOT_NUMBER | | final public static int INVALID_SLOT_NUMBER(Code) | | A slot number guaranteed to be invalid.
|
| copyAndPurge | | public void copyAndPurge(Page destPage, int src_slot, int num_rows, int dest_slot) throws StandardException(Code) | | 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.
Parameters:
destPage - the page to copy to
Parameters:
src_slot - start copying from this slot
Parameters:
num_rows - copy and purge this many rows from this page
Parameters:
dest_slot - copying into this slot of destPage
exception:
StandardException - Standard Cloudscape error policy |
| currentTimeStamp | | PageTimeStamp currentTimeStamp()(Code) | | Return a time stamp that can be used to identify the page of this
specific instance. For pages that don't support timestamp, returns
null.
|
| delete | | public boolean delete(RecordHandle handle, LogicalUndo undo) throws StandardException(Code) | | 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.
Parameters:
handle - record Handle to record
Parameters:
undo - if logical undo may be necessary, a function pointer tothe access code where the logical undo logic resides.Null if logical undo is not necessary. true if the record was updated. False if it wasn't because it is already deleted.
exception:
StandardException - Standard Cloudscape error policy
exception:
StandardException - The container was not opened in update mode.
exception:
StandardException - If the record handle does not match a record on the page.
See Also: Page.deleteAtSlot
See Also: LockingPolicy |
| deleteAtSlot | | public RecordHandle deleteAtSlot(int slot, boolean delete, LogicalUndo undo) throws StandardException(Code) | | 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
a Handle to the deleted/undeleted record.
Parameters:
slot - is the slot number
Parameters:
delete - true if this record is to be deleted false if this deleted record is to be marked undeleted
Parameters:
undo - if logical undo may be necessary, a function pointer tothe access code where the logical undo logic resides.Null if logical undo is not necessary.
exception:
StandardException - Standard Cloudscape error policy
exception:
StandardException - The container was not opened in update mode.
exception:
StandardException - A statement level exception is thrown when trying to delete an already deleted record,or undelete a not deleted record.
exception:
StandardException - A statement level exception is thrown if the slot is not on the page.
See Also: LockingPolicy
See Also: Page.delete
See Also: LogicalUndo
See Also: LogicalUndoable |
| equalTimeStamp | | boolean equalTimeStamp(PageTimeStamp ts) throws StandardException(Code) | | See if timeStamp for this page is the same as the current
instance of the page. Null timeStamp never equals the instance of the
page.
Parameters:
ts - the time stamp gotten from an earlier call to this page'sgetTimeStamp true if timestamp is the same
exception:
StandardException - Standard Cloudscape error policy.
See Also: PageTimeStamp |
| fetch | | RecordHandle fetch(RecordHandle handle, Object[] row, FormatableBitSet validColumns, boolean forUpdate) throws StandardException(Code) | | Fetch and lock a non-deleted record.
Lock and fetch a non-deleted record identified by a RecordHandle.
Reads data from the page into row.
Locking Policy
Calls the lockRecordForRead() method of the LockingPolicy object
passed to the openContainer() call before the record is accessed.
The page latch may be released and re-latched within this method.
This will occur if the record lock has to be waited for.
Parameters:
handle - Handle to record.
Parameters:
row - Row to be filled in with data from the record.
Parameters:
validColumns - a bit map of which columns in the row is to be fetched. ValidColumns will not be changed by RawStore.
Parameters:
forUpdate - true if the intention is to update this record, false otherwise. A handle to the record, null if the record has been deleted.
exception:
StandardException - Standard Cloudscape error policy, a statemente level exception is thrown ifthe record handle does not match a record on the page.
See Also: Page.delete
See Also: LockingPolicy |
| fetchFieldFromSlot | | public RecordHandle fetchFieldFromSlot(int slot, int fieldId, Object column) throws StandardException(Code) | | 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
Parameters:
slot - is the slot number
Parameters:
fieldId - is the column id
Parameters:
column - is to be filled in with information from the record. the Handle to the record that is locked
exception:
StandardException - Standard Cloudscape error policy, a statement level exception is thrown ifthe slot is not on the page.
See Also: Page.fetchFromSlot
See Also: LockingPolicy |
| fetchFromSlot | | public RecordHandle fetchFromSlot(RecordHandle rh, int slot, Object[] row, FetchDescriptor fetchDesc, boolean ignoreDelete) throws StandardException(Code) | | 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.
Parameters:
rh - the record handle of the row. If non-null it must refer to the same record as the slot.
Parameters:
slot - the slot number
Parameters:
row - Row to be filled in with information from record.
Parameters:
fetchDesc - A structure to efficiently carry a set of parametersneeded 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 ifthe row should be returned.An array of qualifiers which restrict whether or notthe 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 qualificationis 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 idthe 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 noqualifiers are input then array need not be input. Passed in rather than allocated so thatspace can be allocated a single time in a scan.If not passed in then raw store will allocate anddeallocate per call.
Parameters:
ignoreDelete - if true, return row regardless of whether it is deleted or not. If false, only return non-deleted row. A handle to the record.
exception:
StandardException - Standard Cloudscape error policy
See Also: LockingPolicy |
| fetchNumFields | | public int fetchNumFields(RecordHandle handle) throws StandardException(Code) | | Fetch the number of fields in a record.
Locking Policy
No locks are obtained.
MT - latched
Parameters:
handle - record handle to deleted or non-deleted record the number of fields in the record
exception:
StandardException - Standard Cloudscape error policy, a statement level exception is thrown if the record handle does not match a record on the page. |
| fetchNumFieldsAtSlot | | public int fetchNumFieldsAtSlot(int slot) throws StandardException(Code) | | 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
Parameters:
slot - is the slot number the number of fields in the record
exception:
StandardException - Standard Cloudscape error policy |
| getAuxObject | | public AuxObject getAuxObject()(Code) | | Retrieve this page's aux object, returning null if there isn't one. The reference returned
must only be used while the page is latched, once unlatch is called the reference to the
aux object must be discarded.
MT - latched
See Also: AuxObject |
| getInvalidRecordHandle | | public RecordHandle getInvalidRecordHandle()(Code) | | Return an invalid record handle.
an invalid record handle.
exception:
StandardException - Standard exception policy. |
| getNextSlotNumber | | int getNextSlotNumber(RecordHandle handle) throws StandardException(Code) | | 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
Parameters:
handle - record handle to find the next higher id. record id of the first record on the page with a record id higher than the one passed in. If no such record exists, -1 is returned.
exception:
StandardException - Standard exception policy. |
| getPageNumber | | public long getPageNumber()(Code) | | 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
See Also: ContainerHandle The page number of this page. |
| getRecordHandle | | RecordHandle getRecordHandle(int recordId)(Code) | | 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
A valid record handle or null if the record no longer exists.
Parameters:
recordId - previously stored recordId.
See Also: RecordHandle.getId |
| getRecordHandleAtSlot | | RecordHandle getRecordHandleAtSlot(int slot) throws StandardException(Code) | | 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
Parameters:
slot - the slot number the record handle.
exception:
StandardException - Standard Cloudscape error policy |
| getSlotNumber | | int getSlotNumber(RecordHandle handle) throws StandardException(Code) | | 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
Parameters:
handle - the record handle the slot number
exception:
StandardException - Standard Cloudscape error policy |
| insert | | RecordHandle insert(Object[] row, FormatableBitSet validColumns, byte insertFlag, int overflowThreshold) throws StandardException(Code) | | 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
Parameters:
row - The row version of the data
Parameters:
validColumns - a bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
Parameters:
insertFlag - see values for insertFlag below. A RecordHandle representing the new record.
exception:
StandardException - Standard Cloudscape error policy
exception:
StandardException - The container was not opened in update mode.
exception:
StandardException - Row cannot fit on the page or row is null. |
| insertAtSlot | | RecordHandle insertAtSlot(int slot, Object[] row, FormatableBitSet validColumns, LogicalUndo undo, byte insertFlag, int overflowThreshold) throws StandardException(Code) | | 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:
- an exception is thrown if the page has no other rows, this is an
indication that the row could never fit on a page in this container.
- null is returned if there are other rows on the page, this is an
indication that the row can potentially be inserted successfully
onto an empty page.
Locking Policy
Calls the lockRecordForWrite() method of the LockingPolicy object passed
to the openContainer() call before the record is inserted.
MT - latched
Parameters:
slot - The specified slot
Parameters:
row - The row version of the data
Parameters:
undo - if logical undo may be necessary, a function pointerto the access code where the logical undo logic resides. Null if logical undo is not necessary.
Parameters:
validColumns - a bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore.
Parameters:
insertFlag - if INSERT_UNDO_WITH_PURGE set, then the undo of thisinsert will purge the row rather than mark it as deleted, which is the default bahavior for insertAtSlot and insert. A RecordHandle representing the new record, or null if the row will not fit on a non-empty page.
exception:
StandardException - Standard Cloudscape error policy
exception:
StandardException - The container was not opened in update mode.
exception:
StandardException - The row cannot fit on the page
See Also: LogicalUndo
See Also: LogicalUndoable |
| isDeletedAtSlot | | public boolean isDeletedAtSlot(int slot) throws StandardException(Code) | | 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
Parameters:
slot - slot of record to be tested.
exception:
StandardException - Standard Cloudscape error policy, a statement level exception is thrown if the slot is not on the page. |
| isLatched | | public boolean isLatched()(Code) | | |
| makeRecordHandle | | public RecordHandle makeRecordHandle(int recordHandleConstant) throws StandardException(Code) | | 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."
See Also: RecordHandle The created record handle.
Parameters:
recordHandleConstant - the special recordId
exception:
StandardException - if input is not a special record identifier. |
| moveRecordForCompressAtSlot | | public int moveRecordForCompressAtSlot(int slot, Object[] row, RecordHandle[] old_handle, RecordHandle[] new_handle) throws StandardException(Code) | | Move record to a page toward the beginning of the file.
As part of compressing the table records need to be moved from the
end of the file toward the beginning of the file. Only the
contiguous set of free pages at the very end of the file can
be given back to the OS. This call is used to purge the row from
the current page, insert it into a previous page, and return the
new row location
Mark the record identified by position as deleted. The record may be
undeleted sometime later using undelete() by any transaction that sees
the record.
The interface is optimized to work on a number of rows at a time,
optimally processing all rows on the page at once. The call will
process either all rows on the page, or the number of slots in the
input arrays - whichever is smaller.
Locking Policy
MUST be called with table locked, not locks are requested. Because
it is called with table locks the call will go ahead and purge any
row which is marked deleted. It will also use purge rather than
delete to remove the old row after it moves it to a new page. This
is ok since the table lock insures that no other transaction will
use space on the table before this transaction commits.
A page latch on the new page will be requested and released.
Parameters:
slot - Slot of row to move.
Parameters:
row - A template to read the current row into as partof moving it.
Parameters:
old_handle - An array to be filled in by the call with the old handles of all rows moved.
Parameters:
new_handle - An array to be filled in by the call with the new handles of all rows moved. the number of rows processed.
exception:
StandardException - Standard Cloudscape error policy
See Also: LockingPolicy |
| nonDeletedRecordCount | | public int nonDeletedRecordCount() throws StandardException(Code) | | Return the number of records on this page that are not marked as deleted.
MT - latched
exception:
StandardException - Standard Cloudscape error policy |
| purgeAtSlot | | public void purgeAtSlot(int slot, int numpurges, boolean needDataLogged) throws StandardException(Code) | | Purge the row(s) from page.
Purge the row(s) from page, get rid of the row(s) and slot(s) -
USE WITH CAUTION,
please see entire description of this operation before attempting to
use this.
Starting from the specified slot, n rows will be purged. That is, rows
that occupies from slot to slot+n-1 will be purged from the page.
Locking Policy
Calls the lockRecordForWrite() method of the LockingPolicy object passed
to the openContainer() call before the records are purged.
NOTE : CAVEAT
This operation will physically get rid of the row from the page, so if a
subsequent operation on this page uses a slot that has been purged, then
the undo of this operation will fail. 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
NOTE
Outstanding handles to purged rows are no longer valid, accessing them
will cause an exception to be thrown.
NOTE : Data Logging for Purges
needDataLogged is used to specify whether data is required to be
logged for purge operatios. Data Logging is required
Only if the row can be reused or required for key search if a purge is
rolled back;(rollback can occur if the system crashes in the middle of
purges or some unexpected error condiditions rolled back.
For example:
1)Btree expects the data to be there if a purge is rolled back;
needDataLogged=true
2)Heaps does not care if data exist because only operation that can occur
on a row whose purge rolled back is purging again.(needDataLogged=false)
MT - latched
Parameters:
slot - the starting slot number
Parameters:
numpurges - number of slots to purge. If <= 0, just returns as a no-op.
Parameters:
needDataLogged - if set to true data is logged for purges else only headers.
exception:
StandardException - Standard Cloudscape error policy
See Also: LockingPolicy |
| recordCount | | public int recordCount() throws StandardException(Code) | | 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
exception:
StandardException - Standard Cloudscape error policy |
| recordExists | | boolean recordExists(RecordHandle handle, boolean ignoreDelete) throws StandardException(Code) | | 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
boolean indicating if the record still exists on the page.
Parameters:
handle - handle of the record to look for.
Parameters:
ignoreDelete - if true, then routine will return true even if therow is marked deleted.
exception:
StandardException - Standard exception policy. |
| setAuxObject | | public void setAuxObject(AuxObject aux)(Code) | | Set the aux object for this page.
To clear the auxObject in the page, pass in a null AuxObject.
If the AuxObject has already been set, this method will
call auxObjectInvalidated() on the old aux objkect and replace it with aux.
MT - latched
See Also: AuxObject |
| shouldReclaimSpace | | public boolean shouldReclaimSpace(int num_non_deleted_rows, int slot_just_deleted) throws StandardException(Code) | | 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.
true if a reclaim space should be scheduled post commit on thispage, false otherwise.
Parameters:
num_non_deleted_rows - threshold number of non-deleted rows toschedule reclaim space.
Parameters:
slot_just_deleted - row on page to check for long row/long column
exception:
StandardException - Standard exception policy. |
| spaceForInsert | | boolean spaceForInsert() throws StandardException(Code) | | Is it likely that an insert will fit on this page?
Return true if there is a good chance an insert will fit on this page,
false otherwise. If this returns true then an insert may still fail by
throwing an exception or by returning null, see insertAtSlot for details.
It is very probable that this call is much faster than the version that
takes a row. In situations where it is expected that the
majority of times a row will fit on a page this method should be used
and the null return handled from insert/insertAtSlot.
MT - latched
true if it is likely an insert will fit on the page.
exception:
StandardException - Standard exception policy. |
| spaceForInsert | | boolean spaceForInsert(Object[] row, FormatableBitSet validColumns, int overflowThreshold) throws StandardException(Code) | | will insert of this row fit on this page?
Return true if this record is guaranteed to be inserted successfully
using insert() or insertAtSlot(). This guarantee is only valid if the
following conditions are fulfilled before an insert is called with t
his row.
- The page is not unlatched
- The page is not modified in any way, ie. no updates or other inserts
- The row is not modified in such a way that would change its
storage size
MT - latched
true if insert of this row will fit on this page.
Parameters:
row - The row to check for insert.
Parameters:
validColumns - bit map to interpret valid columns in row.
Parameters:
overflowThreshold - The percentage of the page to use for theinsert. 100 means use 100% of the page,50 means use 50% of page (ie. make sure2 rows fit per page).
exception:
StandardException - Standard exception policy. |
| unlatch | | public void unlatch()(Code) | | Unlatch me, the page is exclusivly latched by its current user until
this method call is made.
After using this method the caller must throw away the
reference to the Page object, e.g.
ref.unlatch();
ref = null;
The page will be released automatically at the close of the
container if this method is not called explictly.
MT - latched
|
| update | | boolean update(RecordHandle handle, Object[] row, FormatableBitSet validColumns) throws StandardException(Code) | | 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.
Parameters:
handle - the record handle
Parameters:
row - The row version of the data
Parameters:
validColumns - A bit map of which columns in the row is valid. ValidColumns will not be changed by RawStore. true if the record is updated. False if it is not because the record is already deleted.
exception:
StandardException - Standard Cloudscape error policy
exception:
StandardException - The container was not opened in update mode.
exception:
StandardException - If the record handle does not match a record on the page.
See Also: Page.updateAtSlot
exception:
StandardException - Standard exception policy. |
| updateAtSlot | | RecordHandle updateAtSlot(int slot, Object[] row, FormatableBitSet validColumns) throws StandardException(Code) | | 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
a Handle to the updated record.
Parameters:
slot - is the slot number
Parameters:
validColumns - a bit map of which columns in the row is valid.ValidColumns will not be changed by RawStore.
exception:
StandardException - Standard Cloudscape error policy
exception:
StandardException - The container was not opened in update mode.
exception:
StandardException - if the slot is not on the page.
See Also: Page.update |
| updateFieldAtSlot | | public RecordHandle updateFieldAtSlot(int slot, int fieldId, Object newValue, LogicalUndo undo) throws StandardException(Code) | | 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
Parameters:
slot - is the slot number
Parameters:
fieldId - is the column id
Parameters:
newValue - has the new colum value to be stored in the record
Parameters:
undo - if logical undo may be necessary, a function pointer to theaccess code where the logical undo logic resides. Null if logical undois not necessary. a Handle to the updated record.
exception:
StandardException - Standard Cloudscape error policy, astatement level exception is thrown ifthe slot is not on the page, or if the record is deleted, or if the fieldId is not on the record and (fieldId - 1)does not exist.
exception:
StandardException - The container was not opened in update mode.
See Also: LockingPolicy
See Also: LogicalUndo
See Also: LogicalUndoable |
|
|