org.tmatesoft.sqljet.core.internal.btree

Class SqlJetBtreeCursor

java.lang.Object

org.tmatesoft.sqljet.core.internal.SqlJetCloneable

org.tmatesoft.sqljet.core.internal.btree.SqlJetBtreeCursor

All Implemented Interfaces:

java.lang.Cloneable, ISqlJetBtreeCursor

public class SqlJetBtreeCursor
extends SqlJetCloneable
implements ISqlJetBtreeCursor

Author:

TMate Software Ltd., Sergey Scherbina (sergey.scherbina@gmail.com)

Field Summary

Fields inherited from interface org.tmatesoft.sqljet.core.internal.ISqlJetBtreeCursor

BTCURSOR_MAX_DEPTH

Constructor Summary

Constructors

Constructor and Description
SqlJetBtreeCursor(SqlJetBtree btree, int table, boolean wrFlag, ISqlJetKeyInfo keyInfo) Create a new cursor for the BTree whose root is on the page iTable.

Method Summary

Modifier and Type	Method and Description
void	cacheOverflow() Set a flag on this cursor to cache the locations of pages from the overflow list for the current row.
void	clearCursor() Clear the current cursor position.
void	closeCursor() Close a cursor.
boolean	cursorHasMoved() Determine whether or not a cursor has moved from the position it was last placed at.
void	data(int offset, int amt, ISqlJetMemoryPointer buf) Read part of the data associated with cursor pCur.
ISqlJetMemoryPointer	dataFetch(int[] amt) For the entry that cursor pCur is point to, return as many bytes of the key or data as are available on the local b-tree page.
void	delete() Delete the entry that the cursor is pointing to.
void	enterCursor() Enter a mutex on a Btree given a cursor owned by that Btree.
boolean	eof() Return TRUE if the cursor is not pointing at an entry of the table.
boolean	first() Move the cursor to the first entry in the table.
short	flags() Return the flag byte at the beginning of the page that the cursor is currently pointing to.
ISqlJetDbHandle	getCursorDb() Return the database connection handle for a cursor.
int	getDataSize() Return the number of bytes of data in the entry the cursor currently points to.
long	getKeySize() Returns the size of the buffer needed to hold the value of the key for the current entry.
void	insert(ISqlJetMemoryPointer pKey, long nKey, ISqlJetMemoryPointer pData, int nData, int zero, boolean bias) Insert a new record into the BTree.
void	key(int offset, int amt, ISqlJetMemoryPointer buf) Read part of the key associated with cursor pCur.
ISqlJetMemoryPointer	keyFetch(int[] amt) For the entry that cursor pCur is point to, return as many bytes of the key or data as are available on the local b-tree page.
boolean	last() Move the cursor to the last entry in the table.
void	leaveCursor() Leave a mutex on a Btree given a cursor owned by that Btree.
int	moveTo(ISqlJetMemoryPointer pKey, long nKey, boolean bias) In this version of moveTo(), pKey is a packed index record such as is generated by the OP_MakeRecord opcode.
int	moveToUnpacked(ISqlJetUnpackedRecord pIdxKey, long intKey, boolean biasRight) Move the cursor so that it points to an entry near the key specified by pIdxKey or intKey.
boolean	next() Advance the cursor to the next entry in the database.
boolean	previous() Step the cursor to the back to the previous entry in the database.
void	putData(int offset, int amt, ISqlJetMemoryPointer data) Must be a cursor opened for writing on an INTKEY table currently pointing at a valid table entry.
void	restoreCursorPosition() Restore the cursor to the position it was in (or as close to as possible) when saveCursorPosition() was called.
boolean	saveCursorPosition() Save the current cursor position in the variables BtCursor.nKey and BtCursor.pKey.

Methods inherited from class org.tmatesoft.sqljet.core.internal.SqlJetCloneable

clone

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SqlJetBtreeCursor

public SqlJetBtreeCursor(SqlJetBtree btree,
                         int table,
                         boolean wrFlag,
                         ISqlJetKeyInfo keyInfo)
                  throws SqlJetException

Create a new cursor for the BTree whose root is on the page iTable. The act of acquiring a cursor gets a read lock on the database file. If wrFlag==0, then the cursor can only be used for reading. If wrFlag==1, then the cursor can be used for reading or for writing if other conditions for writing are also met. These are the conditions that must be met in order for writing to be allowed: 1: The cursor must have been opened with wrFlag==1 2: Other database connections that share the same pager cache but which are not in the READ_UNCOMMITTED state may not have cursors open with wrFlag==0 on the same table. Otherwise the changes made by this write cursor would be visible to the read cursors in the other database connection. 3: The database must be writable (not on read-only media) 4: There must be an active transaction. No checking is done to make sure that page iTable really is the root page of a b-tree. If it is not, then the cursor acquired will not work correctly. It is assumed that the sqlite3BtreeCursorSize() bytes of memory pointed to by pCur have been zeroed by the caller.

Parameters:

sqlJetBtree -

table -

wrFlag2 -

keyInfo -

Throws:

SqlJetException

Method Detail

clearCursor

public void clearCursor()

