org.tmatesoft.sqljet.core.internal
Interface ISqlJetPager

All Known Implementing Classes:
SqlJetPager

public interface ISqlJetPager

The pages cache subsystem reads and writes a file a page at a time and provides a journal for rollback.


Field Summary
static ISqlJetMemoryPointer aJournalMagic
          Journal files begin with the following magic string.
static java.lang.String JOURNAL
           
static java.lang.String MEMORY_DB
          In-memory database's "file-name".
static int PAGER_MAX_PGNO
          The maximum legal page number is (2^31 - 1).
static int SQLJET_DEFAULT_JOURNAL_SIZE_LIMIT
          If defined as non-zero, auto-vacuum is enabled by default.
static int SQLJET_MIN_SECTOR_SIZE
          The minimum sector size is 512
 
Method Summary
 ISqlJetPage acquirePage(int pageNumber, boolean read)
          Acquire a page.
 void begin(boolean exclusive)
          Acquire a write-lock on the database.
 void close()
          Shutdown the page cache.
 void commitPhaseOne(java.lang.String master, boolean noSync)
          Sync the database file for the pager pPager.
 void commitPhaseTwo()
          Commit all changes to the database and release the write lock.
 int getCacheSize()
           
 java.io.File getDirectoryName()
          Return the directory of the database file.
 ISqlJetFile getFile()
          Return the file handle for the database file associated with the pager.
 java.io.File getFileName()
          Return the path of the database file.
 ISqlJetFileSystem getFileSystem()
          Return the file system for the pager.
 SqlJetPagerJournalMode getJournalMode()
          Get the journal-mode for this pager.
 java.io.File getJournalName()
          Return the path of the journal file.
 long getJournalSizeLimit()
          Get the size-limit used for persistent journal files.
 SqlJetPagerLockingMode getLockingMode()
          Get the locking-mode for this pager.
 int getMaxPageCount()
          Return the current maximum page count.
 ISqlJetPage getPage(int pageNumber)
          Just call acquire( pageNumber, true);
 int getPageCount()
          Return the total number of pages in the disk file associated with pager.
 int getPageSize()
          Get the page size.
 int getRefCount()
          Return the number of references to the pager.
 SqlJetSafetyLevel getSafetyLevel()
          Get safety level
 ISqlJetMemoryPointer getTempSpace()
          Return a pointer to the "temporary page" buffer held internally by the pager.
 int imageSize()
          Return the current size of the database file image in pages.
 boolean isNoSync()
          Return true if fsync() calls are disabled for this pager.
 boolean isReadOnly()
          Return TRUE if the database file is opened read-only.
 ISqlJetPage lookupPage(int pageNumber)
          Acquire a page if it is already in the in-memory cache.
 void open(ISqlJetFileSystem fs, java.io.File fileName, java.util.Set<SqlJetPagerFlags> flags, SqlJetFileType type, java.util.Set<SqlJetFileOpenPermission> permissions)
          Open a new page cache.
 void openSavepoint(int nSavepoint)
          Ensure that there are at least nSavepoint savepoints open.
 void readFileHeader(int count, ISqlJetMemoryPointer buffer)
          Read the first N bytes from the beginning of the file into memory that buffer points to.
 void rollback()
          Rollback all changes.
 void savepoint(SqlJetSavepointOperation op, int iSavepoint)
          Parameter op is always either SAVEPOINT_ROLLBACK or SAVEPOINT_RELEASE.
 void setBusyhandler(ISqlJetBusyHandler busyHandler)
          Set the busy handler function.
 void setCacheSize(int cacheSize)
          Change the maximum number of in-memory pages that are allowed.
 void setJournalMode(SqlJetPagerJournalMode journalMode)
          Set the journal-mode for this pager.
 void setJournalSizeLimit(long limit)
          Set the size-limit used for persistent journal files.
 void setLockingMode(SqlJetPagerLockingMode lockingMode)
          Set the locking-mode for this pager.
 void setMaxPageCount(int maxPageCount)
          Attempt to set the maximum database page count if mxPage is positive.
 int setPageSize(int pageSize)
          Set the page size to pageSize.
 void setReiniter(ISqlJetPageCallback reinitier)
          Set the reinitializer for this pager.
 void setSafetyLevel(SqlJetSafetyLevel safetyLevel)
          Set safety level
 void sync()
          Sync the pager file to disk.
 void truncateImage(int pagesNumber)
          Truncate the in-memory database file image to nPage pages.
 

Field Detail

SQLJET_MIN_SECTOR_SIZE

