com.revusky.niggle.data
Interface DataSource

All Superinterfaces:
java.rmi.Remote
All Known Subinterfaces:
MutableDataSource, TransactionalDataSource
All Known Implementing Classes:
AbstractDataSource

public interface DataSource
extends java.rmi.Remote

a marker interface representing objects that contain a set of Records indexed by a lookup key

Author:
Jonathan Revusky

Method Summary
 void close()
          A method that should be called to free any resources associated with the data source.
 Record get(java.lang.Object key)
          method that exists for backward compatibility This is equivalent to get(null, key);
 Record get(java.lang.String type, java.lang.Object key)
           
 java.lang.String getName()
           
 java.util.List getRecords(java.lang.Object key)
           
 void init(java.util.Properties props)
          A method that initializes a DataSource with a set of initialization properties.
 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)
           
 

Method Detail

getName

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

get

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

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. If the data source allows multiple records, only returns the first one found. Use getRecords() in that situation. returns null if none is found.

getRecords

public java.util.List getRecords(java.lang.Object key)
                          throws java.io.IOException
Returns:
a List of records based on a lookup key. The result can be an empty list, but never null.

keys

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

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.

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

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