com.almworks.sqlite4java
Class SQLiteBackup

java.lang.Object
  com.almworks.sqlite4java.SQLiteBackup

public class SQLiteBackup
extends java.lang.Object

SQLiteBackup wraps an instance of SQLite database backup, represented as sqlite3_backup* in SQLite C API.

Usage example:

 SQLiteBackup backup = connection.initializeBackup(new File("filename"));
 try {
   while (!backup.isFinished()) {
     backup.backupStep(32);
   }
 } finally {
   backup.dispose();
 }
 

Unless a method is marked as thread-safe, it is confined to the thread that has opened the connection to the source database. Calling a confined method from a different thread will result in exception.

Author:

Igor Korsunov

See Also:

SQLite Online Backup API, Using the SQLite Online Backup API, SQLiteConnection.initializeBackup(java.lang.String, java.io.File, int)

Method Summary

boolean	backupStep(int pagesToBackup) Copy up to pagesToBackup pages from source database to destination.
void	dispose() Disposes this backup instance and connection to the destination database.
void	dispose(boolean disposeDestination) Dispose this backup instance and, if disposeDestination is true, dispose the connection to the destination database as well.
SQLiteConnection	getDestinationConnection() Returns connection to the destination database, that was opened by SQLiteConnection.initializeBackup(java.lang.String, java.io.File, int).
int	getPageCount() Returns the total number of pages in the source database.
int	getRemaining() Returns the number of pages still to be backed up.
boolean	isFinished() Checks whether the backup was successfully finished.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

backupStep

public boolean backupStep(int pagesToBackup)
                   throws SQLiteException,
                          SQLiteBusyException

Copy up to pagesToBackup pages from source database to destination. If pagesToBackup is negative, all remaining pages are copied.

If source database is modified during backup by any connection other than the source connection, then the backup will be restarted by the next call to backupStep. If the source database is modified by the source connection itself, then destination database is be updated without backup restart.

Parameters:

pagesToBackup - the maximum number of pages to back up during this step, or negative number to back up all pages

Returns:

true if the backup was finished, false if there are still pages to back up

Throws:

SQLiteException - if SQLite returns an error or if the call violates the contract of this class

SQLiteBusyException - if SQLite cannot establish SHARED_LOCK on the source database or RESERVED_LOCK on the destination database or source connection is currently used to write to the database. In these cases call to backupStep can be retried later.

See Also:

sqlite3_backup_step

isFinished

public boolean isFinished()

Checks whether the backup was successfully finished.

Returns:

true if last call to backupStep(int) has returned true.

getDestinationConnection

public SQLiteConnection getDestinationConnection()

Returns connection to the destination database, that was opened by SQLiteConnection.initializeBackup(java.lang.String, java.io.File, int).

Important! If you call this method, you should be careful about disposing the connection you got. You should only dispose it after disposing SQLiteBackup instance, otherwise the JVM might crash.

Returns:

destination database connection

dispose

public void dispose(boolean disposeDestination)

Dispose this backup instance and, if disposeDestination is true, dispose the connection to the destination database as well.

You might want to pass false to this method to subsequently call getDestinationConnection() and perform any actions on the fresh backup of the database, then dispose it yourself.

Parameters:

disposeDestination - if true, connection to the destination database will be disposed

dispose

public void dispose()

Disposes this backup instance and connection to the destination database.

This is a convenience method, equivalent to dispose(true).

See Also:

dispose(boolean)

getPageCount

public int getPageCount()
                 throws SQLiteException

Returns the total number of pages in the source database.

Returns:

total number of pages to back up

Throws:

SQLiteException - if called from a different thread or if source or destination connection are disposed

See Also:

SQLite Online Backup API

getRemaining

public int getRemaining()
                 throws SQLiteException

Returns the number of pages still to be backed up.

Returns:

number of remaining pages

Throws:

SQLiteException - if called from a different thread or if source or destination connection are disposed

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object