net.wotonomy.datastore
Interface DataSoup

All Known Implementing Classes:

FileSoup, SerializedFileSoup, XMLFileSoup

public interface DataSoup

Method Summary

void	addIndex(java.lang.String aName, java.lang.String aProperty) Adds an index to the soup.
DataKey	addObject(java.lang.Object anObject) Adds the specified object to the soup and returns the key for the new object by which it may be subsequently retrieved.
DataView	createView() Returns an empty data view, suitable for creating new entries in the soup.
java.util.Collection	getAllIndices() Gets a collection of all indices in this soup.
java.lang.Object	getObjectByKey(DataKey aKey) Gets object from data store whose identifier is equal to the specified object.
DataView	queryByIndex(java.lang.String anIndexName, java.lang.Object beginKey, java.lang.Object endKey) Queries by the specified pre-generated index, if it exists.
DataView	queryByKeys(java.util.Collection aKeyList) Returns a view containing the objects for the specified keys.
DataView	queryByProperty(java.lang.String aPropertyName, java.lang.Object beginKey, java.lang.Object endKey) Generates an index based on the specified property and then executes the query.
DataView	queryObjects(java.lang.Object beginKey, java.lang.Object endKey) Generates an index based on the values of the objects themselves and then executes the query.
DataKey	registerTemporaryObject(java.lang.Object anObject) Registers an object that may or may not be created later, returning a temporary but uniquely identifiable key.
void	removeIndex(java.lang.String aName) Deletes the specified index from the soup.
java.lang.Object	removeObject(DataKey aKey) Removes the specified object from the soup and returns the removed object as read from the soup (which is the original copy of the object).
DataView	reverseQueryByIndex(java.lang.String anIndexName, java.lang.Object beginKey, java.lang.Object endKey) As queryByIndex, but with objects returned in reverse order.
DataView	reverseQueryByProperty(java.lang.String aPropertyName, java.lang.Object beginKey, java.lang.Object endKey) As queryByProperty, but with objects returned in reverse order.
DataView	reverseQueryObjects(java.lang.Object beginKey, java.lang.Object endKey) As queryObjects, but with objects returned in reverse order.
java.lang.Object	updateObject(DataKey aKey, java.lang.Object updatedObject) Updates the specified object and returns the object as updated.

Method Detail

addObject

DataKey addObject(java.lang.Object anObject)

Adds the specified object to the soup and returns the key for the new object by which it may be subsequently retrieved. Null indicates an error, probably due to serialization.

Parameters:

anObject - Object to be added to soup.

Returns:

The unique identifier used for the new object.

removeObject

java.lang.Object removeObject(DataKey aKey)

Removes the specified object from the soup and returns the removed object as read from the soup (which is the original copy of the object). Null indicates object not found.

Parameters:

aKey - A key for an object to be removed.

Returns:

The object that was removed, or null if not found or error.

updateObject

java.lang.Object updateObject(DataKey aKey,
                              java.lang.Object updatedObject)

Updates the specified object and returns the object as updated. Null indicates an error writing the object.

Parameters:

aKey - A key for an object to be updated.

aKey - The new object for that key.

Returns:

A copy of the updated object, possibly updated, or null if not found or error.

getObjectByKey

java.lang.Object getObjectByKey(DataKey aKey)

Gets object from data store whose identifier is equal to the specified object.

Parameters:

aKey - A key for an object to be retrieved.

Returns:

The corresponding object from the soup.

registerTemporaryObject

DataKey registerTemporaryObject(java.lang.Object anObject)

Registers an object that may or may not be created later, returning a temporary but uniquely identifiable key. The key will be replaced with a permanent key when the object is created with addObject().

Parameters:

anObject - An object to be registered.

Returns:

A temporary key for this object.

addIndex

void addIndex(java.lang.String aName,
              java.lang.String aProperty)

Adds an index to the soup.

Parameters:

aName - The string identifier for this index.

aProperty - The property on which this index will be based.

removeIndex

void removeIndex(java.lang.String aName)

Deletes the specified index from the soup.

Parameters:

aName - The string identifier for the index to be removed.

getAllIndices

java.util.Collection getAllIndices()

Gets a collection of all indices in this soup.

Returns:

A collection of all indices in this soup.

createView

DataView createView()

Returns an empty data view, suitable for creating new entries in the soup.

Returns:

A DataView containing no entries.

queryByIndex

DataView queryByIndex(java.lang.String anIndexName,
                      java.lang.Object beginKey,
                      java.lang.Object endKey)

Queries by the specified pre-generated index, if it exists. Will return objects whose values for the indexed property fall between the two values inclusive. Otherwise, falls through to queryByProperty.

Parameters:

anIndexName - The index to be queried.

beginValue - The beginning value, or null for all values up to an including the end key.

endValue - The ending value, or null for all values since and including the begin key.

Returns:

A DataView containing the query results, or null for invalid query parameters.

queryByProperty

DataView queryByProperty(java.lang.String aPropertyName,
                         java.lang.Object beginKey,
                         java.lang.Object endKey)

Generates an index based on the specified property and then executes the query. Will return objects whose values for the specified property fall between the two values inclusive.

Parameters:

aPropertyName - The property to be queried. If null, will query the objects directly with queryObjects().

beginValue - The beginning value, or null for all values up to an including the end key.

endValue - The ending value, or null for all values since and including the begin key.

Returns:

A DataView containing the query results, or null for invalid query parameters.

queryObjects

DataView queryObjects(java.lang.Object beginKey,
                      java.lang.Object endKey)

Generates an index based on the values of the objects themselves and then executes the query. Will return objects whose values fall between the two values inclusive.

Parameters:

beginValue - The beginning value, or null for all values up to and including the end key.

endValue - The ending value, or null for all values since and including the begin key.

Returns:

A DataView containing the query results, or null for invalid query parameters.

queryByKeys

DataView queryByKeys(java.util.Collection aKeyList)

Returns a view containing the objects for the specified keys.

Parameters:

aKeyList - A collection of keys to be placed in the view.

Returns:

A DataView containing the objects for the corresponding keys, in the order in which the keys are returned from the collection.

reverseQueryByIndex

DataView reverseQueryByIndex(java.lang.String anIndexName,
                             java.lang.Object beginKey,
                             java.lang.Object endKey)

As queryByIndex, but with objects returned in reverse order.

Parameters:

anIndexName - The index to be queried.

beginValue - The beginning value, or null for all values up to and including the end key.

endValue - The ending value, or null for all values since and including the begin key.

Returns:

A DataView containing the query results, or null for invalid query parameters.

reverseQueryByProperty

DataView reverseQueryByProperty(java.lang.String aPropertyName,
                                java.lang.Object beginKey,
                                java.lang.Object endKey)

As queryByProperty, but with objects returned in reverse order.

Parameters:

aPropertyName - The property to be queried. If null, will query the objects directly with queryObjects().

beginValue - The beginning value, or null for all values up to and including the end key.

endValue - The ending value, or null for all values since and including the begin key.

Returns:

A DataView containing the query results, or null for invalid query parameters.

reverseQueryObjects

DataView reverseQueryObjects(java.lang.Object beginKey,
                             java.lang.Object endKey)

As queryObjects, but with objects returned in reverse order.

Parameters:

beginValue - The beginning value, or null for all values up to and including the end key.

endValue - The ending value, or null for all values since and including the begin key.

Returns:

A DataView containing the query results, or null for invalid query parameters.