com.almworks.sqlite4java
Class SQLiteBackup

java.lang.Object
  extended by 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.

Use example:

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

Unless a method is marked as thread-safe, it is confined to the thread that has opened the connection to 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

Method Summary
 boolean backupStep(int pagesToBackup)
          Copy up to pagesToBackup pages from source database to destination.
 void dispose()
          Dispose this backup instance and connection to destination database.
 void dispose(boolean disposeDestination)
          Dispose this backup instance and, if disposeDestination is true, connection to destination database.
 SQLiteConnection getDestinationConnection()
          Returns connection to destination database, that was opened by SQLiteConnection.initializeBackup(java.lang.String, java.io.File, int).
 int getPageCount()
          Returns the total number of pages in source database.
 int getRemaining()
          Returns the number of pages still to be backed up.
 boolean isFinished()
          Checks whether back up 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 are negative, all remaining pages are copied.

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

Parameters:
pagesToBackup - - the number of page, that will be backed up during this step.
Returns:
true if back up was finished, false if there are still more pages to back up.
Throws:
SQLiteException - if SQLite return an error or if the call violates the contract of this class
SQLiteBusyException - if SQLite cannot established SHARED_LOCK on source DB or RESERVED_LOCK on destination DB or source connection is used to write to DB. In these cases call to backupStep can be retried later
See Also:
sqlite3_backup_step

isFinished

public boolean isFinished()
Checks whether back up was successfully finished.

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

getDestinationConnection

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

NB! If you get connection to destination database, you should care about disposing order of backup and that connection. That connection must be disposed after disposing SQLiteBackup instance.

Returns:
destination database connection.

dispose

public void dispose(boolean disposeDestination)
Dispose this backup instance and, if disposeDestination is true, connection to destination database.

Parameters:
disposeDestination - if true, connection to destination database will be disposed.

dispose

public void dispose()
Dispose this backup instance and connection to destination database.

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


getPageCount

public int getPageCount()
                 throws SQLiteException
Returns the total number of pages in source database.

Returns:
destination database's number of pages.
Throws:
SQLiteException - if called from differed thread or if source or destination connection are disposed

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 differed thread or if source or destination connection are disposed

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object