static final int SQLJET_MIN_SECTOR_SIZE
The minimum sector size is 512


JOURNAL

static final java.lang.String JOURNAL
See Also:
Constant Field Values

aJournalMagic

static final ISqlJetMemoryPointer aJournalMagic
Journal files begin with the following magic string. The data was obtained from /dev/random. It is used only as a sanity check. Since version 2.8.0, the journal format contains additional sanity checking information. If the power fails while the journal is being written, semi-random garbage data might appear in the journal file after power is restored. If an attempt is then made to roll the journal back, the database could be corrupted. The additional sanity checking data is an attempt to discover the garbage in the journal and ignore it. The sanity checking information for the new journal format consists of a 32-bit checksum on each page of data. The checksum covers both the page number and the pPager->pageSize bytes of data for the page. This cksum is initialized to a 32-bit random value that appears in the journal file right after the header. The random initializer is important, because garbage data that appears at the end of a journal is likely data that was once in other files that have now been deleted. If the garbage data came from an obsolete journal file, the checksums might be correct. But by initializing the checksum to random value which is different for every journal, we minimize that risk.


PAGER_MAX_PGNO

static final int PAGER_MAX_PGNO
The maximum legal page number is (2^31 - 1).

See Also:
Constant Field Values

SQLJET_DEFAULT_JOURNAL_SIZE_LIMIT

static final int SQLJET_DEFAULT_JOURNAL_SIZE_LIMIT
If defined as non-zero, auto-vacuum is enabled by default. Otherwise it must be turned on for each database using "PRAGMA auto_vacuum = 1".


MEMORY_DB

static final java.lang.String MEMORY_DB
In-memory database's "file-name".

See Also:
Constant Field Values
Method Detail

open

void open(ISqlJetFileSystem fs,
          java.io.File fileName,
          java.util.Set<SqlJetPagerFlags> flags,
          SqlJetFileType type,
          java.util.Set<SqlJetFileOpenPermission> permissions)
          throws SqlJetException
Open a new page cache. The file to be cached need not exist. The file is not locked until the first call to getPage(int) and is only held open until the last page is released using #unref(ISqlJetPage). If fileName is null then a randomly-named temporary file is created and used as the file to be cached. The file will be deleted automatically when it is closed. If fileName is MEMORY_DB then all information is held in cache. It is never written to disk. This can be used to implement an in-memory database.

Parameters:
fs - The file system to use
fileName - Name of the database file to open
flags - flags controlling this file
type - file type passed through to ISqlJetFileSystem.open(java.io.File, SqlJetFileType, Set)
permissions - permissions passed through to ISqlJetFileSystem.open(java.io.File, SqlJetFileType, Set)
Throws:
SqlJetException

getFileName

java.io.File getFileName()
Return the path of the database file.

Returns:

getDirectoryName

java.io.File getDirectoryName()
Return the directory of the database file.

Returns:

getJournalName

java.io.File getJournalName()
Return the path of the journal file.

Returns:

getFileSystem

ISqlJetFileSystem getFileSystem()
Return the file system for the pager.

Returns:

getFile

ISqlJetFile getFile()
Return the file handle for the database file associated with the pager. This might return NULL if the file has not yet been opened.

Returns:

isReadOnly

boolean isReadOnly()
Return TRUE if the database file is opened read-only. Return FALSE if the database is (in theory) writable.

Returns:

isNoSync

boolean isNoSync()
Return true if fsync() calls are disabled for this pager. Return FALSE if fsync()s are executed normally.

Returns:

getLockingMode

SqlJetPagerLockingMode getLockingMode()
Get the locking-mode for this pager.

Returns:

setLockingMode

void setLockingMode(SqlJetPagerLockingMode lockingMode)
Set the locking-mode for this pager.

Parameters:
lockingMode -

getJournalMode

SqlJetPagerJournalMode getJournalMode()
Get the journal-mode for this pager.

Parameters:
journalMode -
Returns:

setJournalMode

void setJournalMode(SqlJetPagerJournalMode journalMode)
Set the journal-mode for this pager.

Parameters:
journalMode -

getJournalSizeLimit

long getJournalSizeLimit()
Get the size-limit used for persistent journal files.

Returns:

setJournalSizeLimit

void setJournalSizeLimit(long limit)
Set the size-limit used for persistent journal files.

Parameters:
limit -

setSafetyLevel

void setSafetyLevel(SqlJetSafetyLevel safetyLevel)
Set safety level

Parameters:
safetyLevel -

getSafetyLevel

SqlJetSafetyLevel getSafetyLevel()
Get safety level

Returns:

