waba.io
Class Catalog

java.lang.Object
  |
  +--waba.io.Stream
        |
        +--waba.io.Catalog
Direct Known Subclasses:
HighScores, ObjectCatalog

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;
 DataStream ds = new DataStream(c);
 int count = c.getRecordCount();
 for (int i = 0; i < count; i++)
    if (c.setRecordPos(i))
    {
       String name = ds.readString();
       int age = ds.readShort();
       double salary = ds.readDouble();
       ...
    }
 c.close();
 

Note: a Catalog cannot be opened twice. You must close one instance before opening the other or share the same instance.

In Windows CE, you can specify the path of the pdb file, either absolute ("\\My Documents\\Test") or relative ("..\\..\\Test").


Field Summary
static int CREATE
          Create open mode.
static int DB_ATTR_APPINFODIRTY
          Set if Application Info block is dirty.
static int DB_ATTR_BACKUP
          Set if database should be backed up to PC if no app-specific synchronization conduit has been supplied.
static int DB_ATTR_COPY_PREVENTION
          This database should not be copied to
static int DB_ATTR_OK_TO_INSTALL_NEWER
          This tells the backup conduit that it's OK for it to install a newer version of this database with a different name if the current database is open.
static int DB_ATTR_READ_ONLY
          Read Only database
static int DB_ATTR_RESET_AFTER_INSTALL
          Device requires a reset after this database is installed.
static int DB_ATTR_STREAM
          This database is used for file stream implementation.
static int READ_ONLY
          Read-only open mode.
static int READ_WRITE
          Read-write open mode.
static byte REC_ATTR_DELETE
          Record atribute: Deleted.
static byte REC_ATTR_DIRTY
          Record atribute: Dirty (has been modified since last sync)
static byte REC_ATTR_SECRET
          Record atribute: Private
static int WRITE_ONLY
          Write-only open mode.
 
Constructor Summary
Catalog()
          this constructor was created to let users use the toPdb and fromPdb methods if running in the desktop.
