ewe.io
Class Catalog

java.lang.Object
  ewe.util.Errorable
      ewe.io.BasicStreamObject
          ewe.io.StreamObject
              ewe.io.Catalog

All Implemented Interfaces:

BasicStream, OverridesClose, Stream, Streamable

public class Catalog

extends StreamObject

implements OverridesClose

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.

Fields inherited from class ewe.io.StreamObject

napIterations, napTime, READWRITE_CLOSED, READWRITE_ERROR, READWRITE_WOULDBLOCK

Fields inherited from class ewe.io.BasicStreamObject

closed

Fields inherited from class ewe.util.Errorable

error

Constructor Summary

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.
boolean	close() Closes the catalog.
boolean	delete() Deletes the catalog.
boolean	deleteRecord() Deletes the current record and sets the current record position to -1.
boolean	flushStream() This is non-blocking.
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 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 ewe.io.StreamObject

closeStream, doRead, doWrite, flush, nap, nap, nonBlockingRead, nonBlockingWrite, read, readAByte, readBytes, write, writeAByte, writeBytes

Methods inherited from class ewe.io.BasicStreamObject

getException, getName, read, read, throwIOException, toInputStream, toOutputStream, toStream, write, write

Methods inherited from class ewe.util.Errorable

returnError, returnError, returnError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

READ_ONLY

public static final int READ_ONLY

Read-only open mode.

See Also:

Constant Field Values

WRITE_ONLY

public static final int WRITE_ONLY

Write-only open mode.

See Also:

Constant Field Values

READ_WRITE

public static final int READ_WRITE

Read-write open mode.

See Also:

Constant Field Values

CREATE

public static final int CREATE

Create open mode. Used to create a database if one does not exist.

See Also:

Constant Field Values

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

Specified by:

close in interface BasicStream

Overrides:

close in class StreamObject

delete

public boolean delete()

Deletes the catalog. Returns true if the operation is successful and false otherwise.

listCatalogs

public static 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.

Specified by:

isOpen in interface BasicStream

Overrides:

isOpen in class StreamObject

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.

Specified by:

readBytes in interface Stream

Overrides:

readBytes in class StreamObject

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.

Specified by:

writeBytes in interface Stream

Overrides:

writeBytes in class StreamObject

Parameters:

buf - the byte array to write data from

start - the start position in the byte array

count - the number of bytes to write

flushStream

public boolean flushStream()
                    throws IOException

Description copied from interface: BasicStream

This is non-blocking. It returns true if the flush completed, false if it did not, or throws an exception on error.

Specified by:

flushStream in interface BasicStream

Throws:

IOException