getTempSpace

ISqlJetMemoryPointer getTempSpace()
Return a pointer to the "temporary page" buffer held internally by the pager. This is a buffer that is big enough to hold the entire content of a database page. This buffer is used internally during rollback and will be overwritten whenever a rollback occurs. But other modules are free to use it too, as long as no rollbacks are happening.

Returns:

setBusyhandler

void setBusyhandler(ISqlJetBusyHandler busyHandler)
Set the busy handler function.

Parameters:
busyHandler -

setReiniter

void setReiniter(ISqlJetPageCallback reinitier)
Set the reinitializer for this pager. If not NULL, the reinitializer is called when the content of a page in cache is restored to its original value as a result of a rollback. The callback gives higher-level code an opportunity to restore the EXTRA section to agree with the restored page data.

Parameters:
reinitier -

setPageSize

int setPageSize(int pageSize)
                throws SqlJetException
Set the page size to pageSize. If the suggest new page size is inappropriate, then an alternative page size is set to that value before returning.

Parameters:
pageSize -
Returns:
Throws:
SqlJetException

getPageSize

int getPageSize()
Get the page size.

Returns:

setMaxPageCount

void setMaxPageCount(int maxPageCount)
                     throws SqlJetException
Attempt to set the maximum database page count if mxPage is positive. Make no changes if mxPage is zero or negative. And never reduce the maximum page count below the current size of the database.

Parameters:
maxPageCount -
Throws:
SqlJetException

getMaxPageCount

int getMaxPageCount()
Return the current maximum page count.

Returns:

setCacheSize

void setCacheSize(int cacheSize)
Change the maximum number of in-memory pages that are allowed.

Parameters:
cacheSize -

readFileHeader

void readFileHeader(int count,
                    ISqlJetMemoryPointer buffer)
                    throws SqlJetIOException
Read the first N bytes from the beginning of the file into memory that buffer points to. No error checking is done. The rational for this is that this function may be called even if the file does not exist or contain a header. In these cases sqlite3OsRead() will return an error, to which the correct response is to zero the memory at pDest and continue. A real IO error will presumably recur and be picked up later (Todo: Think about this).

Parameters:
count -
buffer -
Throws:
SqlJetIOException

getPageCount

int getPageCount()
                 throws SqlJetException
Return the total number of pages in the disk file associated with pager. If the PENDING_BYTE lies on the page directly after the end of the file, then consider this page part of the file too. For example, if PENDING_BYTE is byte 4096 (the first byte of page 5) and the size of the file is 4096 bytes, 5 is returned instead of 4.

Returns:
pages count
Throws:
SqlJetException - if pager is in error state.

close

void close()
           throws SqlJetException
Shutdown the page cache. Free all memory and close all files. If a transaction was in progress when this routine is called, that transaction is rolled back. All outstanding pages are invalidated and their memory is freed. Any attempt to use a page associated with this page cache after this function returns will likely result in a coredump. This function always succeeds. If a transaction is active an attempt is made to roll it back. If an error occurs during the rollback a hot journal may be left in the filesystem but no error is returned to the caller.

Throws:
SqlJetException

acquirePage

ISqlJetPage acquirePage(int pageNumber,
                        boolean read)
                        throws SqlJetException
Acquire a page. A read lock on the disk file is obtained when the first page is acquired. This read lock is dropped when the last page is released. This routine works for any page number greater than 0. If the database file is smaller than the requested page, then no actual disk read occurs and the memory image of the page is initialized to all zeros. The extra data appended to a page is always initialized to zeros the first time a page is loaded into memory. The acquisition might fail for several reasons. In all cases, an appropriate error code is returned and *ppPage is set to NULL. See also lookupPage(int). Both this routine and lookupPage(int) attempt to find a page in the in-memory cache first. If the page is not already in memory, this routine goes to disk to read it in whereas lookupPage(int) just returns 0. This routine acquires a read-lock the first time it has to go to disk, and could also playback an old journal if necessary. Since lookupPage(int) never goes to disk, it never has to deal with locks or journal files. If noContent is false, the page contents are actually read from disk. If noContent is true, it means that we do not care about the contents of the page at this time, so do not do a disk read. Just fill in the page content with zeros. But mark the fact that we have not read the content by setting the PgHdr.needRead flag. Later on, if sqlite3PagerWrite() is called on this page or if this routine is called again with noContent==0, that means that the content is needed and the disk read should occur at that point.

Parameters:
pageNumber - Page number to fetch
read - Do not bother reading content from disk if false
Returns:
Throws:
SqlJetException

getPage

