org.oreodata
Interface OreoDataSource

All Superinterfaces:
DataListener, java.util.EventListener, java.rmi.Remote
All Known Subinterfaces:
TransactionalDataSource
All Known Implementing Classes:
AbstractDataSource, JDBCTransactionalDataSource

public interface OreoDataSource
extends DataListener, java.rmi.Remote

Interface implemented by objects that manage a collection of records.

Author:
Jonathan Revusky

Method Summary
 void addDataListener(DataListener dl)
          Add a listener that gets notified if ever a record is inserted, updated or deleted.
 void close()
          A method that should be called to free any resources associated with the data source.
 Record delete(Record rec)
          Delete a record.
 Record delete(java.lang.String type, java.lang.Object key)
          Delete a record.
 Record get(java.lang.Object key)
           
 Record get(java.lang.String type, java.lang.Object key)
           
 java.lang.String getName()
           
 void init(java.util.Properties props)
          A method that initializes a DataSource with a set of initialization properties.
 Record insert(Record rec)
          Adds a new record to the managed pool.
 java.util.List keys()
          This is equivalent to calling keys(null) where no record type is specified.
 java.util.List keys(java.lang.String type)
           
 java.util.List lookup(java.lang.Object lookupKey)
          Some datasources may support a multiple lookup by key functionality.
 void reload(org.xml.sax.InputSource input)
          loads data from an InputSource, meant to be used in a startup phase.
 void reload(Record rec)
          loads a Record without any notification to listeners or any synchronization.
 void removeDataListener(DataListener dl)
          Remove a listener that gets notified if ever a record is inserted, updated or deleted.
 java.util.List select(RecordFilter filter)
          This is equivalent to calling select(filter, null)
 java.util.List select(RecordFilter filter, RecordComparator comparator)
          Fetches a list of records matching filter.
 Record update(Record oldRec, Record newRec)
          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.
 void writeElement(java.io.Writer writer, java.lang.String type, java.lang.Object key, boolean recurse)
          This is used to write out an XML tree.
 void writeSnapshot(java.io.OutputStream out)
          This method outputs the entire contents of the data source as an XML tree.
 
Methods inherited from interface org.oreodata.DataListener
handleEvent
 

Method Detail

keys

public java.util.List keys()
                    throws java.io.IOException
This is equivalent to calling keys(null) where no record type is specified.

java.io.IOException

keys

public java.util.List keys(java.lang.String type)
                    throws java.io.IOException
Parameters:
type - the record type we are interested, under some circumstances, this may be null.
Returns:
a list of all valid lookup keys that correspond to a given record type.
java.io.IOException

init

public void init(java.util.Properties props)
          throws java.io.IOException
A method that initializes a DataSource with a set of initialization properties. This is called internally within Oreo and should not be called by application code. As an implementor, you should make sure that this method is only called once, for example, throw a RuntimeException if an attempt is made to call this on a DataSource a second time.

Specified by:
init in interface DataListener
java.io.IOException

close

public void close()
           throws java.io.IOException
A method that should be called to free any resources associated with the data source. Note that no other methods should be called on this object after this one. (In many implementations, this method will likely do nothing.)

java.io.IOException

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. Otherwise, it does nothing.

java.io.IOException

getName

public java.lang.String getName()
                         throws java.io.IOException
Returns:
a unique string by which this data source will be known.
java.io.IOException

get

public Record get(java.lang.Object key)
           throws java.io.IOException
Parameters:
key - the lookup key method that exists for backward compatibility This is equivalent to get(null, key);
java.io.IOException

get

public Record get(java.lang.String type,
                  java.lang.Object key)
           throws java.io.IOException
Parameters:
type - the type of the record, if this is null, then any type will do.
key - the lookup key
Returns:
a Record of the given type, with the given lookup key.
java.io.IOException

insert

public Record insert(Record rec)
              throws java.io.IOException
Adds a new record to the managed pool.

Parameters:
rec - the record to add
Returns:
the added record (frozen).
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 Record update(Record oldRec,
                     Record newRec)
              throws java.io.IOException
Replaces an existing version of a record with a new updated version. Some implementations may use the oldRec parameter to guarantee that there are no concurrency issues. In such case, it would throw a ConcurrentModificationException

Parameters:
oldRec - the record to replace.
newRec - the new record.
Returns:
the updated record (frozen).
Throws:
java.io.IOException - thrown in case of any other database or communication error.

delete

public Record delete(Record rec)
              throws java.io.IOException
Delete a record.

Parameters:
rec - the record to delete.
Returns:
the deleted Record of the given type, with the given lookup key.
java.io.IOException

delete

public Record delete(java.lang.String type,
                     java.lang.Object key)
              throws java.io.IOException
Delete a record.

Parameters:
type - the type of the record, if this is null, then any type will do.
key - the primary key of the record to delete.
Returns:
the deleted Record of the given type, with the given lookup key.
java.io.IOException

select

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

java.io.IOException

select

public java.util.List select(RecordFilter filter,
                             RecordComparator comparator)
                      throws java.io.IOException
Fetches a list of records matching filter. If filter is null, returns all the records in the container. If the comparator is null, no sorting is carried out on the resulting list.

Parameters:
filter - the record filter, or null.
comparator - defines an ordering for the records.
Returns:
a List of all the records that are an instance of a given class. If no records match the filter, an empty List.
java.io.IOException

reload

public void reload(Record rec)
            throws java.io.IOException
loads a Record without any notification to listeners or any synchronization. Should only be used when restarting an app and restoring the data.

java.io.IOException

addDataListener

public void addDataListener(DataListener dl)
                     throws java.io.IOException
Add a listener that gets notified if ever a record is inserted, updated or deleted.

Parameters:
dl - the listener
java.io.IOException

removeDataListener

public void removeDataListener(DataListener dl)
                        throws java.io.IOException
Remove a listener that gets notified if ever a record is inserted, updated or deleted.

Parameters:
dl - the listener
java.io.IOException

writeSnapshot

public void writeSnapshot(java.io.OutputStream out)
                   throws java.io.IOException
This method outputs the entire contents of the data source as an XML tree.

java.io.IOException

writeElement

public void writeElement(java.io.Writer writer,
                         java.lang.String type,
                         java.lang.Object key,
                         boolean recurse)
                  throws java.io.IOException
This is used to write out an XML tree.

Parameters:
writer - the character stream to write to.
type - the record type.
key - the primary key of the record.
recurse - whether to write out the child elements recursively (if this applies)
java.io.IOException

reload

public void reload(org.xml.sax.InputSource input)
            throws org.xml.sax.SAXException,
                   java.io.IOException
loads data from an InputSource, meant to be used in a startup phase.

org.xml.sax.SAXException
java.io.IOException

lookup

public java.util.List lookup(java.lang.Object lookupKey)
                      throws java.io.IOException
Some datasources may support a multiple lookup by key functionality.

Returns:
a List of Record objects
java.io.IOException