com.syncbuilder.storage
Interface Database

All Known Implementing Classes:

DatabaseBase

public abstract interface Database

This interface is implemented by all classes which represent a database. This includes databases on the device, as well as those in any other storage.

Field Summary

static int	OPEN_DEFAULT Opened with default settings (read/write, exclusive).
static int	OPEN_EXCLUSIVE Opened for exclusive access.
static int	OPEN_READ Opened for read access.
static int	OPEN_WRITE Opened for write access.

Method Summary

void	close() Closes the database.
AppBlock	createAppBlock() Create a new instance of an AppBlock that matches the Database.
Pref	createPref(int id) Create a new instance of a Pref that matches the Database.
Pref	createPref(int id, int version, boolean backed_up) Create a new instance of a Pref that matches the Database.
Record	createRecord() Create a new Record with an unspecified RecordID (0).
Record	createRecord(byte[] contents, RecordID id, int index, int attr, int cat) Create a new Record with the specified RecordID.
Record	createRecord(RecordID id) Create a new Record with the specified RecordID.
Resource	createResource() Create a new instance of a Resource that matches the Database.
Resource	createResource(byte[] contents, Char4 type, int id, int index) Create a new instance of a Resource that matches the Database.
Resource	createResource(Char4 type, int id) Create a new instance of a Resource that matches the Database.
SortBlock	createSortBlock() Create a new instance of a SortBlock that matches the Database.
void	deleteAllRecords() Delete ALL records in the database.
void	deleteAllResources() Delete ALL resources.
void	deleteCategory(int category) Delete all records from a specified category
void	deleteRecord(RecordID uid) Delete the record with the specified UID from the database.
void	deleteResource(Char4 type, int id) Delete a single resource from the database.
AppBlock	getAppBlock() Get a new instance of an AppBlock that matches the Database.
DBInfo	getDBInfo() Return meta-information about the Database.
Record	getNextModifiedRecord() Retrieve the next modified Record from the Database.
Record	getNextModifiedRecord(int category) Retrieve the next modified Record within the specified category from the Database.
Record	getNextRecord(int category) Retrieve the next Record within the specified category from the Database.
Pref	getPref(int id) Get one of the preferences which are associated with the same app as the database.
Pref	getPref(int id, boolean backed_up) Get one of the preferences which are associated with the same app as the database.
Record	getRecord(int index) Retrieve the Record with the specified index from the Database.
Record	getRecord(RecordID uid) Retrieve the Record with the specified UID from the Database.
int	getRecordCount() Return the number of records in the Database.
RecordID[]	getRecordIDs() Return the UIDs of all records in the DB, in an unsorted fashion.
RecordID[]	getRecordIDs(boolean sort) Return the UIDs of all records in the DB.
RecordID[]	getRecordIDs(boolean sort, int start) Return the UIDs of selected records in the DB.
RecordID[]	getRecordIDs(boolean sort, int start, int max) Return the UIDs of selected records in the DB.
Resource	getResource(Char4 type, int id) Get a resource through the type and id.
Resource	getResource(int index) Get a resource through the specified index.
SortBlock	getSortBlock() Get a new instance of a SortBlock that matches the Database.
void	moveCategory(int from, int to)
void	purgeRecords() Deletes all records which are marked as archived or deleted
void	putRecord(Record record) Stores a record in the database.
void	putResource(Resource resource) Store a resource in the database.
void	resetFlags() For record databases, reset all dirty flags.
void	resetNext() Resets the 'next record' index to the beginning
void	setAppBlock(AppBlock appblock) Associate the AppBlock with the Database.
void	setDBInfo(DBInfo dbinfo) Associate a complete set of meta-information with the Database.
void	setPref(Pref pref) Store a Pref which is associated with the same app as the database to the database.
void	setSortBlock(SortBlock sortblock) Associate the SortBlock with the Database.

Field Detail

OPEN_READ

public static final int OPEN_READ

Opened for read access. Not all implementations will honour this flag.

OPEN_WRITE

public static final int OPEN_WRITE

Opened for write access. Not all implementations will honour this flag.

OPEN_EXCLUSIVE

public static final int OPEN_EXCLUSIVE

Opened for exclusive access. Not all implementations will honour this flag.

OPEN_DEFAULT

public static final int OPEN_DEFAULT

Opened with default settings (read/write, exclusive). Not all implementations will honour this flag.

Method Detail

getAppBlock

public AppBlock getAppBlock()
                     throws DatabaseException

Get a new instance of an AppBlock that matches the Database.

setAppBlock

public void setAppBlock(AppBlock appblock)
                 throws DatabaseException

Associate the AppBlock with the Database.

createAppBlock

public AppBlock createAppBlock()

Create a new instance of an AppBlock that matches the Database.

Note: Avoid using the new-operator in order to create an AppBlock.

getSortBlock

public SortBlock getSortBlock()
                       throws DatabaseException

Get a new instance of a SortBlock that matches the Database.

setSortBlock

public void setSortBlock(SortBlock sortblock)
                  throws DatabaseException

Associate the SortBlock with the Database.

createSortBlock

public SortBlock createSortBlock()

Create a new instance of a SortBlock that matches the Database.

Note: Avoid using the new-operator in order to create a SortBlock.

getRecord

public Record getRecord(int index)
                 throws DatabaseException

Retrieve the Record with the specified index from the Database.

Parameters:

index - the index of the Record

Returns:

a specialization of the Record class which matches the creator of the Database, or null, if the specified Record could not be found.

getRecord

public Record getRecord(RecordID uid)
                 throws DatabaseException

Retrieve the Record with the specified UID from the Database.

Parameters:

uid - the UID of the Record

Returns:

a specialization of the Record class which matches the creator of the Database, or null, if the specified Record could not be found.

getNextRecord

public Record getNextRecord(int category)
                     throws DatabaseException

Retrieve the next Record within the specified category from the Database. The database keeps an internal 'next record' index pointer, which it updates automatically.

Parameters:

category - the category from which the Record shall be taken

Returns:

a specialization of the Record class which matches the creator of the Database, or null, if the specified Record could not be found.

See Also:

resetNext()

getNextModifiedRecord

public Record getNextModifiedRecord()
                             throws DatabaseException

Retrieve the next modified Record from the Database. The database keeps an internal 'next record' index pointer, which it updates automatically.

Returns:

a specialization of the Record class which matches the creator of the Database, or null, if the specified Record could not be found.

See Also:

resetNext()

getNextModifiedRecord

public Record getNextModifiedRecord(int category)
                             throws DatabaseException

Retrieve the next modified Record within the specified category from the Database. The database keeps an internal 'next record' index pointer, which it updates automatically.

Parameters:

category - the category from which the Record shall be taken

Returns:

a specialization of the Record class which matches the creator of the Database, or null, if the specified Record could not be found.

See Also:

resetNext()

resetNext

public void resetNext()
               throws DatabaseException

Resets the 'next record' index to the beginning

putRecord

public void putRecord(Record record)
               throws DatabaseException

Stores a record in the database. If the Record had an unspecified RecordID before, then a new valid RecordID will be assigned to it.

createRecord

public Record createRecord()

Create a new Record with an unspecified RecordID (0).

Note: Avoid using the new-operator in order to create a Record.

createRecord

public Record createRecord(RecordID id)

Create a new Record with the specified RecordID.

Note: Avoid using the new-operator in order to create a Record.

Parameters:

id - the unique ID of the record

createRecord

public Record createRecord(byte[] contents,
                           RecordID id,
                           int index,
                           int attr,
                           int cat)

Create a new Record with the specified RecordID.

Note: Avoid using the new-operator in order to create a Record.

Parameters:

contents - the raw contents of the Record

id - the unique ID of the record

index - the index of the record within the database

attr - the attributes of the record

cat - the category of the record

deleteRecord

public void deleteRecord(RecordID uid)
                  throws DatabaseException

Delete the record with the specified UID from the database.

Parameters:

uid - the UID (not the index!) of the record

deleteAllRecords

public void deleteAllRecords()
                      throws DatabaseException

Delete ALL records in the database.
Use with caution!

deleteCategory

public void deleteCategory(int category)
                    throws DatabaseException

Delete all records from a specified category

Parameters:

category - the category

moveCategory

public void moveCategory(int from,
                         int to)
                  throws DatabaseException

getRecordIDs

public RecordID[] getRecordIDs()
                        throws DatabaseException