ISqlJetPage getPage(int pageNumber)
                    throws SqlJetException
Just call acquire( pageNumber, true);

Parameters:
pageNumber - Page number to fetch
Returns:
Throws:
SqlJetException

lookupPage

ISqlJetPage lookupPage(int pageNumber)
                       throws SqlJetException
Acquire a page if it is already in the in-memory cache. Do not read the page from disk. Return a pointer to the page, or null if the page is not in cache. See also getPage(int). The difference between this routine and getPage(int) is that getPage(int) will go to the disk and read in the page if the page is not already in cache. This routine returns null if the page is not in cache or if a disk I/O error has ever happened.

Parameters:
pageNumber - Page number to lookup
Returns:
Throws:
SqlJetException

begin

void begin(boolean exclusive)
           throws SqlJetException
Acquire a write-lock on the database. The lock is removed when the any of the following happen: The parameter indicates how much space in bytes to reserve for a master journal file-name at the start of the journal when it is created. A journal file is opened if this is not a temporary file. For temporary files, the opening of the journal file is deferred until there is an actual need to write to the journal. If the database is already reserved for writing, this routine is a no-op. If exclusive is true, go ahead and get an EXCLUSIVE lock on the file immediately instead of waiting until we try to flush the cache. The exclusive is ignored if a transaction is already active.

Parameters:
exclusive -
Throws:
SqlJetException

commitPhaseOne

void commitPhaseOne(java.lang.String master,
                    boolean noSync)
                    throws SqlJetException
Sync the database file for the pager pPager. zMaster points to the name of a master journal file that should be written into the individual journal file. zMaster may be NULL, which is interpreted as no master journal (a single database transaction). This routine ensures that the journal is synced, all dirty pages written to the database file and the database file synced. The only thing that remains to commit the transaction is to delete the journal file (or master journal file if specified). Note that if zMaster==NULL, this does not overwrite a previous value passed to an sqlite3PagerCommitPhaseOne() call. If the final parameter - noSync - is true, then the database file itself is not synced. The caller must call sqlite3PagerSync() directly to sync the database file before calling CommitPhaseTwo() to delete the journal file in this case.

Parameters:
master -
noSync -
Throws:
SqlJetException

commitPhaseTwo

void commitPhaseTwo()
                    throws SqlJetException
Commit all changes to the database and release the write lock. If the commit fails for any reason, a rollback attempt is made and an error code is returned. If the commit worked, SQLITE_OK is returned.

Throws:
SqlJetException

rollback

void rollback()
              throws SqlJetException
Rollback all changes. The database falls back to PAGER_SHARED mode. All in-memory cache pages revert to their original data contents. The journal is deleted. This routine cannot fail unless some other process is not following the correct locking protocol or unless some other process is writing trash into the journal file (SQLITE_CORRUPT) or unless a prior malloc() failed (SQLITE_NOMEM). Appropriate error codes are returned for all these occasions. Otherwise, SQLITE_OK is returned.

Throws:
SqlJetException

getRefCount

int getRefCount()
Return the number of references to the pager.

Returns:

sync

void sync()
          throws SqlJetIOException
Sync the pager file to disk.

Throws:
SqlJetIOException

openSavepoint

void openSavepoint(int nSavepoint)
                   throws SqlJetException
Ensure that there are at least nSavepoint savepoints open.

Throws:
SqlJetException

savepoint

void savepoint(SqlJetSavepointOperation op,
               int iSavepoint)
               throws SqlJetException
Parameter op is always either SAVEPOINT_ROLLBACK or SAVEPOINT_RELEASE. If it is SAVEPOINT_RELEASE, then release and destroy the savepoint with index iSavepoint. If it is SAVEPOINT_ROLLBACK, then rollback all changes that have occured since savepoint iSavepoint was created. In either case, all savepoints with an index greater than iSavepoint are destroyed. If there are less than (iSavepoint+1) active savepoints when this function is called it is a no-op.

Throws:
SqlJetException

truncateImage

void truncateImage(int pagesNumber)
Truncate the in-memory database file image to nPage pages. This function does not actually modify the database file on disk. It just sets the internal state of the pager object so that the truncation will be done when the current transaction is committed.

Parameters:
pageNumber -

imageSize

int imageSize()
Return the current size of the database file image in pages. This function differs from sqlite3PagerPagecount() in two ways: a) It may only be called when at least one reference to a database page is held. This guarantees that the database size is already known and a call to sqlite3OsFileSize() is not required. b) The return value is not adjusted for the locking page.


getCacheSize

int getCacheSize()
Returns: