superwaba.ext.xplat.sync
Class RemoteCatalog

java.lang.Object
  |
  +--superwaba.ext.xplat.sync.RemoteCatalog

public final class RemoteCatalog

extends java.lang.Object

This class represents a Palm DataBase that is being synchronized.

Field Summary

protected int	mode
protected java.lang.String	name
protected boolean	open
protected int	recIndex
static int	RECORD_SIZE_AUTO
protected int	wRecordSize

Constructor Summary

RemoteCatalog(java.lang.String name)
Opens a remote catalog in READ_ONLY mode.

RemoteCatalog(java.lang.String name, int mode)
Opens a remote catalog in the given mode.

RemoteCatalog(java.lang.String name, int mode, int recordSize)
Opens a remote catalog with the given name.

Method Summary

boolean	close() Closes this catalog.
void	delete() Completely deletes this database, closing it first.
boolean	deleteRecord(int index) Deletes the given record index.
int	getNextModifiedRecordIndex() Returns the next modified record index.
int	getRecordCount() Returns the number of records inside this database
int	getRecordPos() Returns the current record position or -1 if there is no current record.
boolean	isOpen() Returns if this remote catalog is open or closed.
static java.lang.String[]	listCatalogs(int crtr, int type) Lists the available catalogs on the device that has the given creator id and type.
boolean	readRecord(int index, RemoteCatalogRecord rec) Fetches the given index, passing to the rec a DataStream to read the record information.
int	skipBytes(int count) Offsets the cursor in the current record a number of bytes.
boolean	writeRecord(int index, RemoteCatalogRecord rec) Write the record at the given index.

Methods inherited from class java.lang.Object

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

Field Detail

name

protected java.lang.String name

mode

protected int mode

open

protected boolean open

recIndex

protected int recIndex

wRecordSize

protected int wRecordSize

RECORD_SIZE_AUTO

public static int RECORD_SIZE_AUTO

Constructor Detail

RemoteCatalog

public RemoteCatalog(java.lang.String name,
                     int mode,
                     int recordSize)

Opens a remote catalog with the given name. Important: only one catalog can be open at a time. Trying to open a new catalog before explicitly closing the former will throw a RuntimeException. Note that the Settings.dataPath, if set, is used by this method as the path to the catalog.

Parameters:

name - The catalog name on the form name.crtr.type

mode - Can be Catalog.READ_ONLY, Catalog.WRITE_ONLY, Catalog.READ_WRITE, Catalog.CREATE (this one is non destructive: if the catalog not exists, it will be created and it will remain open on WRITE_ONLY mode; if it exists, it will stay open on WRITE_ONLY mode). You can also or the mode with Catalog.DB_ATTR_BACKUP or Catalog.DB_ATTR_STREAM to set these attributes when creating a database (do NOT use the other attributes!)

recordSize - Used only when writing records. If you plan to write records with fixed size, pass in the desired size. Otherwise, pass RemoteCatalog.RECORD_SIZE_AUTO to automatically expand or shrink the record.

RemoteCatalog

public RemoteCatalog(java.lang.String name)

Opens a remote catalog in READ_ONLY mode.

See Also:

RemoteCatalog(String, int, int)

RemoteCatalog

public RemoteCatalog(java.lang.String name,
                     int mode)

Opens a remote catalog in the given mode.

See Also:

RemoteCatalog(String, int, int)

Method Detail

isOpen

public boolean isOpen()

Returns if this remote catalog is open or closed.

delete

public void delete()

Completely deletes this database, closing it first.

getRecordCount

public int getRecordCount()

Returns the number of records inside this database

readRecord

public boolean readRecord(int index,
                          RemoteCatalogRecord rec)

Fetches the given index, passing to the rec a DataStream to read the record information.

writeRecord

public boolean writeRecord(int index,
                           RemoteCatalogRecord rec)

Write the record at the given index. IMPORTANT: if index is -1, the record is appended, otherwise, the given record is OVERWRITTEN. It is not possible to insert a record into a given position due to limitations of the native API. Also, passing a record index greater than the number of records may cause unexpected results.

getRecordPos

public int getRecordPos()

Returns the current record position or -1 if there is no current record.

deleteRecord

public boolean deleteRecord(int index)

Deletes the given record index. The record is immediately removed from the catalog and all subsequent records are moved up one position. IMPORTANT: due to this behaviour, if you plan to delete all records from a database, it is much faster if you delete them in REVERSE ORDER (from last to first). If you plan to delete all records, delete the whole database using delete and then create it again.

skipBytes

public int skipBytes(int count)

Offsets the cursor in the current record a number of bytes. The cursor defines where read and write operations start from in the record. It can be negative but cannot underflow neither overflow the record size.

Parameters:

count - the number of bytes to skip.

Returns:

The given number of bytes if success, -1 if failed.

getNextModifiedRecordIndex

public int getNextModifiedRecordIndex()

Returns the next modified record index. Can be used with the readRecord to only retrieve the changed records since the last synchronization.

close

public boolean close()

Closes this catalog.

listCatalogs

public static java.lang.String[] listCatalogs(int crtr,
                                              int type)

Lists the available catalogs on the device that has the given creator id and type. If you don't pass a creator id and/or a type, this method will return with NO RESULTS. Note that the Settings.dataPath, if set, is used by this method as the path to the catalogs.

Returns:

A String array with the answer, or null if no db was found that matched the criteria.