/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2000 Michael Powers

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, see http://www.gnu.org
*/

package net.wotonomy.datastore;

import java.util.Collection;

public interface DataSoup {
	/**
	 * 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.
	 * 
	 * @param anObject Object to be added to soup.
	 * @return The unique identifier used for the new object.
	 */
	public DataKey addObject(Object anObject);

	/**
	 * 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.
	 * 
	 * @param aKey A key for an object to be removed.
	 * @return The object that was removed, or null if not found or error.
	 */
	public Object removeObject(DataKey aKey);

	/**
	 * Updates the specified object and returns the object as updated. Null
	 * indicates an error writing the object.
	 * 
	 * @param aKey A key for an object to be updated.
	 * @param aKey The new object for that key.
	 * @return A copy of the updated object, possibly updated, or null if not found
	 *         or error.
	 */
	public Object updateObject(DataKey aKey, Object updatedObject);

	/**
	 * Gets object from data store whose identifier is equal to the specified
	 * object.
	 * 
	 * @param aKey A key for an object to be retrieved.
	 * @return The corresponding object from the soup.
	 */
	public Object getObjectByKey(DataKey aKey);

	/**
	 * 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().
	 * 
	 * @param anObject An object to be registered.
	 * @return A temporary key for this object.
	 */
	public DataKey registerTemporaryObject(Object anObject);

	// index management

	/**
	 * Adds an index to the soup.
	 * 
	 * @param aName     The string identifier for this index.
	 * @param aProperty The property on which this index will be based.
	 */
	public void addIndex(String aName, String aProperty);

	/**
	 * Deletes the specified index from the soup.
	 * 
	 * @param aName The string identifier for the index to be removed.
	 */
	public void removeIndex(String aName);

	/**
	 * Gets a collection of all indices in this soup.
	 * 
	 * @return A collection of all indices in this soup.
	 */
	public Collection<String> getAllIndices();

	// relationship management

	/**
	 * Adds a relation to entries in another soup.
	 * 
	 * @param aProperty The property on which this relation will be based.
	 * @param aSoup     The name of the soup to be related in this store.
	 */
//    public void addRelation( String aProperty, String aSoup );

	/**
	 * Deletes the specified relation to entries in another soup.
	 * 
	 * @param aProperty The property on which this relation will be based.
	 * @param aSoup     The name of the soup to be related in this store.
	 */
//    public void removeRelation( String aProperty, String aSoup ); 

	/**
	 * Gets a collection of all relations in this soup.
	 * 
	 * @return A collection of all relation in this soup.
	 */
//	public Collection getAllRelations();

	// queries

	/**
	 * Returns an empty data view, suitable for creating new entries in the soup.
	 * 
	 * @return A DataView containing no entries.
	 */
	public DataView createView();

	/**
	 * 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.
	 * 
	 * @param anIndexName The index to be queried.
	 * @param beginValue  The beginning value, or null for all values up to an
	 *                    including the end key.
	 * @param endValue    The ending value, or null for all values since and
	 *                    including the begin key.
	 * @return A DataView containing the query results, or null for invalid query
	 *         parameters.
	 */
	public DataView queryByIndex(String anIndexName, Object beginKey, 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.
	 * 
	 * @param aPropertyName The property to be queried. If null, will query the
	 *                      objects directly with queryObjects().
	 * @param beginValue    The beginning value, or null for all values up to an
	 *                      including the end key.
	 * @param endValue      The ending value, or null for all values since and
	 *                      including the begin key.
	 * @return A DataView containing the query results, or null for invalid query
	 *         parameters.
	 */
	public DataView queryByProperty(String aPropertyName, Object beginKey, 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.
	 * 
	 * @param beginValue The beginning value, or null for all values up to and
	 *                   including the end key.
	 * @param endValue   The ending value, or null for all values since and
	 *                   including the begin key.
	 * @return A DataView containing the query results, or null for invalid query
	 *         parameters.
	 */
	public DataView queryObjects(Object beginKey, Object endKey);

	/**
	 * Returns a view containing the objects for the specified keys.
	 * 
	 * @param aKeyList A collection of keys to be placed in the view.
	 * @return A DataView containing the objects for the corresponding keys, in the
	 *         order in which the keys are returned from the collection.
	 */
	public DataView queryByKeys(Collection<String> aKeyList);

	/**
	 * As queryByIndex, but with objects returned in reverse order.
	 * 
	 * @param anIndexName The index to be queried.
	 * @param beginValue  The beginning value, or null for all values up to and
	 *                    including the end key.
	 * @param endValue    The ending value, or null for all values since and
	 *                    including the begin key.
	 * @return A DataView containing the query results, or null for invalid query
	 *         parameters.
	 */
	public DataView reverseQueryByIndex(String anIndexName, Object beginKey, Object endKey);

	/**
	 * As queryByProperty, but with objects returned in reverse order.
	 * 
	 * @param aPropertyName The property to be queried. If null, will query the
	 *                      objects directly with queryObjects().
	 * @param beginValue    The beginning value, or null for all values up to and
	 *                      including the end key.
	 * @param endValue      The ending value, or null for all values since and
	 *                      including the begin key.
	 * @return A DataView containing the query results, or null for invalid query
	 *         parameters.
	 */
	public DataView reverseQueryByProperty(String aPropertyName, Object beginKey, Object endKey);

	/**
	 * As queryObjects, but with objects returned in reverse order.
	 * 
	 * @param beginValue The beginning value, or null for all values up to and
	 *                   including the end key.
	 * @param endValue   The ending value, or null for all values since and
	 *                   including the begin key.
	 * @return A DataView containing the query results, or null for invalid query
	 *         parameters.
	 */
	public DataView reverseQueryObjects(Object beginKey, Object endKey);

//    public void addIndex( String aName, DataIndex anIndex ) {}
//    public void removeIndex( String aName ) {}
//    public void addTaggedObject( String aKey, Serializable anObject )
//    public Object getTaggedObject( String aKey );
//    public void removeTaggedObject( String aKey );
//    public void setMetaData( 
//	String aMetaProperty, Serializable aValue, Serializable anObject );

}

/*
 * $Log$ Revision 1.2 2006/02/19 16:26:19 cgruber Move non-unit-test code to
 * tests project Fix up code to work with proper imports Fix maven dependencies.
 *
 * Revision 1.1 2006/02/16 13:18:56 cgruber Check in all sources in
 * eclipse-friendly maven-enabled packages.
 *
 * Revision 1.4 2003/08/14 19:29:38 chochos minor cleanup (imports, static
 * method calls, etc)
 *
 * Revision 1.3 2001/03/05 22:12:11 mpowers Created the control package for a
 * datastore-specific implementation of EOObjectStore.
 *
 * Revision 1.2 2001/02/15 21:12:41 mpowers Added accessors for key throughout
 * the api. This breaks compatibility. insertObject now returns the permanent
 * key for the newly created object. The old way returned a copy of the object
 * which was an additional read that was often ignored. Now you can read it only
 * if you need it. Furthermore, there was not other way of getting the permanent
 * key.
 *
 * Revision 1.1.1.1 2000/12/21 15:47:05 mpowers Contributing wotonomy.
 *
 * Revision 1.2 2000/12/20 16:25:36 michael Added log to all files.
 *
 *
 */