waba.io
Class Catalog

java.lang.Object
  |
  +--waba.io.Stream
        |
        +--waba.io.Catalog

public class Catalog
extends Stream

Catalog is a collection of records commonly referred to as a database on small devices.

Here is an example showing data being read from records in a catalog:

 Catalog c = new Catalog("MyCatalog", Catalog.READ_ONLY);
 if (!c.isOpen())
   return;
 int count = c.getRecordCount();
 byte b[] = new byte[10];
 for (int i = 0; i < count; i++)
   {   
   c.setRecord(i);
   c.readBytes(b, 0, 10);
   ...
   }
 c.close();
 


Field Summary
static int CREATE
          Create open mode.
static int READ_ONLY
          Read-only open mode.
static int READ_WRITE
          Read-write open mode.
static int WRITE_ONLY
          Write-only open mode.
 
Constructor Summary
Catalog(java.lang.String name, int mode)
          Opens a catalog with the given name and mode.
 
Method Summary
 int addRecord(int size)
          Adds a record to the end of the catalog.
 boolean close()
          Closes the catalog.
 boolean delete()
          Deletes the catalog.
 boolean deleteRecord()
          Deletes the current record and sets the current record position to -1.
 int getRecordCount()
          Returns the number of records in the catalog or -1 if the catalog is not open.
 int getRecordSize()
          Returns the size of the current record in bytes or -1 if there is no current record.
 boolean isOpen()
          Returns true if the catalog is open and false otherwise.
static java.lang.String[] listCatalogs()
          Returns the complete list of existing catalogs.
 int readBytes(byte[] buf, int start, int count)
          Reads bytes from the current record into a byte array.
 boolean resizeRecord(int size)
          Resizes a record.
 boolean setRecordPos(int pos)
          Sets the current record position and locks the given record.
 int skipBytes(int count)
          Advances the cursor in the current record a number of bytes.
 int writeBytes(byte[] buf, int start, int count)
          Writes to the current record.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

READ_ONLY

public static final int READ_ONLY
Read-only open mode.

WRITE_ONLY

public static final int WRITE_ONLY
Write-only open mode.

READ_WRITE

public static final int READ_WRITE
Read-write open mode.

CREATE

public static final int CREATE
Create open mode. Used to create a database if one does not exist.
Constructor Detail

Catalog

public Catalog(java.lang.String name,
               int mode)
Opens a catalog with the given name and mode. If mode is CREATE, the catalog will be created if it does not exist.

For PalmOS: A PalmOS creator id and type can be specified by appending a 4 character creator id and 4 character type to the name seperated by periods. For example:

 Catalog c = new Catalog("MyCatalog.CRTR.TYPE", Catalog.CREATE);
 
Will create a PalmOS database with the name "MyCatalog", creator id of "CRTR" and type of "TYPE".

If no creator id and type is specified, the creator id will default to the creator id of current waba program and the type will default to "DATA".

Under PalmOS, the name of the catalog must be 31 characters or less, not including the creator id and type. Windows CE supports a 32 character catalog name but to maintain compatibility with PalmOS, you should use 31 characters maximum for the name of the catalog.

Parameters:
name - catalog name
mode - one of READ_ONLY, WRITE_ONLY, READ_WRITE or CREATE
Method Detail

addRecord

public int addRecord(int size)
Adds a record to the end of the catalog. If this operation is successful, the position of the new record is returned and the current position is set to the new record. If it is unsuccessful the current position is unset and -1 is returned.
Parameters:
size - the size in bytes of the record to add

resizeRecord

public boolean resizeRecord(int size)
Resizes a record. This method changes the size (in bytes) of the current record. The contents of the existing record are preserved if the new size is larger than the existing size. If the new size is less than the existing size, the contents of the record are also preserved but truncated to the new size. Returns true if the operation is successful and false otherwise.
Parameters:
size - the new size of the record

close

public boolean close()
Closes the catalog. Returns true if the operation is successful and false otherwise.
Overrides:
close in class Stream

delete

public boolean delete()
Deletes the catalog. Returns true if the operation is successful and false otherwise.

listCatalogs

public static java.lang.String[] listCatalogs()
Returns the complete list of existing catalogs. If no catalogs exist, this method returns null.

deleteRecord

public boolean deleteRecord()
Deletes the current record and sets the current record position to -1. The record is immediately removed from the catalog and all subsequent records are moved up one position.

getRecordCount

public int getRecordCount()
Returns the number of records in the catalog or -1 if the catalog is not open.

getRecordSize

public int getRecordSize()
Returns the size of the current record in bytes or -1 if there is no current record.

isOpen

public boolean isOpen()
Returns true if the catalog is open and false otherwise. This can be used to check if opening or creating a catalog was successful.

setRecordPos

public boolean setRecordPos(int pos)
Sets the current record position and locks the given record. The value -1 can be passed to unset and unlock the current record. If the operation is succesful, true is returned and the read/write cursor is set to the beginning of the record. Otherwise, false is returned.

readBytes

public int readBytes(byte[] buf,
                     int start,
                     int count)
Reads bytes from the current record into a byte array. Returns the number of bytes actually read or -1 if an error prevented the read operation from occurring. After the read is complete, the location of the cursor in the current record (where read and write operations start from) is advanced the number of bytes read.
Overrides:
readBytes in class Stream
Parameters:
buf - the byte array to read data into
start - the start position in the array
count - the number of bytes to read

skipBytes

public int skipBytes(int count)
Advances the cursor in the current record a number of bytes. The cursor defines where read and write operations start from in the record. Returns the number of bytes actually skipped or -1 if an error occurs.
Parameters:
count - the number of bytes to skip

writeBytes

public int writeBytes(byte[] buf,
                      int start,
                      int count)
Writes to the current record. Returns the number of bytes written or -1 if an error prevented the write operation from occurring. After the write is complete, the location of the cursor in the current record (where read and write operations start from) is advanced the number of bytes written.
Overrides:
writeBytes in class Stream
Parameters:
buf - the byte array to write data from
start - the start position in the byte array
count - the number of bytes to write