Description copied from interface: ISqlJetBtreeCursor

Clear the current cursor position.

Specified by:

clearCursor in interface ISqlJetBtreeCursor

closeCursor

public void closeCursor()
                 throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Close a cursor. The read lock on the database file is released when the last cursor is closed.

Specified by:

closeCursor in interface ISqlJetBtreeCursor

Throws:

SqlJetException

moveTo

public int moveTo(ISqlJetMemoryPointer pKey,
                  long nKey,
                  boolean bias)
           throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

In this version of moveTo(), pKey is a packed index record such as is generated by the OP_MakeRecord opcode. Unpack the record and then call BtreeMovetoUnpacked() to do the work.

Specified by:

moveTo in interface ISqlJetBtreeCursor

Parameters:

pKey - Packed key if the btree is an index

nKey - Integer key for tables. Size of pKey for indices

bias - Bias search to the high end

Returns:

Throws:

SqlJetException

moveToUnpacked

public int moveToUnpacked(ISqlJetUnpackedRecord pIdxKey,
                          long intKey,
                          boolean biasRight)
                   throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Move the cursor so that it points to an entry near the key specified by pIdxKey or intKey. Return a success code. For INTKEY tables, the intKey parameter is used. pIdxKey must be NULL. For index tables, pIdxKey is used and intKey is ignored. If an exact match is not found, then the cursor is always left pointing at a leaf page which would hold the entry if it were present. The cursor might point to an entry that comes before or after the key. An integer is returned which is the result of comparing the key with the entry to which the cursor is pointing. The meaning of the integer returned is as follows: <0 The cursor is left pointing at an entry that is smaller than intKey/pIdxKey or if the table is empty and the cursor is therefore left point to nothing. ==0 The cursor is left pointing at an entry that exactly matches intKey/pIdxKey. >0 The cursor is left pointing at an entry that is larger than intKey/pIdxKey.

Specified by:

moveToUnpacked in interface ISqlJetBtreeCursor

Throws:

SqlJetException

restoreCursorPosition

public void restoreCursorPosition()
                           throws SqlJetException

Restore the cursor to the position it was in (or as close to as possible) when saveCursorPosition() was called. Note that this call deletes the saved position info stored by saveCursorPosition(), so there can be at most one effective restoreCursorPosition() call after each saveCursorPosition().

Specified by:

restoreCursorPosition in interface ISqlJetBtreeCursor

Throws:

SqlJetException

cursorHasMoved

public boolean cursorHasMoved()

Description copied from interface: ISqlJetBtreeCursor

Determine whether or not a cursor has moved from the position it was last placed at. Cursors can move when the row they are pointing at is deleted out from under them.

Specified by:

cursorHasMoved in interface ISqlJetBtreeCursor

Returns:

true if the cursor has moved and false if not.

delete

public void delete()
            throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Delete the entry that the cursor is pointing to. The cursor is left pointing at a arbitrary location.

Specified by:

delete in interface ISqlJetBtreeCursor

Throws:

SqlJetException

insert

public void insert(ISqlJetMemoryPointer pKey,
                   long nKey,
                   ISqlJetMemoryPointer pData,
                   int nData,
                   int zero,
                   boolean bias)
            throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Insert a new record into the BTree. The key is given by (pKey,nKey) and the data is given by (pData,nData). The cursor is used only to define what table the record should be inserted into. The cursor is left pointing at a random location. For an INTKEY table, only the nKey value of the key is used. pKey is ignored. For a ZERODATA table, the pData and nData are both ignored.

Specified by:

insert in interface ISqlJetBtreeCursor

Parameters:

pKey - The key of the new record

nKey - The key of the new record

pData - The data of the new record

nData - The data of the new record

zero - Number of extra 0 bytes to append to data

bias - True if this is likely an append

Throws:

SqlJetException

first

public boolean first()
              throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Move the cursor to the first entry in the table.

Specified by:

first in interface ISqlJetBtreeCursor

Returns:

false if the cursor actually points to something or true if the table is empty.

Throws:

SqlJetException

last

public boolean last()
             throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Move the cursor to the last entry in the table.

Specified by:

last in interface ISqlJetBtreeCursor

Returns:

true if the cursor actually points to something or false if the table is empty.

Throws:

SqlJetException

next

public boolean next()
             throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Advance the cursor to the next entry in the database. If successful then return false. If the cursor was already pointing to the last entry in the database before this routine was called, then return true.

Specified by:

next in interface ISqlJetBtreeCursor

Returns:

Throws:

SqlJetException

previous

public boolean previous()
                 throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Step the cursor to the back to the previous entry in the database. If successful then return false. If the cursor was already pointing to the first entry in the database before this routine was called, then return true.

Specified by:

previous in interface ISqlJetBtreeCursor

Throws:

SqlJetException

eof

public boolean eof()

Description copied from interface: ISqlJetBtreeCursor

Return TRUE if the cursor is not pointing at an entry of the table. TRUE will be returned after a call to sqlite3BtreeNext() moves past the last entry in the table or sqlite3BtreePrev() moves past the first entry. TRUE is also returned if the table is empty.

