Interface ISqlJetBtreeCursor

All Known Implementing Classes:
SqlJetBtreeCursor

public interface ISqlJetBtreeCursor
Author:
TMate Software Ltd., Sergey Scherbina (sergey.scherbina@gmail.com)
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Maximum depth of an SQLite B-Tree structure.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Set a flag on this cursor to cache the locations of pages from the overflow list for the current row.
    void
    Clear the current cursor position.
    void
    Close a cursor.
    boolean
    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.
    dataFetch(int[] pAmt)
    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 the entry that the cursor is pointing to.
    void
    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
    Move the cursor to the first entry in the table.
    short
    Return the flag byte at the beginning of the page that the cursor is currently pointing to.
    Return the database connection handle for a cursor.
    int
    Return the number of bytes of data in the entry the cursor currently points to.
    long
    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 nZero, 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.
    keyFetch(int[] pAmt)
    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
    Move the cursor to the last entry in the table.
    void
    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 pUnKey, long intKey, boolean bias)
    Move the cursor so that it points to an entry near the key specified by pIdxKey or intKey.
    boolean
    Advance the cursor to the next entry in the database.
    boolean
    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
    Restore the cursor to the position it was in (or as close to as possible) when saveCursorPosition() was called.
    boolean
    Save the current cursor position in the variables BtCursor.nKey and BtCursor.pKey.
  • Field Details

    • BTCURSOR_MAX_DEPTH

      static final int BTCURSOR_MAX_DEPTH
      Maximum depth of an SQLite B-Tree structure. Any B-Tree deeper than this will be declared corrupt. This value is calculated based on a maximum database size of 2^31 pages a minimum fanout of 2 for a root-node and 3 for all other internal nodes. If a tree that appears to be taller than this is encountered, it is assumed that the database is corrupt.
      See Also:
  • Method Details

    • closeCursor

      void closeCursor() throws SqlJetException
      Close a cursor. The read lock on the database file is released when the last cursor is closed.
      Throws:
      SqlJetException
    • moveTo

      int moveTo(ISqlJetMemoryPointer pKey, long nKey, boolean bias) throws SqlJetException
      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.
      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

      int moveToUnpacked(ISqlJetUnpackedRecord pUnKey, long intKey, boolean bias) throws SqlJetException
      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.
      Throws:
      SqlJetException
    • cursorHasMoved

      boolean cursorHasMoved() throws SqlJetException
      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.
      Returns:
      true if the cursor has moved and false if not.
      Throws:
      SqlJetException
    • delete

      void delete() throws SqlJetException
      Delete the entry that the cursor is pointing to. The cursor is left pointing at a arbitrary location.
      Throws:
      SqlJetException
    • insert

      void insert(ISqlJetMemoryPointer pKey, long nKey, ISqlJetMemoryPointer pData, int nData, int nZero, boolean bias) throws SqlJetException
      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.
      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
      nZero - Number of extra 0 bytes to append to data
      bias - True if this is likely an append
      Throws:
      SqlJetException
    • first

      boolean first() throws SqlJetException
      Move the cursor to the first entry in the table.
      Returns:
      false if the cursor actually points to something or true if the table is empty.
      Throws:
      SqlJetException
    • last

      boolean last() throws SqlJetException
      Move the cursor to the last entry in the table.
      Returns:
      true if the cursor actually points to something or false if the table is empty.
      Throws:
      SqlJetException
    • next

      boolean next() throws SqlJetException
      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.
      Returns:
      Throws:
      SqlJetException
    • eof

      boolean eof()
      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.
      Returns:
      Throws:
      SqlJetException
    • flags

      short flags() throws SqlJetException
      Return the flag byte at the beginning of the page that the cursor is currently pointing to.
      Returns:
      Throws:
      SqlJetException
    • previous

      boolean previous() throws SqlJetException
      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.
      Throws:
      SqlJetException
    • getKeySize

      long getKeySize() throws SqlJetException
      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.
      Throws:
      SqlJetException
    • key

      void key(int offset, int amt, ISqlJetMemoryPointer buf) throws SqlJetException
      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.
      Throws:
      SqlJetException
    • getCursorDb

      ISqlJetDbHandle getCursorDb() throws SqlJetException
      Return the database connection handle for a cursor.
      Returns:
      Throws:
      SqlJetException
    • keyFetch

      ISqlJetMemoryPointer keyFetch(int[] pAmt) throws SqlJetException
      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.
      Returns:
      Throws:
      SqlJetException
    • dataFetch

      ISqlJetMemoryPointer dataFetch(int[] pAmt) throws SqlJetException
      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.
      Returns:
      Throws:
      SqlJetException
    • getDataSize

      int getDataSize() throws SqlJetException
      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.
      Returns:
      Throws:
      SqlJetException
    • data

      void data(int offset, int amt, ISqlJetMemoryPointer buf) throws SqlJetException
      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.
      Parameters:
      offset -
      amt -
      buf -
      Throws:
      SqlJetException
    • putData

      void putData(int offset, int amt, ISqlJetMemoryPointer data) throws SqlJetException
      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.
      Parameters:
      offset -
      amt -
      data -
      Throws:
      SqlJetException
    • cacheOverflow

      void cacheOverflow() throws SqlJetException
      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()).
      Throws:
      SqlJetException
    • clearCursor

      void clearCursor() throws SqlJetException
      Clear the current cursor position.
      Throws:
      SqlJetException
    • enterCursor

      void enterCursor()
      Enter a mutex on a Btree given a cursor owned by that Btree.
    • leaveCursor

      void leaveCursor()
      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.
    • saveCursorPosition

      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.
      Throws:
      SqlJetException
    • restoreCursorPosition

      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().
      Throws:
      SqlJetException