com.ibm.mobileservices.isync.midp
Class Index

java.lang.Object
  |
  +--com.ibm.mobileservices.isync.midp.Index

public class Index
extends java.lang.Object

Provides the developer with the ability to search, update and delete based on the primary key of a row. In order to keep the primary key index up to date the developer must perform all "modification" operations via an instance of the Index class.

Primary Key operations provided by the Index class are findByPrimaryKey, deleteByPrimaryKey and updateByPrimaryKey. Methods provided to ensure that the primary key is kept up to date and which must be used in place of the modification methods of RecordStore (addRecord, deleteRecord and setRecord) are insertRecord, deleteRecord and updateRecord. Finally, findRecord(int), findRecord(int, byte[]) and findRecordSize(int) are also provided as convenience functions that wrap the functionality of getRecord(int), getRecord(int, byte[]) and getRecordSize(int) respectively.

Example usage

        public class MyClass extends MIDlet 
         implements CommandListener, ISyncListener, Runnable
    { 
        

    }
        

See Also:
FastRecordEnumeration, IndexException

Constructor Summary
Index(com.ibm.mobileservices.isync.midp.FastRecordStore store, com.ibm.mobileservices.isync.midp.TableMetaData table)
           
 
Method Summary
 void close()
           Writes changes in the Primary Key index to non-volatile storage and closes the underlying RecordStore.
static void delete(java.lang.String storeName)
           Deletes an index for the named store.
 void deleteByPrimaryKey(byte[] keyData, int keyLength)
           Deletes a record in the Store that matches a particular primary key value.
 void deleteRecord(int recordId)
           Deletes a record from the underlying FastRecordStore and modifies the primary key index.
 int findByPrimaryKey(byte[] key, int keyLength)
           Returns the record matching the passed in key value.
 byte[] findRecord(int recordId)
          Helper method that wraps FastRecordStore.getRecord(int).
 int findRecord(int recordId, byte[] data)
          Helper method that wraps FastRecordStore.getRecord(int, byte[], int).
 int findRecordSize(int recordId)
          Helper method that wraps FastRecordStore.getRecordSize(int).
 int insertRecord(byte[] data, int numBytes)
           Adds a record to the underlying FastRecordStore and modifies the primary key index.
 void openIndex(com.ibm.mobileservices.isync.midp.FastRecordStore store, com.ibm.mobileservices.isync.midp.TableMetaData tab)
          Allows the the reuse of an index object.
 void updateByPrimaryKey(byte[] data, int numBytes)
           Updates a record that matches the primary key portion of the new row data.
 void updateRecord(int recordId, byte[] data, int numBytes)
           Updates a record to the underlying FastRecordStore and modifies the primary key index.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Index

public Index(com.ibm.mobileservices.isync.midp.FastRecordStore store,
             com.ibm.mobileservices.isync.midp.TableMetaData table)
      throws IndexException
Parameters:
store - The FastRecordStore instance that the Index is being created against. All modifications to the data in store can only be performed via the Index instance.
table - The schema of the FastRecordStore instance.
Throws:
IndexException - If there is a problem reading the index.
See Also:
FastRecordStore, TableMetaData
Method Detail

openIndex

public final void openIndex(com.ibm.mobileservices.isync.midp.FastRecordStore store,
                            com.ibm.mobileservices.isync.midp.TableMetaData tab)
                     throws IndexException
Allows the the reuse of an index object.

Parameters:
store - The FastRecordStore instance that the Index is being created against. All modifications to the data in store can only be performed via the Index instance.
Throws:
IndexException - If there is a problem reading the index, or if the storeName is too long in store.

insertRecord

public final int insertRecord(byte[] data,
                              int numBytes)
                       throws javax.microedition.rms.RecordStoreNotOpenException,
                              javax.microedition.rms.RecordStoreException,
                              javax.microedition.rms.RecordStoreFullException,
                              IndexException

Adds a record to the underlying FastRecordStore and modifies the primary key index.

Parameters:
data - The row to insert.
numBytes - The size of row.
Returns:
The record id of the newly inserted record.
Throws:
javax.microedition.rms.RecordStoreNotOpenException - if the record store is not open.
javax.microedition.rms.RecordStoreException - if the meta data has become corrupted, or invalid, e.g. not for this store.
javax.microedition.rms.RecordStoreFullException - no more space to create a new record store.
IndexException - If the routine fails to modify the primary key.
See Also:
FastRecordStore, TableMetaData

deleteRecord

public void deleteRecord(int recordId)
                  throws javax.microedition.rms.RecordStoreNotOpenException,
                         javax.microedition.rms.InvalidRecordIDException,
                         javax.microedition.rms.RecordStoreException,
                         IndexException

Deletes a record from the underlying FastRecordStore and modifies the primary key index.

Parameters:
recordId - The row to delete.
Throws:
javax.microedition.rms.RecordStoreNotOpenException - if the record store is not open.
javax.microedition.rms.InvalidRecordIDException - if recordId does not exist.
javax.microedition.rms.RecordStoreException - if the meta data has become corrupted, or invalid, e.g. not for this store.
IndexException - If the routine fails to modify the primary key.
See Also:
FastRecordStore, TableMetaData

updateRecord

