com.niggle.data
Interface MutableDataSource

All Superinterfaces:
DataChangeNotifier, DataSource, java.rmi.Remote
All Known Implementing Classes:
AbstractMutableDataSource

public interface MutableDataSource
extends DataSource, DataChangeNotifier

Interface implemented by objects that manage a collection of records.

Author:
Jonathan Revusky

Method Summary
 void delete(java.lang.Object key)
          This is equivalent to delete(null, key)
 void delete(java.lang.String type, java.lang.Object key)
          Delete a record given its primary lookup key.
 void forceUpdate(Record rec, Record oldRec)
          Replace an existing version of a record with a new updated version.
 void insert(Record rec)
          Adds a new record to the managed pool.
 java.util.List select(RecordFilter filter)
          This is equivalent to select(null, filter)
 java.util.List select(java.lang.String type, RecordFilter filter)
          Fetches a list of records matching filter.
 void update(Record rec)
          Replaces an existing version of a record with a new updated version.
 void wipeCache()
          If this data source is backed by some external mechanism, like an RDBMS, wipes the in-memory cache, if one is being maintained.
 
Methods inherited from interface com.niggle.data.DataSource
close, get, get, getName, getRecords, init, keys, keys
 
Methods inherited from interface com.niggle.data.DataChangeNotifier
addDataListener, removeDataListener
 

Method Detail

insert

public void insert(Record rec)
            throws java.io.IOException
Adds a new record to the managed pool.
Parameters:
rec - the record to add
Throws:
DuplicateRecordException - if another record already exists with same primary key as 'rec'.
java.io.IOException - if the record cannot be initialized (i.e. has missing fields or invalid field values, etc.), or in case of a low-level error.

update

public void update(Record rec)
            throws java.io.IOException
Replaces an existing version of a record with a new updated version. Automatically replaces the previous version if it has not been modified since the object was taken from the data source. A ModifiedRecordException is thrown otherwise.

Not all underlying storage mediums will be able to support these semantics. Check your implementation carefully.

Parameters:
rec - the new updated record.
Throws:
ModifiedRecordException - thrown if the record was modified by another process since rec was requested from a data source.
java.io.IOException - thrown in case of any other database or communication error.

forceUpdate

public void forceUpdate(Record rec,
                        Record oldRec)
                 throws java.io.IOException
Replace an existing version of a record with a new updated version. Automatically replaces the prevous version, even if it has been modified by another process.

The client's version of the original record is passed in order to allow implementations to make the update as fine-grained as possible. Some will simply update the entire records, while others will update only modified fields.

Parameters:
rec - the new updated record.
oldRec - the client's copy of the record it removed from the data source.
Throws:
java.io.IOException - thrown in case of a database or communication error. Note that ModifiedRecordException is never thrown by this method.

delete

public void delete(java.lang.Object key)
            throws java.io.IOException
This is equivalent to delete(null, key)

delete

public void delete(java.lang.String type,
                   java.lang.Object key)
            throws java.io.IOException
Delete a record given its primary lookup key.
Parameters:
type - the record type we want to delete If this is null, we delete indistinctly with no sanity check.
key - the key to the object to delete.
Throws:
MissingRecordException - thrown if the record to be deleted could not be found.
DataException - thrown if the key maps to more than one record.
java.io.IOException - thrown in case of any other database or communication error.

select

public java.util.List select(RecordFilter filter)
                      throws java.io.IOException
This is equivalent to select(null, filter)

select

public java.util.List select(java.lang.String type,
                             RecordFilter filter)
                      throws java.io.IOException
Fetches a list of records matching filter. If filter is null, returns all the records in the container.
Parameters:
the - type of record we are interested in, possibly null
filter - the record filter, or null.
Returns:
a List of all the records that are an instance of a given class. If no records match the filter, an empty List.

wipeCache

public void wipeCache()
               throws java.io.IOException
If this data source is backed by some external mechanism, like an RDBMS, wipes the in-memory cache, if one is being maintained.