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
Method Summary |
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 java.lang.Object |
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
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
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 indexnKey
- Integer key for tables. Size of pKey for indicesbias
- 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 recordnKey
- The key of the new recordpData
- The data of the new recordnData
- The data of the new recordzero
- Number of extra 0 bytes to append to databias
- 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