public final void updateRecord(int recordId,
                               byte[] data,
                               int numBytes)
                        throws javax.microedition.rms.RecordStoreNotOpenException,
                               javax.microedition.rms.InvalidRecordIDException,
                               javax.microedition.rms.RecordStoreException,
                               IndexException

Updates a record to the underlying FastRecordStore and modifies the primary key index.

Parameters:
recordId - The Record ID of the row in the Record Store to update.
data - The new data for the row, even if only part of the row has changed the entire row is replaced.
numBytes - The length of the data.
Throws:
javax.microedition.rms.RecordStoreNotOpenException - if the record store is not open.
javax.microedition.rms.InvalidRecordIDException - if recordId does not exist.
javax.microedition.rms.RecordStoreException - if the meta data has become corrupted, or invalid, e.g. not for this store.
IndexException - If the routine fails to modify the primary key.
See Also:
FastRecordStore, TableMetaData

findByPrimaryKey

public final int findByPrimaryKey(byte[] key,
                                  int keyLength)
                           throws IndexException,
                                  javax.microedition.rms.InvalidRecordIDException

Returns the record matching the passed in key value.

A search is made of the primary key index (key may contain multiple key values, concatenated together) for a row containing the same primary key value.

If a match is found its ID is returned, otherwise an InvalidRecordIDException is thrown.

Multiple keys in the byte array key follow the same data format as described in TableMetaData. No boolean NULL indicators are included in the key since a primary key is always NOT NULL.

Parameters:
key - The search key.
Returns:
The record id of the record.
Throws:
IndexException - If there is a problem reading from the index.
javax.microedition.rms.InvalidRecordIDException - If there is no match for the key.
See Also:
FastRecordStore, TableMetaData

deleteByPrimaryKey

public void deleteByPrimaryKey(byte[] keyData,
                               int keyLength)
                        throws IndexException,
                               javax.microedition.rms.InvalidRecordIDException,
                               javax.microedition.rms.RecordStoreException

Deletes a record in the Store that matches a particular primary key value.

Parameters:
keyData - The primary key value of the record to delete.
keyLength - Length of the keyData. If keyLength != keyData.length be sure to pass the correct value.
Throws:
IndexException - If an error while trying to access the underlying primary key.
javax.microedition.rms.InvalidRecordIDException - If there is no match for the keyData.
javax.microedition.rms.RecordStoreException - if the meta data has become corrupted, or invalid, e.g. not for this store.


updateByPrimaryKey

public void updateByPrimaryKey(byte[] data,
                               int numBytes)
                        throws IndexException,
                               javax.microedition.rms.InvalidRecordIDException,
                               javax.microedition.rms.RecordStoreException

Updates a record that matches the primary key portion of the new row data.

Parameters:
data - The new row data. Note: unlike findByPrimaryKey and deleteByPrimaryKey which just required the primary key value, updateByPrimaryKey takes the entire row to be replaced.
numBytes - Length of the new row data.
Throws:
IndexException - If an error while trying to access the underlying primary key.
javax.microedition.rms.InvalidRecordIDException - If there is no match for the key.
javax.microedition.rms.RecordStoreException - if the meta data has become corrupted, or invalid, e.g. not for this store.


close

public final void close()
                 throws IndexException

Writes changes in the Primary Key index to non-volatile storage and closes the underlying RecordStore.

Important Note: It is essential that for each instance of Index the index.close() method is called when the developer has finished operations on the Index. This ensures that changes to the Index structure are written to non volatile memory and the underlying RMS table is closed.

Throws:
IndexException - If there is a problem during saving and closing of the index.

findRecordSize

public final int findRecordSize(int recordId)
                         throws javax.microedition.rms.RecordStoreException,
                                java.io.IOException
Helper method that wraps FastRecordStore.getRecordSize(int).

Parameters:
recordId - The record id of the row to locate
Returns:
The record size for the record identified by recordId
javax.microedition.rms.RecordStoreException
java.io.IOException
See Also:
FastRecordStore.getRecordSize(int)

findRecord

public final byte[] findRecord(int recordId)
                        throws javax.microedition.rms.RecordStoreException,
                               java.io.IOException
Helper method that wraps FastRecordStore.getRecord(int).

Parameters:
recordId - The record id of the row to locate
Returns:
The record byte array for the record identified by recordId
javax.microedition.rms.RecordStoreException
java.io.IOException
See Also:
FastRecordStore.getRecord(int)

findRecord

public final int findRecord(int recordId,
                            byte[] data)
                     throws javax.microedition.rms.RecordStoreException,
                            java.io.IOException
Helper method that wraps FastRecordStore.getRecord(int, byte[], int).

Parameters:
recordId - The record id of the row to locate
data - buffer in which to put the row data.
Returns:
The record size for the record identified by recordId
javax.microedition.rms.RecordStoreException
java.io.IOException
See Also:
FastRecordStore.getRecord(int, byte[], int)

delete

public static final void delete(java.lang.String storeName)
                         throws IndexException

Deletes an index for the named store.

Parameters:
storeName - Name of the Record Store associated with the Index.
Throws:
IndexException - if record store does not exist, or there is another related problem.


(c) Copyright IBM Corp. 2001, 2002, 2003. All Rights Reserved.