Return the UIDs of all records in the DB, in an unsorted fashion.

getRecordIDs

public RecordID[] getRecordIDs(boolean sort)
                        throws DatabaseException

Return the UIDs of all records in the DB. If you ask for a sorted list of UIDs, then the application on the Palm device will be asked to sort the records before their UIDs are returned.

getRecordIDs

public RecordID[] getRecordIDs(boolean sort,
                               int start)
                        throws DatabaseException

Return the UIDs of selected records in the DB. If you ask for a sorted list of UIDs, then the application on the Palm device will be asked to sort the records before their UIDs are returned.

getRecordIDs

public RecordID[] getRecordIDs(boolean sort,
                               int start,
                               int max)
                        throws DatabaseException

Return the UIDs of selected records in the DB. If you ask for a sorted list of UIDs, then the application on the Palm device will be asked to sort the records before their UIDs are returned.

purgeRecords

public void purgeRecords()
                  throws DatabaseException

Deletes all records which are marked as archived or deleted

getResource

public Resource getResource(int index)
                     throws DatabaseException

Get a resource through the specified index.

getResource

public Resource getResource(Char4 type,
                            int id)
                     throws DatabaseException

Get a resource through the type and id.

putResource

public void putResource(Resource resource)
                 throws DatabaseException

Store a resource in the database.

createResource

public Resource createResource()

Create a new instance of a Resource that matches the Database.

Note: Avoid using the new-operator in order to create an Resource.

createResource

public Resource createResource(Char4 type,
                               int id)

Create a new instance of a Resource that matches the Database.

Note: Avoid using the new-operator in order to create an Resource.

Parameters:

type - the type of the Resource

id - the id of the Resource

createResource

public Resource createResource(byte[] contents,
                               Char4 type,
                               int id,
                               int index)

Create a new instance of a Resource that matches the Database.

Note: Avoid using the new-operator in order to create an Resource.

Parameters:

contents - the raw contents of the Resource

type - the type of the Resource

id - the id of the Resource

index - the index of the Resource with in the database

deleteResource

public void deleteResource(Char4 type,
                           int id)
                    throws DatabaseException

Delete a single resource from the database.

Parameters:

type - the type of the Resource

id - the id of the Resource

deleteAllResources

public void deleteAllResources()
                        throws DatabaseException

Delete ALL resources.
Use with caution!

getPref

public Pref getPref(int id)
             throws DatabaseException,
                    NoCreatorException

Get one of the preferences which are associated with the same app as the database. The Pref is taken from the saved preferences.

Parameters:

id - the id of the preference

getPref

public Pref getPref(int id,
                    boolean backed_up)
             throws DatabaseException,
                    NoCreatorException

Get one of the preferences which are associated with the same app as the database.

Parameters:

id - the id of the preference

backed_up - Shall the Pref be taken from the saved (true) or from the unsaved (false) preferences?

setPref

public void setPref(Pref pref)
             throws DatabaseException

Store a Pref which is associated with the same app as the database to the database. Since the Creator ID is taken from the Pref object and not from the database object, this method will also happily write preferences which belong to a different application.

createPref

public Pref createPref(int id)

Create a new instance of a Pref that matches the Database.

Note: Avoid using the new-operator in order to create a Pref.

Parameters:

id - the id of the preference

createPref

public Pref createPref(int id,
                       int version,
                       boolean backed_up)

Create a new instance of a Pref that matches the Database.

Note: Avoid using the new-operator in order to create a Pref.

Parameters:

id - the id of the preference

version - the version number of the application

backed_up - Shall the Pref be taken from the saved (true) or from the unsaved (false) preferences?

close

public void close()
           throws DatabaseException

Closes the database. The Database-object shall no longer be used after the invocation of this method!

resetFlags

public void resetFlags()
                throws DatabaseException

For record databases, reset all dirty flags. For both record and resource databases, set the last sync time to now.

getRecordCount

public int getRecordCount()
                   throws DatabaseException

Return the number of records in the Database.

getDBInfo

public DBInfo getDBInfo()
                 throws DatabaseException

Return meta-information about the Database.

setDBInfo

public void setDBInfo(DBInfo dbinfo)
               throws DatabaseException

Associate a complete set of meta-information with the Database.