Coverage Report

Coverage Report - net.wotonomy.datastore.DataSoup

Classes in this File

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

1		/*
2		Wotonomy: OpenStep design patterns for pure Java applications.
3		Copyright (C) 2000 Michael Powers
4
5		This library is free software; you can redistribute it and/or
6		modify it under the terms of the GNU Lesser General Public
7		License as published by the Free Software Foundation; either
8		version 2.1 of the License, or (at your option) any later version.
9
10		This library is distributed in the hope that it will be useful,
11		but WITHOUT ANY WARRANTY; without even the implied warranty of
12		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13		Lesser General Public License for more details.
14
15		You should have received a copy of the GNU Lesser General Public
16		License along with this library; if not, see http://www.gnu.org
17		*/
18
19		package net.wotonomy.datastore;
20
21		import java.util.Collection;
22
23		public interface DataSoup
24		{
25		/**
26		* Adds the specified object to the soup and returns the key
27		* for the new object by which it may be subsequently retrieved.
28		* Null indicates an error, probably due to serialization.
29		* @param anObject Object to be added to soup.
30		* @return The unique identifier used for the new object.
31		*/
32		public DataKey addObject( Object anObject );
33
34		/**
35		* Removes the specified object from the soup and returns
36		* the removed object as read from the soup (which is the
37		* original copy of the object). Null indicates object not found.
38		* @param aKey A key for an object to be removed.
39		* @return The object that was removed, or null if not found or error.
40		*/
41		public Object removeObject( DataKey aKey );
42
43		/**
44		* Updates the specified object and returns the object
45		* as updated. Null indicates an error writing the object.
46		* @param aKey A key for an object to be updated.
47		* @param aKey The new object for that key.
48		* @return A copy of the updated object, possibly updated,
49		* or null if not found or error.
50		*/
51		public Object updateObject( DataKey aKey, Object updatedObject );
52
53		/**
54		* Gets object from data store whose identifier is equal
55		* to the specified object.
56		* @param aKey A key for an object to be retrieved.
57		* @return The corresponding object from the soup.
58		*/
59		public Object getObjectByKey( DataKey aKey );
60
61		/**
62		* Registers an object that may or may not be created
63		* later, returning a temporary but uniquely identifiable
64		* key. The key will be replaced with a permanent key when
65		* the object is created with addObject().
66		* @param anObject An object to be registered.
67		* @return A temporary key for this object.
68		*/
69		public DataKey registerTemporaryObject( Object anObject );
70
71		// index management
72
73		/**
74		* Adds an index to the soup.
75		* @param aName The string identifier for this index.
76		* @param aProperty The property on which this index will be based.
77		*/
78		public void addIndex( String aName, String aProperty );
79
80		/**
81		* Deletes the specified index from the soup.
82		* @param aName The string identifier for the index to be removed.
83		*/
84		public void removeIndex( String aName );
85
86		/**
87		* Gets a collection of all indices in this soup.
88		* @return A collection of all indices in this soup.
89		*/
90		public Collection getAllIndices();
91
92		// relationship management
93
94		/**
95		* Adds a relation to entries in another soup.
96		* @param aProperty The property on which this relation will be based.
97		* @param aSoup The name of the soup to be related in this store.
98		*/
99		// public void addRelation( String aProperty, String aSoup );
100
101		/**
102		* Deletes the specified relation to entries in another soup.
103		* @param aProperty The property on which this relation will be based.
104		* @param aSoup The name of the soup to be related in this store.
105		*/
106		// public void removeRelation( String aProperty, String aSoup );
107
108		/**
109		* Gets a collection of all relations in this soup.
110		* @return A collection of all relation in this soup.
111		*/
112		// public Collection getAllRelations();
113
114		// queries
115
116		/**
117		* Returns an empty data view, suitable for creating
118		* new entries in the soup.
119		* @return A DataView containing no entries.
120		*/
121		public DataView createView();
122
123		/**
124		* Queries by the specified pre-generated index, if it exists.
125		* Will return objects whose values for the indexed property
126		* fall between the two values inclusive.
127		* Otherwise, falls through to queryByProperty.
128		* @param anIndexName The index to be queried.
129		* @param beginValue The beginning value, or null for all values
130		* up to an including the end key.
131		* @param endValue The ending value, or null for all values
132		* since and including the begin key.
133		* @return A DataView containing the query results, or null
134		* for invalid query parameters.
135		*/
136		public DataView queryByIndex(
137		String anIndexName, Object beginKey, Object endKey );
138
139		/**
140		* Generates an index based on the specified property
141		* and then executes the query.
142		* Will return objects whose values for the specified property
143		* fall between the two values inclusive.
144		* @param aPropertyName The property to be queried. If null,
145		* will query the objects directly with queryObjects().
146		* @param beginValue The beginning value, or null for all values
147		* up to an including the end key.
148		* @param endValue The ending value, or null for all values
149		* since and including the begin key.
150		* @return A DataView containing the query results, or null
151		* for invalid query parameters.
152		*/
153		public DataView queryByProperty(
154		String aPropertyName, Object beginKey, Object endKey );
155
156		/**
157		* Generates an index based on the values of the objects themselves
158		* and then executes the query.
159		* Will return objects whose values fall between the two values inclusive.
160		* @param beginValue The beginning value, or null for all values
161		* up to and including the end key.
162		* @param endValue The ending value, or null for all values
163		* since and including the begin key.
164		* @return A DataView containing the query results, or null
165		* for invalid query parameters.
166		*/
167		public DataView queryObjects( Object beginKey, Object endKey );
168
169		/**
170		* Returns a view containing the objects for the specified keys.
171		* @param aKeyList A collection of keys to be placed in the view.
172		* @return A DataView containing the objects for the corresponding
173		* keys, in the order in which the keys are returned from the collection.
174		*/
175		public DataView queryByKeys( Collection aKeyList );
176
177		/**
178		* As queryByIndex, but with objects returned in reverse order.
179		* @param anIndexName The index to be queried.
180		* @param beginValue The beginning value, or null for all values
181		* up to and including the end key.
182		* @param endValue The ending value, or null for all values
183		* since and including the begin key.
184		* @return A DataView containing the query results, or null
185		* for invalid query parameters.
186		*/
187		public DataView reverseQueryByIndex(
188		String anIndexName, Object beginKey, Object endKey );
189
190		/**
191		* As queryByProperty, but with objects returned in reverse order.
192		* @param aPropertyName The property to be queried. If null,
193		* will query the objects directly with queryObjects().
194		* @param beginValue The beginning value, or null for all values
195		* up to and including the end key.
196		* @param endValue The ending value, or null for all values
197		* since and including the begin key.
198		* @return A DataView containing the query results, or null
199		* for invalid query parameters.
200		*/
201		public DataView reverseQueryByProperty(
202		String aPropertyName, Object beginKey, Object endKey );
203
204		/**
205		* As queryObjects, but with objects returned in reverse order.
206		* @param beginValue The beginning value, or null for all values
207		* up to and including the end key.
208		* @param endValue The ending value, or null for all values
209		* since and including the begin key.
210		* @return A DataView containing the query results, or null
211		* for invalid query parameters.
212		*/
213		public DataView reverseQueryObjects( Object beginKey, Object endKey );
214
215		// public void addIndex( String aName, DataIndex anIndex ) {}
216		// public void removeIndex( String aName ) {}
217		// public void addTaggedObject( String aKey, Serializable anObject )
218		// public Object getTaggedObject( String aKey );
219		// public void removeTaggedObject( String aKey );
220		// public void setMetaData(
221		// String aMetaProperty, Serializable aValue, Serializable anObject );
222
223		}
224
225		/*
226		* $Log$
227		* Revision 1.2 2006/02/19 16:26:19 cgruber
228		* Move non-unit-test code to tests project
229		* Fix up code to work with proper imports
230		* Fix maven dependencies.
231		*
232		* Revision 1.1 2006/02/16 13:18:56 cgruber
233		* Check in all sources in eclipse-friendly maven-enabled packages.
234		*
235		* Revision 1.4 2003/08/14 19:29:38 chochos
236		* minor cleanup (imports, static method calls, etc)
237		*
238		* Revision 1.3 2001/03/05 22:12:11 mpowers
239		* Created the control package for a datastore-specific implementation
240		* of EOObjectStore.
241		*
242		* Revision 1.2 2001/02/15 21:12:41 mpowers
243		* Added accessors for key throughout the api. This breaks compatibility.
244		* insertObject now returns the permanent key for the newly created object.
245		* The old way returned a copy of the object which was an additional read
246		* that was often ignored. Now you can read it only if you need it.
247		* Furthermore, there was not other way of getting the permanent key.
248		*
249		* Revision 1.1.1.1 2000/12/21 15:47:05 mpowers
250		* Contributing wotonomy.
251		*
252		* Revision 1.2 2000/12/20 16:25:36 michael
253		* Added log to all files.
254		*
255		*
256		*/
257