001    /*
002      Copyright (C) 2001-2004 Laurent Martelli <laurent@aopsys.com>
003    
004      This program is free software; you can redistribute it and/or modify
005      it under the terms of the GNU Lesser General Public License as
006      published by the Free Software Foundation; either version 2 of the
007      License, or (at your option) any later version.
008    
009      This program is distributed in the hope that it will be useful,
010      but WITHOUT ANY WARRANTY; without even the implied warranty of
011      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012      GNU Lesser General Public License for more details.
013    
014      You should have received a copy of the GNU Lesser General Public License
015      along with this program; if not, write to the Free Software
016      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
017    
018    package org.objectweb.jac.aspects.persistence;
019    
020    import java.lang.IndexOutOfBoundsException;
021    import java.util.Collection;
022    import java.util.List;
023    import java.util.Map;
024    import org.objectweb.jac.core.rtti.ClassItem;
025    import org.objectweb.jac.core.rtti.CollectionItem;
026    import org.objectweb.jac.core.rtti.FieldItem;
027    
028    /**
029     * The Storage interface defines methods to store and retrieve objects
030     * fields to and from a media (it could be a database, simples files
031     * ...)  
032     */
033    
034    public interface Storage {
035        
036        /**
037         * Returns the id of the storage
038         */
039        String getId();
040    
041        /**
042         * Sets the id of the storage
043         */
044        void setId(String id);
045    
046        /**
047         * Create an object in the storage.
048         *
049         * @param className a <code>String</code> value
050         * @return the OID of new object
051         * @exception Exception if an error occurs
052         */
053        OID createObject(String className) throws Exception;
054    
055        /**
056         * Delete an object from the storage.
057         *
058         * @param oid the ID of the object to delete
059         * @exception Exception if an error occurs
060         */
061        void deleteObject(OID oid) throws Exception;
062    
063        /**
064         * Initialize the value of an object's field. The field must not
065         * have already been set.
066         *
067         * @param oid the ID of the object that will contain the field
068         * @param field the field to set
069         * @param value the value of the field
070         * @exception Exception if an error occurs
071         */
072        void setField(OID oid, FieldItem field, Object value) 
073            throws Exception;
074    
075        /**
076         * Update a field value.
077         *
078         * @param oid the ID of the object that already contains the field
079         * @param field the field to update
080         * @param value the new value of the field
081         * @exception Exception if an error occurs
082         */
083        void updateField(OID oid, FieldItem field, Object value) 
084            throws Exception;
085    
086        /**
087         * Get the value of a field.
088         *
089         * @param oid the ID of the object that contains the field
090         * @param field the field to retrieve
091         * @return the stored value of the field, or null if there's no
092         * stored value for that field
093         * @exception Exception if an error occurs */
094        Object getField(OID oid, FieldItem field)
095            throws Exception;
096       
097        /**
098         * Get the values of several fields.
099         *
100         * @param oid the ID of object to retrieve
101         * @param cl the class of the object
102         * @param fields the fields to retrieve
103         * @return the value of the fields
104         * @exception Exception if an error occurs
105         */
106        StorageField[] getFields(OID oid, ClassItem cl, FieldItem[] fields) 
107            throws Exception;
108    
109        // Collection functions
110    
111        /**
112         * Get the ID of a collection
113         *
114         * @param oid the oid of he object that owns the collection
115         * @param collection the collection
116         * @return the id of the collection
117         * @exception Exception if an error occurs
118         */
119    
120        OID getCollectionID(OID oid, CollectionItem collection) 
121            throws Exception;
122    
123        // List functions
124    
125        /**
126         * Get a List from the storage.
127         *
128         * @param oid the ID of the object that contains the vector
129         * @param collection the collection to retrieve
130         * @return the List
131         * @exception Exception if an error occurs
132         */
133        List getList(OID oid, CollectionItem collection)
134            throws Exception, IndexOutOfBoundsException;
135    
136        /**
137         * Get a List from the storage. 
138         *
139         * @param cid the ID of the List 
140         * @return the List
141         * @exception Exception if an error occurs
142         */
143        List getList(OID cid)
144            throws Exception;
145    
146        /**
147         * Get an element from a list
148         *
149         * @param cid the ID of the List
150         * @param index the index of the element
151         * @return the element
152         * @exception Exception if an error occurs
153         */
154        Object getListItem(OID cid, long index)
155            throws Exception;
156       
157        /**
158         * Get the number of objects contained in a list
159         *
160         * @param cid the ID of the list
161         * @return the number of objects contained in the list
162         * @exception Exception if an error occurs
163         */
164        long getListSize(OID cid) throws Exception;
165       
166        /**
167         * Say if a List contains an object.
168         *
169         * @param cid the ID of the List
170         * @param value the object to look for in the list
171         * @return wether the List contains the value
172         * @exception Exception if an error occurs
173         */
174        boolean listContains(OID cid, Object value) 
175            throws Exception;
176    
177    
178        /**
179         * Insert a value into an existing List.
180         *
181         * @param cid the ID of the List
182         * @param position the position where to insert the value
183         * @param value the value to insert
184         * @exception Exception if an error occurs
185         */
186        void addToList(OID cid, long position, Object value)
187            throws Exception;
188    
189        /**
190         * Add a value at the end of a list.
191         *
192         * @param cid the ID of the List
193         * @param value the value to add
194         * @exception Exception if an error occurs
195         */
196        void addToList(OID cid, Object value)
197            throws Exception;
198    
199        /**
200         * Set the value of a list element.
201         *
202         * @param cid the ID of the List
203         * @param index the index of the element to set
204         * @param value the value
205         * @exception Exception if an error occurs
206         */
207        void setListItem(OID cid, long index, Object value)
208            throws Exception;
209    
210        /**
211         * Remove a value from an existing list.
212         *
213         * @param cid the ID the List
214         * @param position the position of the element to remove
215         * @exception Exception if an error occurs
216         */
217        void removeFromList(OID cid, long position)
218            throws Exception;
219    
220        /**
221         * Remove the first value from an existing list.
222         *
223         * @param cid the ID the List
224         * @param value the value to remove
225         * @exception Exception if an error occurs
226         */
227        void removeFromList(OID cid, Object value)
228            throws Exception;
229    
230        /**
231         * Remove all objects from a list.
232         *
233         * @param cid the ID of the list to clear
234         * @exception Exception if an error occurs
235         */
236        void clearList(OID cid) throws Exception;
237    
238        /**
239         * Get the smallest index of an element in a List.
240         *
241         * @param cid the ID of the List
242         * @param value the value
243         * @return the index of value
244         * @exception Exception if an error occurs
245         */
246        long getIndexInList(OID cid, Object value)
247            throws Exception;
248    
249        /**
250         * Get the highest index of an element in a List.
251         *
252         * @param cid the ID of the List
253         * @param value the value
254         * @return the index of value
255         * @exception Exception if an error occurs
256         */
257        long getLastIndexInList(OID cid, Object value)
258            throws Exception;
259    
260        // Set functions
261    
262        /**
263         * Get the elements of a Set.
264         *
265         * @param oid the ID of the object that contains the Set
266         * @param collection the collection
267         * @return the elements of the Set
268         * @exception Exception if an error occurs
269         */
270        List getSet(OID oid, CollectionItem collection) 
271            throws Exception ;
272    
273        /**
274         * Get the elements of a Set.
275         *
276         * @param cid the ID of the Set
277         * @return the elements of the Set
278         * @exception Exception if an error occurs
279         */
280        List getSet(OID cid) 
281            throws Exception ;
282    
283       
284        /**
285         * Get the number of objects contained in a set
286         *
287         * @param cid the ID of the list
288         * @return the number of objects contained in the set
289         * @exception Exception if an error occurs
290         */
291        long getSetSize(OID cid) throws Exception;
292    
293        /**
294         * Add an object to a Set.
295         *
296         * @param cid the ID of the Set
297         * @param value the value to add
298         * @return true if the set did not already contain the object, false otherwise.
299         * @exception Exception if an error occurs
300         */
301        boolean addToSet(OID cid, Object value) 
302            throws Exception ;
303    
304        /**
305         * Remove an element from a Set.
306         *
307         * @param cid the ID of the Set
308         * @param value the value to add
309         * @return wether the set did contain the object
310         * @exception Exception if an error occurs
311         */
312        boolean removeFromSet(OID cid, Object value) 
313            throws Exception ;
314    
315        /**
316         * Remove all objects from a set.
317         *
318         * @param cid the ID of the set to clear
319         * @exception Exception if an error occurs
320         */
321        void clearSet(OID cid) 
322            throws Exception;
323    
324        /**
325         * Say if a set contains an object.
326         *
327         * @param cid the ID of the Set
328         * @param value the value
329         * @return wether the Set contains the value
330         * @exception Exception if an error occurs
331         */
332        boolean setContains(OID cid, Object value) 
333            throws Exception;
334    
335        // Map functions
336    
337        /**
338         * Describe <code>getMap</code> method here.
339         *
340         * @param oid an <code>OID</code> value
341         * @param collection a <code>CollectionItem</code> value
342         * @return a <code>Map</code> value
343         * @exception Exception if an error occurs
344         */
345        Map getMap(OID oid, CollectionItem collection) 
346            throws Exception;
347    
348        /**
349         * Get the elements of a Map.
350         *
351         * @param cid the ID of the Set
352         * @return the Map
353         * @exception Exception if an error occurs
354         */
355        Map getMap(OID cid) 
356            throws Exception;
357       
358        /**
359         * Get the number of objects contained in a map
360         *
361         * @param cid the ID of the list
362         * @return the number of objects contained in the map
363         * @exception Exception if an error occurs
364         */
365        long getMapSize(OID cid) throws Exception;
366    
367        /**
368         * Put an element in a Map.
369         *
370         * @param cid the ID of the Map
371         * @param key the key
372         * @param value the value
373         * @return the previous value associated with the key
374         * @exception Exception if an error occurs
375         */
376        Object putInMap(OID cid, Object key, Object value) 
377            throws Exception;
378    
379        /**
380         * Get the value associated to a key from a Map.
381         *
382         * @param cid the ID of the Map
383         * @param key the key
384         * @return the value associated with the key
385         * @exception Exception if an error occurs
386         */
387        Object getFromMap(OID cid, Object key) 
388            throws Exception;
389    
390        /**
391         * Says if a Map contains a key.
392         *
393         * @param cid the ID of the Map
394         * @param key the key to search
395         * @return wether the Map contains the key
396         * @exception Exception if an error occurs
397         */
398        boolean mapContainsKey(OID cid, Object key)
399            throws Exception;
400    
401        /**
402         * Says if a Map contains a value.
403         *
404         * @param cid the ID of the Map
405         * @param value the value to search
406         * @return wether the Map contains the value
407         * @exception Exception if an error occurs
408         */
409        boolean mapContainsValue(OID cid, Object value)
410            throws Exception;
411    
412        /**
413         * Remove a key from a Map.
414         *
415         * @param cid the ID the Map
416         * @param key the key to remove
417         * @return the previous value associated to the key, or null
418         * @exception Exception if an error occurs
419         */
420        Object removeFromMap(OID cid, Object key)
421            throws Exception;
422    
423        /**
424         * Remove all objects from a set.
425         *
426         * @param cid the ID of the set to clear
427         * @exception Exception if an error occurs
428         */
429        void clearMap(OID cid) 
430            throws Exception;
431    
432        /**
433         * Remove a field from an existing object.
434         *
435         * @param oid the ID of the object that contains the field
436         * @param field the ID of the field to remove
437         * @param value <b>Deprecated</b> */
438    
439        void removeField(OID oid, FieldItem field, Object value) 
440            throws Exception;
441    
442        /**
443         * Generate a new name for an instance.
444         *
445         * @param className the className of the instance for which to generate a name
446         * @return the generated name, null if failure
447         */
448        String newName(String className) throws Exception;
449    
450        /**
451         * Gets the nam counters used to generate new names.
452         */
453        Map getNameCounters() throws Exception;
454    
455        /**
456         * Gets the nam counters used to generate new names.
457         */
458        void updateNameCounters(Map counters) throws Exception;
459    
460        /**
461         * Get the ID of an object from its name.
462         *
463         * @param name the candidate object name
464         * @return null if not found */
465    
466        OID getOIDFromName(String name) throws Exception;
467    
468        /**
469         * Get the name of an object from its oid.
470         *
471         * @param oid the candidate object oid */
472    
473        String getNameFromOID(OID oid) throws Exception;
474    
475        /**
476         * Bind an existing object to a logical name to that it can be
477         * found later on.<p>
478         *
479         * This method allows the user to create persistence roots.<p>
480         *
481         * @param oid an existing object ID
482         * @param name the name that is given to it */
483    
484        void bindOIDToName(OID oid,String name) throws Exception;
485    
486        /**
487         * Delete a name from the storage.
488         * @param name the name to remove
489         */
490       
491        void deleteName(String name) throws Exception;
492    
493        /**
494         * Get the class ID of a given object.<p>
495         *
496         * @param oid the object's class ID
497         * @exception Exception if an error occurs
498         */
499    
500        String getClassID(OID oid) throws Exception;
501    
502        /**
503         * Get OIDs of all root objects.
504         *
505         * @return the root objects
506         * @exception Exception if an error occurs
507         */
508        Collection getRootObjects() throws Exception;
509    
510        /**
511         * Get all instances of a class, or all objects if cl == null.
512         *
513         * @param cl the class
514         * @return the instances
515         */
516        Collection getObjects(ClassItem cl) throws Exception;
517    
518        /**
519         * Closes the storage.
520         */
521        void close();
522    
523        /**
524         * Starts a transaction
525         */
526        void startTransaction() throws Exception;
527    
528        /**
529         * Commit started transaction
530         */
531        void commit() throws Exception;
532    
533        /**
534         * Rollback started transaction
535         */
536        void rollback() throws Exception;
537    }