Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 openned twice. You must close one instance before openning the other or share the same instance.

Field Summary
`protected Object` | `bag` Only used in the Desktop classes
`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()` 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` | `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)` 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

### bag

    protected Object bag

  Only used in the Desktop classes

### 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 waba 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
    `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 readen 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. added by guich@SuperWaba_1.1

### getRecordAttributes

    public byte getRecordAttributes()

  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)

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

### 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD