javax.microedition.io
Interface DatabaseConnection


public interface DatabaseConnection
extends InputConnection, OutputConnection

This interface defines the capabilities a small (PDA) type database must have.

The suggested URL format to open the database is:

 database://
 
The connection is modal in that there is a concept of being a currently selected record. When a record is selected the normal input and output streams can be used to read and write data to it. In this interface the record numbers are always expressed as integers. When a record is created the protocol will assign it a number. This number remains with the database for as long as the record exists. Deleted records will cause the record number to be reused.

Protocol designers should extend the open database URL to include:

  database://:
 
so that database records can be used to with regular input and output streams like this.
  InputStream = Connector.openInputStream("database://foo.dat:123");
 
The current record pointer can be changed at anytime and any written data will automatically be flushed. After this the input and output stream will address the new record. Input will start with the first byte, and output with append will cause output to start after the last character in the selected record. Output without append will cause the record to be deleted as soon as the first byte has been written, and which will then become the first byte of the record.

When a record is selected it is locked in such a way that no connection stream in any program can access it. For this reason an access exception may occur when one of the select methods is called.

Database modification events can be monitored by opening an event stream. All events are read as a pair of ints from the event stream. The first is an event code in the following format:

 1 = Record added
 2 = Record changed
 3 = Record deleted
 
An asynchronous "event listener" can be created thus:
 DatabaseConnector db = (DatabaseConnector)Connector.open("database://foo.dat");
 new Thread() {
     public void run() {
         DataInput dis = db.getEventStream();
         while(true) {
             int code = dis.readInt();
             int rec  = dis.readint();
             switch(code) {
                 case 1: recordAdded(db, rec);   break;
                 case 2: recordChanged(db, rec); break;
                 case 3: recordDeleted(db, rec); break;
             }
         }
     }
 }.start();
 
The event stream can only be closed by closing the connection.

Selecting a specific record is done using the selectRecord() function. This takes a parameter which is the record number. The value 0 is used to seek to the first record in the database.

A database may be deleted by using a special close function called closeAndDelete()


Method Summary
 int createRecord()
          Create record.
 void deleteAndClose()
          Delete the database
 boolean deleteRecord(int i)
          Delete a record.
 int getDatabaseVersion()
          Return database version number
 long getLength()
          Return the size in bytes of the database
 long getLengthAvailable()
          Return the size in bytes that the database can grow to
 long getModificationDate()
          Return the date of the last modification
 int getNextRecordID()
          Returns the recordID of the next record to be added to the database.
 int getNumRecords()
          Return the number of records in the database
 int getRecordID()
          Returns the recordID of the currently selected record.
 long getRecordModificationDate()
          Return the date the current record was modification
 int getRecordSize()
          Returns the size of the currently selected record.
 DataInput openEventStream()
          Get a database event handler
 int selectNextRecord()
          Select the next record int the database
 boolean selectRecord(int i)
          Select a record.
 
Methods inherited from interface javax.microedition.io.InputConnection
openDataInputStream, openInputStream
 
Methods inherited from interface javax.microedition.io.OutputConnection
openDataOutputStream, openOutputStream
 

Method Detail

getLength

public long getLength()
Return the size in bytes of the database
Returns:
size or -1 for failure

getLengthAvailable

public long getLengthAvailable()
Return the size in bytes that the database can grow to
Returns:
size or -1 for failure

getNumRecords

public int getNumRecords()
Return the number of records in the database
Returns:
size or -1 for failure

getModificationDate

public long getModificationDate()
Return the date of the last modification
Returns:
date or -1 for failure

getDatabaseVersion

public int getDatabaseVersion()
Return database version number

Each time a database is modified (record added, modified, deleted), it's version is incremented.

Returns:
size or -1 for failure

deleteAndClose

public void deleteAndClose()
                    throws IOException
Delete the database
Returns:
success/failure

createRecord

public int createRecord()
                 throws IOException
Create record.
Returns:
the record number or -1 for failure

deleteRecord

public boolean deleteRecord(int i)
                     throws IOException
Delete a record.
Returns:
success/failure

selectRecord

public boolean selectRecord(int i)
                     throws IOException
Select a record.
Returns:
success/failure

selectNextRecord

public int selectNextRecord()
                     throws IOException
Select the next record int the database
Returns:
the record number or -1 for EOF

getRecordID

public int getRecordID()
Returns the recordID of the currently selected record.
Returns:
size or -1 for failure

getNextRecordID

public int getNextRecordID()
Returns the recordID of the next record to be added to the database.
Returns:
size or -1 for failure

getRecordSize

public int getRecordSize()
Returns the size of the currently selected record.
Returns:
size or -1 for failure

getRecordModificationDate

public long getRecordModificationDate()
Return the date the current record was modification
Returns:
date or -1 for failure

openEventStream

public DataInput openEventStream()
Get a database event handler
Returns:
DataOutput stream