org.apache.derby.impl.store.access.btree

Class ControlRow

java.lang.Object

org.apache.derby.impl.store.access.btree.ControlRow

All Implemented Interfaces:

TypedFormat, AuxObject

Direct Known Subclasses:

BranchControlRow, LeafControlRow

public abstract class ControlRow
extends java.lang.Object
implements AuxObject, TypedFormat

Base class for leaf and branch control rows.

Concurrency Notes

All access through control rows is serialized by an exclusive latch on the page the control row is for. The page is latched when the control row is "gotten" (ControlRow#Get), and unlatched when the control row is released (ControlRow#release).

To Do List

• [NOTE1] The code is arranged to fault in fields from the row as necessary. many of the fields of a control row are rarely used (left sibling, parent). The accessors fault in the underlying column only when requested by allocating the appropriate object and calling fetchFromSlot and only fetching the requested field.
• [NOTE2] Currently, all the fields of the control row are stored as StorableU8s for simplicity. This is too few bits to hold the long page numbers, and too many to hold the version, level, and isRoot flag. Some consideration will have to be given to the appropriate storage format for these values.
• [NOTE3] The implementation relies on the existance of page "auxiliary" pointers which keep Object versions of the control row.

See Also:

get(org.apache.derby.impl.store.access.btree.OpenBTree, long), release()

Field Summary

Fields

Modifier and Type	Field and Description
static int	SPLIT_FLAG_FIRST_IN_TABLE
static int	SPLIT_FLAG_FIRST_ON_PAGE
static int	SPLIT_FLAG_LAST_IN_TABLE
static int	SPLIT_FLAG_LAST_ON_PAGE Values passed in the flag argument to splitFor.

Method Summary

Modifier and Type	Method and Description
void	auxObjectInvalidated() Called when the page is being evicted from cache or when a rollback happened on the page and may possibly have changed the control row's value
static int	compareIndexRowFromPageToKey(ControlRow indexpage, int slot, DataValueDescriptor[] indexrow, DataValueDescriptor[] key, int nCompareCols, int partialKeyOrder, boolean[] ascOrDesc) Compare two orderable rows, considering nCompareCols, and return -1, 0, or 1 depending on whether the first row (indexrow) is less than, equal to, or greater than the second (key).
static int	compareIndexRowToKey(DataValueDescriptor[] indexrow, DataValueDescriptor[] key, int nCompareCols, int partialKeyOrder, boolean[] ascOrDesc)
java.lang.String	debugPage(OpenBTree open_btree) Dump complete information about control row and rows on the page.
static ControlRow	get(ContainerHandle container, long pageNumber)
static ControlRow	get(OpenBTree open_btree, long pageNumber) Get the control row from the given page in the b-tree.
BTree	getConglom(int format_id) Get format id information for row on page.
ControlRow	getLeftSibling(OpenBTree btree) Get the control row for this page's left sibling, or null if there is no left sibling (which probably means it's the leftmost page at its level).
long	getleftSiblingPageNumber() Get the page number of the left sibling.
static ControlRow	getNoWait(OpenBTree open_btree, long pageNumber) Get the control row for the given page if the latch on the page can be obtained without waiting, else return null.
Page	getPage()
DataValueDescriptor[]	getRowTemplate(OpenBTree open_btree) Return a new template for reading a data row from the current page.
abstract boolean	isLeftmostLeaf() Is the current page the leftmost leaf of tree?
abstract boolean	isRightmostLeaf() Is the current page the rightmost leaf of tree?
abstract void	printTree(OpenBTree btree) Recursively print the tree starting at current node in tree.
void	release() Release this control row's resources.
abstract ControlRow	search(SearchParameters search_params) Perform a recursive search, ultimately returning the latched leaf page and row slot after which the given key belongs.
java.lang.String	toString() The standard toString().

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.derby.iapi.services.io.TypedFormat

getTypeFormatId

Field Detail

SPLIT_FLAG_LAST_ON_PAGE

public static final int SPLIT_FLAG_LAST_ON_PAGE

Values passed in the flag argument to splitFor.

See Also:

Constant Field Values

SPLIT_FLAG_LAST_IN_TABLE

public static final int SPLIT_FLAG_LAST_IN_TABLE

See Also:

Constant Field Values

SPLIT_FLAG_FIRST_ON_PAGE

public static final int SPLIT_FLAG_FIRST_ON_PAGE

See Also:

Constant Field Values

SPLIT_FLAG_FIRST_IN_TABLE

public static final int SPLIT_FLAG_FIRST_IN_TABLE

See Also:

Constant Field Values

Method Detail

getLeftSibling

public ControlRow getLeftSibling(OpenBTree btree)
                          throws StandardException,
                                 WaitError

Get the control row for this page's left sibling, or null if there is no left sibling (which probably means it's the leftmost page at its level). Since right-to-left traversal of an index level is deadlock-prone, this method will only get get the left sibling if it can latch it without waiting.

Throws:

WaitError - if the latch request would have had to wait.

StandardException - Standard exception policy.

getleftSiblingPageNumber

public long getleftSiblingPageNumber()
                              throws StandardException

Get the page number of the left sibling. Fault it's value in if it hasn't been yet.

Throws:

StandardException - Standard exception policy.

getConglom

public BTree getConglom(int format_id)
                 throws StandardException

Get format id information for row on page.

Returns the format id information for a row on the page. faulting it in from the page if necessary.

Returns:

format id of a row on the page.

Throws:

StandardException - Standard exception policy.

get

public static ControlRow get(OpenBTree open_btree,
                             long pageNumber)
                      throws StandardException

Get the control row from the given page in the b-tree. The returned control row will be of the correct type for the page (i.e., either a LeafControlRow or a BranchControlRow).

Throws:

StandardException - Standard exception policy.

get

public static ControlRow get(ContainerHandle container,
                             long pageNumber)
                      throws StandardException

Throws:

StandardException

getNoWait

public static ControlRow getNoWait(OpenBTree open_btree,
                                   long pageNumber)
                            throws StandardException

Get the control row for the given page if the latch on the page can be obtained without waiting, else return null.

Throws:

StandardException - Standard exception policy.

release

public void release()

Release this control row's resources.

compareIndexRowFromPageToKey

public static int compareIndexRowFromPageToKey(ControlRow indexpage,
                                               int slot,
                                               DataValueDescriptor[] indexrow,
                                               DataValueDescriptor[] key,
                                               int nCompareCols,
                                               int partialKeyOrder,
                                               boolean[] ascOrDesc)
                                        throws StandardException

Compare two orderable rows, considering nCompareCols, and return -1, 0, or 1 depending on whether the first row (indexrow) is less than, equal to, or greater than the second (key). The key may have fewer columns present than nCompareCols. In such a case, if all the columns of the partial key match all of the corresponding columns in the index row, then the value passed in in partialKeyOrder is returned. The caller should pass in partialKeyOrder=1 if the index rows which match a partial key should be considered to be greater than the partial key, and -1 if they should be considered to be less. This routine only reads objects off the page if it needs them, so if a multi-part key differs in the first column the subsequent columns are not read.

Parameters:

indexpage - Controlrow of page to get target row from.

slot - Slot to get control row from.

indexrow - template of the target row (the row in the index).

key - the (possibly partial) search key.

nCompareCols - the number of columns to compare.

partialKeyOrder - what to return on a partial key match.

ascOrDesc - column sort order information

Throws:

StandardException - if lower levels have a problem.

compareIndexRowToKey

public static int compareIndexRowToKey(DataValueDescriptor[] indexrow,
                                       DataValueDescriptor[] key,
                                       int nCompareCols,
                                       int partialKeyOrder,
                                       boolean[] ascOrDesc)
                                throws StandardException

Throws:

StandardException

getPage

public Page getPage()

isLeftmostLeaf

public abstract boolean isLeftmostLeaf()
                                throws StandardException

Is the current page the leftmost leaf of tree?

Returns:

true if the current page is the leftmost leaf of the tree, else return false.

Throws:

StandardException - Standard exception policy.

isRightmostLeaf

public abstract boolean isRightmostLeaf()
                                 throws StandardException

Is the current page the rightmost leaf of tree?

Returns:

true if the current page is the rightmost leaf of the tree, else return false.

Throws:

StandardException - Standard exception policy.

search

public abstract ControlRow search(SearchParameters search_params)
                           throws StandardException

Perform a recursive search, ultimately returning the latched leaf page and row slot after which the given key belongs. The slot is returned in the result structure. If the key exists on the page, the resultExact field will be true. Otherwise, resultExact field will be false, and the row slot returned will be the one immediately preceding the position at which the key belongs.

Throws:

StandardException - Standard exception policy.

printTree

public abstract void printTree(OpenBTree btree)
                        throws StandardException

Recursively print the tree starting at current node in tree.

Throws:

StandardException - Standard exception policy.

auxObjectInvalidated

public void auxObjectInvalidated()

Called when the page is being evicted from cache or when a rollback happened on the page and may possibly have changed the control row's value

Specified by:

auxObjectInvalidated in interface AuxObject

See Also:

AuxObject.auxObjectInvalidated()

getRowTemplate

public DataValueDescriptor[] getRowTemplate(OpenBTree open_btree)
                                     throws StandardException

Return a new template for reading a data row from the current page.

Default implementation for rows which are the same as the conglomerates template, sub-classes can alter if underlying template is different (for instance branch rows add an extra field at the end).

Returns:

Newly allocated template.

Throws:

StandardException - Standard exception policy.

debugPage

public java.lang.String debugPage(OpenBTree open_btree)
                           throws StandardException

Dump complete information about control row and rows on the page.

Returns:

string with all info.

Throws:

StandardException - Standard exception policy.

toString

public java.lang.String toString()

The standard toString().

This is a concise print out of the info in the control row, does not include anything the page.

Overrides:

toString in class java.lang.Object