KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > jac > aspects > persistence > Storage


1 /*
2   Copyright (C) 2001-2004 Laurent Martelli <laurent@aopsys.com>
3
4   This program is free software; you can redistribute it and/or modify
5   it under the terms of the GNU Lesser General Public License as
6   published by the Free Software Foundation; either version 2 of the
7   License, or (at your option) any later version.
8
9   This program is distributed in the hope that it will be useful,
10   but WITHOUT ANY WARRANTY; without even the implied warranty of
11   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12   GNU Lesser General Public License for more details.
13
14   You should have received a copy of the GNU Lesser General Public License
15   along with this program; if not, write to the Free Software
16   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */
17
18 package org.objectweb.jac.aspects.persistence;
19
20 import java.lang.IndexOutOfBoundsException JavaDoc;
21 import java.util.Collection JavaDoc;
22 import java.util.List JavaDoc;
23 import java.util.Map JavaDoc;
24 import org.objectweb.jac.core.rtti.ClassItem;
25 import org.objectweb.jac.core.rtti.CollectionItem;
26 import org.objectweb.jac.core.rtti.FieldItem;
27
28 /**
29  * The Storage interface defines methods to store and retrieve objects
30  * fields to and from a media (it could be a database, simples files
31  * ...)
32  */
33
34 public interface Storage {
35     
36     /**
37      * Returns the id of the storage
38      */
39     String JavaDoc getId();
40
41     /**
42      * Sets the id of the storage
43      */
44     void setId(String JavaDoc id);
45
46     /**
47      * Create an object in the storage.
48      *
49      * @param className a <code>String</code> value
50      * @return the OID of new object
51      * @exception Exception if an error occurs
52      */
53     OID createObject(String JavaDoc className) throws Exception JavaDoc;
54
55     /**
56      * Delete an object from the storage.
57      *
58      * @param oid the ID of the object to delete
59      * @exception Exception if an error occurs
60      */
61     void deleteObject(OID oid) throws Exception JavaDoc;
62
63     /**
64      * Initialize the value of an object's field. The field must not
65      * have already been set.
66      *
67      * @param oid the ID of the object that will contain the field
68      * @param field the field to set
69      * @param value the value of the field
70      * @exception Exception if an error occurs
71      */
72     void setField(OID oid, FieldItem field, Object JavaDoc value)
73         throws Exception JavaDoc;
74
75     /**
76      * Update a field value.
77      *
78      * @param oid the ID of the object that already contains the field
79      * @param field the field to update
80      * @param value the new value of the field
81      * @exception Exception if an error occurs
82      */
83     void updateField(OID oid, FieldItem field, Object JavaDoc value)
84         throws Exception JavaDoc;
85
86     /**
87      * Get the value of a field.
88      *
89      * @param oid the ID of the object that contains the field
90      * @param field the field to retrieve
91      * @return the stored value of the field, or null if there's no
92      * stored value for that field
93      * @exception Exception if an error occurs */
94     Object JavaDoc getField(OID oid, FieldItem field)
95         throws Exception JavaDoc;
96    
97     /**
98      * Get the values of several fields.
99      *
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 JavaDoc;
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 JavaDoc;
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 JavaDoc getList(OID oid, CollectionItem collection)
134         throws Exception JavaDoc, IndexOutOfBoundsException JavaDoc;
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 JavaDoc getList(OID cid)
144         throws Exception JavaDoc;
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 JavaDoc getListItem(OID cid, long index)
155         throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc value)
175         throws Exception JavaDoc;
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 JavaDoc value)
187         throws Exception JavaDoc;
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 JavaDoc value)
197         throws Exception JavaDoc;
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 JavaDoc value)
208         throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc value)
228         throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc value)
247         throws Exception JavaDoc;
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 JavaDoc value)
258         throws Exception JavaDoc;
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 JavaDoc getSet(OID oid, CollectionItem collection)
271         throws Exception JavaDoc ;
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 JavaDoc getSet(OID cid)
281         throws Exception JavaDoc ;
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 JavaDoc;
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 JavaDoc value)
302         throws Exception JavaDoc ;
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 JavaDoc value)
313         throws Exception JavaDoc ;
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 JavaDoc;
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 JavaDoc value)
333         throws Exception JavaDoc;
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 JavaDoc getMap(OID oid, CollectionItem collection)
346         throws Exception JavaDoc;
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 JavaDoc getMap(OID cid)
356         throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc putInMap(OID cid, Object JavaDoc key, Object JavaDoc value)
377         throws Exception JavaDoc;
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 JavaDoc getFromMap(OID cid, Object JavaDoc key)
388         throws Exception JavaDoc;
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 JavaDoc key)
399         throws Exception JavaDoc;
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 JavaDoc value)
410         throws Exception JavaDoc;
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 JavaDoc removeFromMap(OID cid, Object JavaDoc key)
421         throws Exception JavaDoc;
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 JavaDoc;
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 JavaDoc value)
440         throws Exception JavaDoc;
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 JavaDoc newName(String JavaDoc className) throws Exception JavaDoc;
449
450     /**
451      * Gets the name counters used to generate new names.
452      * @return a Map associating counter names to a Long value. The
453      * value is the next value to be used.
454      * @see #updateNameCounters(Map)
455      */
456     Map JavaDoc getNameCounters() throws Exception JavaDoc;
457
458     /**
459      * Sets the name counters used to generate new names.
460      * @param counters a Map associating counter names to a Long
461      * value. The value is the next value to be used. A counter is
462      * updated only if the suplied value is greater than the current
463      * value.
464      * @see #getNameCounters()
465      */
466     void updateNameCounters(Map JavaDoc counters) throws Exception JavaDoc;
467
468     /**
469      * Get the ID of an object from its name.
470      *
471      * @param name the candidate object name
472      * @return null if not found
473      */
474     OID getOIDFromName(String JavaDoc name) throws Exception JavaDoc;
475
476     /**
477      * Get the name of an object from its oid.
478      *
479      * @param oid the candidate object oid
480      */
481     String JavaDoc getNameFromOID(OID oid) throws Exception JavaDoc;
482
483     /**
484      * Bind an existing object to a logical name to that it can be
485      * found later on.<p>
486      *
487      * This method allows the user to create persistence roots.<p>
488      *
489      * @param oid an existing object ID
490      * @param name the name that is given to it
491      */
492     void bindOIDToName(OID oid,String JavaDoc name) throws Exception JavaDoc;
493
494     /**
495      * Delete a name from the storage.
496      * @param name the name to remove
497      */
498     void deleteName(String JavaDoc name) throws Exception JavaDoc;
499
500     /**
501      * Get the class ID of a given object.<p>
502      *
503      * @param oid the object's class ID
504      * @exception Exception if an error occurs
505      */
506     String JavaDoc getClassID(OID oid) throws Exception JavaDoc;
507
508     /**
509      * Get OIDs of all root objects.
510      *
511      * @return the root objects
512      * @exception Exception if an error occurs
513      */
514     Collection JavaDoc getRootObjects() throws Exception JavaDoc;
515
516     /**
517      * Get all instances of a class, or all objects if cl == null.
518      *
519      * @param cl the class
520      * @return the instances
521      */
522     Collection JavaDoc getObjects(ClassItem cl) throws Exception JavaDoc;
523
524     /**
525      * Closes the storage.
526      */
527     void close();
528
529     /**
530      * Starts a transaction
531      */
532     void startTransaction() throws Exception JavaDoc;
533
534     /**
535      * Commit started transaction
536      */
537     void commit() throws Exception JavaDoc;
538
539     /**
540      * Rollback started transaction
541      */
542     void rollback() throws Exception JavaDoc;
543 }
544
Popular Tags