org.oreodata
Class AbstractDataSource

java.lang.Object
  |
  +--java.rmi.server.RemoteObject
        |
        +--java.rmi.server.RemoteServer
              |
              +--java.rmi.server.UnicastRemoteObject
                    |
                    +--org.oreodata.AbstractDataSource

All Implemented Interfaces:

DataListener, java.util.EventListener, OreoDataSource, java.rmi.Remote, java.io.Serializable

Direct Known Subclasses:

InMemoryDataSource, JDBCBackedRecordSet

public abstract class AbstractDataSource

extends java.rmi.server.UnicastRemoteObject

implements OreoDataSource

A convenient base class for OreoDataSource implementations. Implements some methods that are likely to be used by most.

Author:

Jonathan Revusky

See Also:

Serialized Form

Field Summary

protected java.lang.String	defaultCharEncoding The character encoding to use for XML streams
protected java.util.Date	lastLogRotation time of last log rotation
protected int	transactionCount Number of transactions since last log rotation

Fields inherited from class java.rmi.server.RemoteObject

ref

Constructor Summary

AbstractDataSource()
Our constructor must throw the exception since the superclass's constructor does.

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.
protected void	fireDataEvent(DataEvent event) Fire a data event to the listeners.
protected boolean	fireEvents()
protected void	freeze(Record rec) This is equivalent to calling freeze(rec, true);
protected void	freeze(Record rec, boolean validate) Called to mark the record as immutable.
Record	get(java.lang.Object key)
java.lang.String	getName()
void	handleEvent(DataEvent event) handle the event when the OreoDataSource we are listening to has modified data
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.
protected void	markStale(Record rec) Mark the record as "stale".
protected static java.lang.Object	normalizeKey(java.lang.String type, java.lang.String key)
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.
protected void	setFireEvents(boolean fireEvents)
protected void	setUseXML(boolean useXML)
Record	update(Record oldRec, Record newRec) Replaces an existing version of a record with a new updated version.
protected boolean	useXML()
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 class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.oreodata.OreoDataSource

get

Field Detail

defaultCharEncoding

protected java.lang.String defaultCharEncoding

The character encoding to use for XML streams

transactionCount

protected int transactionCount

Number of transactions since last log rotation

lastLogRotation

protected java.util.Date lastLogRotation

time of last log rotation

Constructor Detail

AbstractDataSource

public AbstractDataSource()
                   throws java.io.IOException

Our constructor must throw the exception since the superclass's constructor does.

Method Detail

addDataListener

public void addDataListener(DataListener dl)

Description copied from interface: OreoDataSource

Add a listener that gets notified if ever a record is inserted, updated or deleted.

Specified by:

addDataListener in interface OreoDataSource

Parameters:

dl - the listener

removeDataListener

public void removeDataListener(DataListener dl)

Description copied from interface: OreoDataSource

Remove a listener that gets notified if ever a record is inserted, updated or deleted.

Specified by:

removeDataListener in interface OreoDataSource

Parameters:

dl - the listener

fireDataEvent

protected void fireDataEvent(DataEvent event)
                      throws java.io.IOException

Fire a data event to the listeners.

java.io.IOException

freeze

protected void freeze(Record rec,
                      boolean validate)
               throws java.io.IOException

Called to mark the record as immutable. A subclass might override this routine, particularly one that uses a different implementation of the Record interface.

Parameters:

rec - the Record to freeze

validate - You can make this true if you don't want validation to take place. Be careful with this. You might use this if you are absolutely sure that there is no way that the data you are slurping in could be invalid. Thus you avoid superfluous checks.

java.io.IOException

freeze

protected final void freeze(Record rec)
                     throws java.io.IOException

This is equivalent to calling freeze(rec, true);

java.io.IOException

markStale

protected void markStale(Record rec)

Mark the record as "stale". It has either been deleted or superseded by a newer version.

normalizeKey

protected static java.lang.Object normalizeKey(java.lang.String type,
                                               java.lang.String key)
                                        throws java.io.IOException

Returns:

the "normalized" key given the record type.

java.io.IOException

handleEvent

public void handleEvent(DataEvent event)
                 throws java.io.IOException

Description copied from interface: DataListener

handle the event when the OreoDataSource we are listening to has modified data

Specified by:

handleEvent in interface DataListener

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.

Specified by:

writeSnapshot in interface OreoDataSource

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.

Specified by:

writeElement in interface OreoDataSource

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

Description copied from interface: OreoDataSource

loads data from an InputSource, meant to be used in a startup phase.

Specified by:

reload in interface OreoDataSource

org.xml.sax.SAXException

java.io.IOException

setUseXML

protected void setUseXML(boolean useXML)

useXML

protected boolean useXML()

fireEvents

protected boolean fireEvents()

setFireEvents

protected void setFireEvents(boolean fireEvents)

getName

public java.lang.String getName()
                         throws java.io.IOException

Specified by:

getName in interface OreoDataSource

Returns:

the name of this data source.

java.io.IOException

init

public void init(java.util.Properties props)
          throws java.io.IOException

Description copied from interface: OreoDataSource

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 OreoDataSource

java.io.IOException

get

public final Record get(java.lang.Object key)
                 throws java.io.IOException

Specified by:

get in interface OreoDataSource

Parameters:

key - the lookup key method that exists for backward compatibility This is equivalent to get(null, key);

java.io.IOException

keys

public final java.util.List keys()
                          throws java.io.IOException

Description copied from interface: OreoDataSource

This is equivalent to calling keys(null) where no record type is specified.

Specified by:

keys in interface OreoDataSource

java.io.IOException

wipeCache

public void wipeCache()
               throws java.io.IOException

Description copied from interface: OreoDataSource

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.

Specified by:

wipeCache in interface OreoDataSource

java.io.IOException

close

public void close()
           throws java.io.IOException

Description copied from interface: OreoDataSource

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

Specified by:

close in interface OreoDataSource

java.io.IOException

select

public final java.util.List select(RecordFilter filter)
                            throws java.io.IOException

Description copied from interface: OreoDataSource

This is equivalent to calling select(filter, null)

Specified by:

select in interface OreoDataSource

java.io.IOException

select

public java.util.List select(RecordFilter filter,
                             RecordComparator comparator)
                      throws java.io.IOException

Description copied from interface: OreoDataSource

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.

Specified by:

select in interface OreoDataSource

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

insert

public Record insert(Record rec)
              throws java.io.IOException

Description copied from interface: OreoDataSource

Adds a new record to the managed pool.

Specified by:

insert in interface OreoDataSource

Parameters:

rec - the record to add

Returns:

the added record (frozen).

Throws:

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

Description copied from interface: OreoDataSource

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

Specified by:

update in interface OreoDataSource

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

Description copied from interface: OreoDataSource

Delete a record.

Specified by:

delete in interface OreoDataSource

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

Description copied from interface: OreoDataSource

Delete a record.

Specified by:

delete in interface OreoDataSource

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

keys

public java.util.List keys(java.lang.String type)
                    throws java.io.IOException

Specified by:

keys in interface OreoDataSource

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

lookup

public java.util.List lookup(java.lang.Object lookupKey)
                      throws java.io.IOException

Description copied from interface: OreoDataSource

Some datasources may support a multiple lookup by key functionality.

Specified by:

lookup in interface OreoDataSource

Returns:

a List of Record objects

java.io.IOException

reload

public void reload(Record rec)
            throws java.io.IOException

Description copied from interface: OreoDataSource

loads a Record without any notification to listeners or any synchronization. Should only be used when restarting an app and restoring the data.

Specified by:

reload in interface OreoDataSource

java.io.IOException