Catalog(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.
 int addRecord(int size, int pos)
          Adds a record to the position 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 getAttributes()
          Retrieves this catalog's attributes.
 byte getRecordAttributes()
          Deprecated. use getRecordAttributes(recordPos) instead.
 byte getRecordAttributes(int recordPos)
          Retrieves the attributes of the current record.
 int getRecordCount()
          Returns the number of records in the catalog or -1 if the catalog is not open.
 int getRecordOffset()
          Returns the internal record offset.
 int getRecordPos()
          Returns the current record position or -1 if there is no current record.
 int getRecordSize()
          Returns the size of the current record in bytes or -1 if there is no current record.
 int inspectRecord(byte[] buf, int recPosition)
          Inspects a record. use this method with careful, none of the params are checked for validity. the cursor is not advanced, neither the current record position. this method must be used only for a fast way of viewing the contents of a record, like searching for a specific header or filling a grid of data.
 boolean isOpen()
          Returns true if the catalog is open and false otherwise.
static String[] listCatalogs()
          Returns the complete list of existing catalogs.
static String[] listCatalogs(int creatorId, int type)
          Returns the list of existing catalogs with the given creator id and/or type.
 int readBytes(byte[] buf, int start, int count)
          Reads bytes from the current record into a byte array.
 boolean rename(String newName)
          Renames the currently open catalog to the given name.
 boolean resizeRecord(int size)
          Resizes a record.
 void setAttributes(int i)
          Sets this catalog's attributes, defined by the DB_ATTR_xxx constants.
 void setRecordAttributes(byte attr)
          Deprecated. use setRecordAttributes(recordPos, attr) instead.
 void setRecordAttributes(int recordPos, byte attr)
          Sets the attributes of the current record.
 boolean setRecordPos(int pos)
          Sets the current record position and locks the given record.
 int skipBytes(int count)
          Offsets 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
equals, getClass, hashCode, notify, toString, wait, wait
 

Field Detail

READ_ONLY

public static final int READ_ONLY
Read-only open mode. This flag has no effect in PalmOS (same as READ_WRITE), only in Windows CE.

WRITE_ONLY

public static final int WRITE_ONLY
Write-only open mode. This flag has no effect in PalmOS (same as READ_WRITE), only in Windows CE.

READ_WRITE

public static final int READ_WRITE
Read-write open mode.

CREATE

public static final int CREATE
Create open mode. If the database don't exists, it is created and stays in READ_WRITE mode. Otherwise, if it does exists, it is not erased; it just stays in READ_WRITE mode.

DB_ATTR_READ_ONLY

public static final int DB_ATTR_READ_ONLY
Read Only database

DB_ATTR_APPINFODIRTY

public static final int DB_ATTR_APPINFODIRTY
Set if Application Info block is dirty. Optionally supported by an App's conduit

DB_ATTR_BACKUP

public static final int DB_ATTR_BACKUP
Set if database should be backed up to PC if no app-specific synchronization conduit has been supplied.

DB_ATTR_OK_TO_INSTALL_NEWER

public static final int DB_ATTR_OK_TO_INSTALL_NEWER
This tells the backup conduit that it's OK for it to install a newer version of this database with a different name if the current database is open. This mechanism is used to update the Graffiti Shortcuts database, for example.

DB_ATTR_RESET_AFTER_INSTALL

public static final int DB_ATTR_RESET_AFTER_INSTALL
Device requires a reset after this database is installed.

DB_ATTR_COPY_PREVENTION

public static final int DB_ATTR_COPY_PREVENTION
This database should not be copied to

DB_ATTR_STREAM

public static final int DB_ATTR_STREAM
This database is used for file stream implementation. This attribute may not be used.

REC_ATTR_DELETE

public static final byte REC_ATTR_DELETE
Record atribute: Deleted. Note that after a record has it delete attribute set you don't have access to it anymore.

REC_ATTR_DIRTY

public static final byte REC_ATTR_DIRTY
Record atribute: Dirty (has been modified since last sync)

REC_ATTR_SECRET

public static final byte REC_ATTR_SECRET
Record atribute: Private
Constructor Detail

Catalog

public Catalog(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 SuperWaba program and the type will default to "DATA". Note that in desktop the complete form is required.

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. Every time the database is modified the backup attribute is set.

Parameters:
name - catalog name. Don't use accentuated characters in the catalog name.
mode - one of READ_ONLY, WRITE_ONLY, READ_WRITE or CREATE

Catalog

public Catalog()
this constructor was created to let users use the toPdb and fromPdb methods if running in the desktop. NEVER use it to deal with normal Catalogs! If you do so, your program (or the vm) will crash.
Method Detail

rename

public boolean rename(String newName)
Renames the currently open catalog to the given name. In PalmOS, the name must be in the form "MyNewCatalogName.CRTR.TYPE". Note: in desktop only, the old file may remain if its deletion is not possible (in other words, in desktop the rename operation may work like a "copy oldName newName").

Here is an example of use:

 Catalog c = new Catalog("guich.Crtr.Type",Catalog.READ_ONLY);
 if (c.isOpen())
    c.rename("flor.CrTr.TyPe");
 c.close();

 

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

addRecord

public int addRecord(int size,
                     int pos)
Adds a record to the position 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. implemented by guich (guich@email.com) in 06/30/2000.
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. If you don't close the Catalog, it will be closed when it gets garbage collected. Note that in desktop the catalog is only written to disk after it is closed.
Overrides:
close in class Stream

delete

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

After this, the catalog is closed (of course).

Note that this behavior is different between running on desktop and running on palm os, because in applets we cannot erase files at the server, in this case only records are all deleted, but file still exists, with palm-info-header. PS: since 3.0, the catalog may be deleted in applet too.


listCatalogs

public static String[] listCatalogs()
Returns the complete list of existing catalogs. If no catalogs exist, this method returns null. In the desktop, it searches in the already opened files and also the pdb files in the current "." directory. Be careful! The catalog may return null strings in the array.

listCatalogs

public static String[] listCatalogs(int creatorId,
                                    int type)
Returns the list of existing catalogs with the given creator id and/or type. If no catalogs exist, this method returns null. In the desktop, it searches in the already opened files and also the pdb files in the current "." directory. The creator id and type works like a wildcard. You may pass 0 to ignore them. You can use the function Convert.chars2int(String fourChars) to convert a String like "Wrp2" to an integer to pass in this method. Be careful! The catalog may return null strings in the array.
Since:
SuperWaba 3.3

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.
Overrides:
isOpen in class Stream

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)
Offsets 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

inspectRecord

public int inspectRecord(byte[] buf,
                         int recPosition)
Inspects a record. use this method with careful, none of the params are checked for validity. the cursor is not advanced, neither the current record position. this method must be used only for a fast way of viewing the contents of a record, like searching for a specific header or filling a grid of data. buf.length bytes (at maximum) are read from the record into buf. Returns the number of bytes read (can be different of buf.length if buf.length is greater than the record size) or -1 if an error prevented the read operation from occurring.
Since:
SuperWaba 1.1

getRecordAttributes

public byte getRecordAttributes()
Deprecated. use getRecordAttributes(recordPos) instead.

Retrieves the attributes of the current record. Use the REC_ATTR_xxx masks to set/retrieve its states.
Returns:
0 if db dont exists

setRecordAttributes

public void setRecordAttributes(byte attr)
Deprecated. use setRecordAttributes(recordPos, attr) instead.

Sets the attributes of the current record. Use the REC_ATTR_xxx masks to set/retrieve its states.

getRecordAttributes

public byte getRecordAttributes(int recordPos)
Retrieves the attributes of the current record. Use the REC_ATTR_xxx masks to set/retrieve its states. Note that the current record, if modified, will have its attributes changed after you call this method.
Returns:
0 if db dont exists

setRecordAttributes

public void setRecordAttributes(int recordPos,
                                byte attr)
Sets the attributes of the current record. Use the REC_ATTR_xxx masks to set/retrieve its states. Don't try to change the current record's attribute, because it may change again (by the VM) after the record is released.

getAttributes

public int getAttributes()
Retrieves this catalog's attributes. Use the DB_ATTR_xxx masks to retrieve its states.

setAttributes

public void setAttributes(int i)
Sets this catalog's attributes, defined by the DB_ATTR_xxx constants. The original attributes must be getted prior applying this value. If not, you can loose your database and your app will crash.

getRecordPos

public int getRecordPos()
Returns the current record position or -1 if there is no current record.

getRecordOffset

public int getRecordOffset()
Returns the internal record offset. You may use this value in conjunction with the skipBytes method. Note that setRecordPos resets the offset to 0.
Since:
SuperWaba 4.0