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 }