/*
   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 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 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.
  *
  *
  */