View Javadoc

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