Specified by:

eof in interface ISqlJetBtreeCursor

Returns:

flags

public short flags()
            throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Return the flag byte at the beginning of the page that the cursor is currently pointing to.

Specified by:

flags in interface ISqlJetBtreeCursor

Returns:

Throws:

SqlJetException

getKeySize

public long getKeySize()
                throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Returns the size of the buffer needed to hold the value of the key for the current entry. If the cursor is not pointing to a valid entry, returns 0. For a table with the INTKEY flag set, this routine returns the key itself, not the number of bytes in the key.

Specified by:

getKeySize in interface ISqlJetBtreeCursor

Throws:

SqlJetException

key

public void key(int offset,
                int amt,
                ISqlJetMemoryPointer buf)
         throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Read part of the key associated with cursor pCur. Exactly "amt" bytes will be transfered into buf[]. The transfer begins at "offset". Throws error code if anything goes wrong. An error is thrown if "offset+amt" is larger than the available payload.

Specified by:

key in interface ISqlJetBtreeCursor

Throws:

SqlJetException

getCursorDb

public ISqlJetDbHandle getCursorDb()

Description copied from interface: ISqlJetBtreeCursor

Return the database connection handle for a cursor.

Specified by:

getCursorDb in interface ISqlJetBtreeCursor

Returns:

keyFetch

public ISqlJetMemoryPointer keyFetch(int[] amt)

Description copied from interface: ISqlJetBtreeCursor

For the entry that cursor pCur is point to, return as many bytes of the key or data as are available on the local b-tree page. Write the number of available bytes into *pAmt. The pointer returned is ephemeral. The key/data may move or be destroyed on the next call to any Btree routine, including calls from other threads against the same cache. Hence, a mutex on the BtShared should be held prior to calling this routine. These routines is used to get quick access to key and data in the common case where no overflow pages are used.

Specified by:

keyFetch in interface ISqlJetBtreeCursor

Returns:

dataFetch

public ISqlJetMemoryPointer dataFetch(int[] amt)

Description copied from interface: ISqlJetBtreeCursor

For the entry that cursor pCur is point to, return as many bytes of the key or data as are available on the local b-tree page. Write the number of available bytes into *pAmt. The pointer returned is ephemeral. The key/data may move or be destroyed on the next call to any Btree routine, including calls from other threads against the same cache. Hence, a mutex on the BtShared should be held prior to calling this routine. These routines is used to get quick access to key and data in the common case where no overflow pages are used.

Specified by:

dataFetch in interface ISqlJetBtreeCursor

Returns:

getDataSize

public int getDataSize()
                throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Return the number of bytes of data in the entry the cursor currently points to. If the cursor is not currently pointing to an entry (which can happen, for example, if the database is empty) then return 0.

Specified by:

getDataSize in interface ISqlJetBtreeCursor

Returns:

Throws:

SqlJetException

data

public void data(int offset,
                 int amt,
                 ISqlJetMemoryPointer buf)
          throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Read part of the data associated with cursor pCur. Exactly "amt" bytes will be transfered into buf[]. The transfer begins at "offset". Throws error code if anything goes wrong. An error is returned if "offset+amt" is larger than the available payload.

Specified by:

data in interface ISqlJetBtreeCursor

Throws:

SqlJetException

putData

public void putData(int offset,
                    int amt,
                    ISqlJetMemoryPointer data)
             throws SqlJetException

Description copied from interface: ISqlJetBtreeCursor

Must be a cursor opened for writing on an INTKEY table currently pointing at a valid table entry. This function modifies the data stored as part of that entry. Only the data content may only be modified, it is not possible to change the length of the data stored.

Specified by:

putData in interface ISqlJetBtreeCursor

Throws:

SqlJetException

cacheOverflow

public void cacheOverflow()

Description copied from interface: ISqlJetBtreeCursor

Set a flag on this cursor to cache the locations of pages from the overflow list for the current row. This is used by cursors opened for incremental blob IO only. This function sets a flag only. The actual page location cache (stored in BtCursor.aOverflow[]) is allocated and used by function accessPayload() (the worker function for sqlite3BtreeData() and sqlite3BtreePutData()).

Specified by:

cacheOverflow in interface ISqlJetBtreeCursor

saveCursorPosition

public boolean saveCursorPosition()
                           throws SqlJetException

Save the current cursor position in the variables BtCursor.nKey and BtCursor.pKey. The cursor's state is set to CURSOR_REQUIRESEEK.

Specified by:

saveCursorPosition in interface ISqlJetBtreeCursor

Throws:

SqlJetException

enterCursor

public void enterCursor()

Description copied from interface: ISqlJetBtreeCursor

Enter a mutex on a Btree given a cursor owned by that Btree.

Specified by:

enterCursor in interface ISqlJetBtreeCursor

leaveCursor

public void leaveCursor()

Description copied from interface: ISqlJetBtreeCursor

Leave a mutex on a Btree given a cursor owned by that Btree. These entry points are used by incremental I/O and can be omitted if that module is not used.

Specified by:

leaveCursor in interface ISqlJetBtreeCursor