org.objectweb.jac.aspects.persistence
Interface Storage

All Known Implementing Classes:
FSStorage, SQLStorage

public interface Storage

The Storage interface defines methods to store and retrieve objects fields to and from a media (it could be a database, simples files ...)


Method Summary
 void addToList(OID cid, long position, Object value)
          Insert a value into an existing List.
 void addToList(OID cid, Object value)
          Add a value at the end of a list.
 boolean addToSet(OID cid, Object value)
          Add an object to a Set.
 void bindOIDToName(OID oid, String name)
          Bind an existing object to a logical name to that it can be found later on.
 void clearList(OID cid)
          Remove all objects from a list.
 void clearMap(OID cid)
          Remove all objects from a set.
 void clearSet(OID cid)
          Remove all objects from a set.
 void close()
          Closes the storage.
 void commit()
          Commit started transaction
 OID createObject(String className)
          Create an object in the storage.
 void deleteName(String name)
          Delete a name from the storage.
 void deleteObject(OID oid)
          Delete an object from the storage.
 String getClassID(OID oid)
          Get the class ID of a given object.
 OID getCollectionID(OID oid, CollectionItem collection)
          Get the ID of a collection
 Object getField(OID oid, FieldItem field)
          Get the value of a field.
 StorageField[] getFields(OID oid, ClassItem cl, FieldItem[] fields)
          Get the values of several fields.
 Object getFromMap(OID cid, Object key)
          Get the value associated to a key from a Map.
 String getId()
          Returns the id of the storage
 long getIndexInList(OID cid, Object value)
          Get the smallest index of an element in a List.
 long getLastIndexInList(OID cid, Object value)
          Get the highest index of an element in a List.
 List getList(OID cid)
          Get a List from the storage.
 List getList(OID oid, CollectionItem collection)
          Get a List from the storage.
 Object getListItem(OID cid, long index)
          Get an element from a list
 long getListSize(OID cid)
          Get the number of objects contained in a list
 Map getMap(OID cid)
          Get the elements of a Map.
 Map getMap(OID oid, CollectionItem collection)
          Describe getMap method here.
 long getMapSize(OID cid)
          Get the number of objects contained in a map
 Map getNameCounters()
          Gets the name counters used to generate new names.
 String getNameFromOID(OID oid)
          Get the name of an object from its oid.
 Collection getObjects(ClassItem cl)
          Get all instances of a class, or all objects if cl == null.
 OID getOIDFromName(String name)
          Get the ID of an object from its name.
 Collection getRootObjects()
          Get OIDs of all root objects.
 List getSet(OID cid)
          Get the elements of a Set.
 List getSet(OID oid, CollectionItem collection)
          Get the elements of a Set.
 long getSetSize(OID cid)
          Get the number of objects contained in a set
 boolean listContains(OID cid, Object value)
          Say if a List contains an object.
 boolean mapContainsKey(OID cid, Object key)
          Says if a Map contains a key.
 boolean mapContainsValue(OID cid, Object value)
          Says if a Map contains a value.
 String newName(String className)
          Generate a new name for an instance.
 Object putInMap(OID cid, Object key, Object value)
          Put an element in a Map.
 void removeField(OID oid, FieldItem field, Object value)
          Remove a field from an existing object.
 void removeFromList(OID cid, long position)
          Remove a value from an existing list.
 void removeFromList(OID cid, Object value)
          Remove the first value from an existing list.
 Object removeFromMap(OID cid, Object key)
          Remove a key from a Map.
 boolean removeFromSet(OID cid, Object value)
          Remove an element from a Set.
 void rollback()
          Rollback started transaction
 boolean setContains(OID cid, Object value)
          Say if a set contains an object.
 void setField(OID oid, FieldItem field, Object value)
          Initialize the value of an object's field.
 void setId(String id)
          Sets the id of the storage
 void setListItem(OID cid, long index, Object value)
          Set the value of a list element.
 void startTransaction()
          Starts a transaction
 void updateField(OID oid, FieldItem field, Object value)
          Update a field value.
 void updateNameCounters(Map counters)
          Sets the name counters used to generate new names.
 

Method Detail

getId

public String getId()
Returns the id of the storage


setId

public void setId(String id)
Sets the id of the storage


createObject

public OID createObject(String className)
                 throws Exception
Create an object in the storage.

Parameters:
className - a String value
Returns:
the OID of new object
Throws:
Exception - if an error occurs

deleteObject

public void deleteObject(OID oid)
                  throws Exception
Delete an object from the storage.

Parameters:
oid - the ID of the object to delete
Throws:
Exception - if an error occurs

setField

public void setField(OID oid,
                     FieldItem field,
                     Object value)
              throws Exception
Initialize the value of an object's field. The field must not have already been set.

Parameters:
oid - the ID of the object that will contain the field
field - the field to set
value - the value of the field
Throws:
Exception - if an error occurs

updateField

public void updateField(OID oid,
                        FieldItem field,
                        Object value)
                 throws Exception
Update a field value.

Parameters:
oid - the ID of the object that already contains the field
field - the field to update
value - the new value of the field
Throws:
Exception - if an error occurs

getField

public Object getField(OID oid,
                       FieldItem field)
                throws Exception
Get the value of a field.

Parameters:
oid - the ID of the object that contains the field
field - the field to retrieve
Returns:
the stored value of the field, or null if there's no stored value for that field
Throws:
Exception - if an error occurs

getFields

public StorageField[] getFields(OID oid,
                                ClassItem cl,
                                FieldItem[] fields)
                         throws Exception
Get the values of several fields.

Parameters:
oid - the ID of object to retrieve
cl - the class of the object
fields - the fields to retrieve
Returns:
the value of the fields
Throws:
Exception - if an error occurs

getCollectionID

public OID getCollectionID(OID oid,
                           CollectionItem collection)
                    throws Exception
Get the ID of a collection

Parameters:
oid - the oid of he object that owns the collection
collection - the collection
Returns:
the id of the collection
Throws:
Exception - if an error occurs

getList

public List getList(OID oid,
                    CollectionItem collection)
             throws Exception,
                    IndexOutOfBoundsException
Get a List from the storage.

Parameters:
oid - the ID of the object that contains the vector
collection - the collection to retrieve
Returns:
the List
Throws:
Exception - if an error occurs
IndexOutOfBoundsException

getList

public List getList(OID cid)
             throws Exception
Get a List from the storage.

Parameters:
cid - the ID of the List
Returns:
the List
Throws:
Exception - if an error occurs

getListItem

public Object getListItem(OID cid,
                          long index)
                   throws Exception
Get an element from a list

Parameters:
cid - the ID of the List
index - the index of the element
Returns:
the element
Throws:
Exception - if an error occurs

getListSize

public long getListSize(OID cid)
                 throws Exception
Get the number of objects contained in a list

Parameters:
cid - the ID of the list
Returns:
the number of objects contained in the list
Throws:
Exception - if an error occurs

listContains

public boolean listContains(OID cid,
                            Object value)
                     throws Exception
Say if a List contains an object.

Parameters:
cid - the ID of the List
value - the object to look for in the list
Returns:
wether the List contains the value
Throws:
Exception - if an error occurs

addToList

public void addToList(OID cid,
                      long position,
                      Object value)
               throws Exception
Insert a value into an existing List.

Parameters:
cid - the ID of the List
position - the position where to insert the value
value - the value to insert
Throws:
Exception - if an error occurs

addToList

public void addToList(OID cid,
                      Object value)
               throws Exception
Add a value at the end of a list.

Parameters:
cid - the ID of the List
value - the value to add
Throws:
Exception - if an error occurs

setListItem

public void setListItem(OID cid,
                        long index,
                        Object value)
                 throws Exception
Set the value of a list element.

Parameters:
cid - the ID of the List
index - the index of the element to set
value - the value
Throws:
Exception - if an error occurs

removeFromList

public void removeFromList(OID cid,
                           long position)
                    throws Exception
Remove a value from an existing list.

Parameters:
cid - the ID the List
position - the position of the element to remove
Throws:
Exception - if an error occurs

removeFromList

public void removeFromList(OID cid,
                           Object value)
                    throws Exception
Remove the first value from an existing list.

Parameters:
cid - the ID the List
value - the value to remove
Throws:
Exception - if an error occurs

clearList

public void clearList(OID cid)
               throws Exception
Remove all objects from a list.

Parameters:
cid - the ID of the list to clear
Throws:
Exception - if an error occurs

getIndexInList

public long getIndexInList(OID cid,
                           Object value)
                    throws Exception
Get the smallest index of an element in a List.

Parameters:
cid - the ID of the List
value - the value
Returns:
the index of value
Throws:
Exception - if an error occurs

getLastIndexInList

public long getLastIndexInList(OID cid,
                               Object value)
                        throws Exception
Get the highest index of an element in a List.

Parameters:
cid - the ID of the List
value - the value
Returns:
the index of value
Throws:
Exception - if an error occurs

getSet

public List getSet(OID oid,
                   CollectionItem collection)
            throws Exception
Get the elements of a Set.

Parameters:
oid - the ID of the object that contains the Set
collection - the collection
Returns:
the elements of the Set
Throws:
Exception - if an error occurs

getSet

public List getSet(OID cid)
            throws Exception
Get the elements of a Set.

Parameters:
cid - the ID of the Set
Returns:
the elements of the Set
Throws:
Exception - if an error occurs

getSetSize

public long getSetSize(OID cid)
                throws Exception
Get the number of objects contained in a set

Parameters:
cid - the ID of the list
Returns:
the number of objects contained in the set
Throws:
Exception - if an error occurs

addToSet

public boolean addToSet(OID cid,
                        Object value)
                 throws Exception
Add an object to a Set.

Parameters:
cid - the ID of the Set
value - the value to add
Returns:
true if the set did not already contain the object, false otherwise.
Throws:
Exception - if an error occurs

removeFromSet

public boolean removeFromSet(OID cid,
                             Object value)
                      throws Exception
Remove an element from a Set.

Parameters:
cid - the ID of the Set
value - the value to add
Returns:
wether the set did contain the object
Throws:
Exception - if an error occurs

clearSet

public void clearSet(OID cid)
              throws Exception
Remove all objects from a set.

Parameters:
cid - the ID of the set to clear
Throws:
Exception - if an error occurs

setContains

public boolean setContains(OID cid,
                           Object value)
                    throws Exception
Say if a set contains an object.

Parameters:
cid - the ID of the Set
value - the value
Returns:
wether the Set contains the value
Throws:
Exception - if an error occurs

getMap

public Map getMap(OID oid,
                  CollectionItem collection)
           throws Exception
Describe getMap method here.

Parameters:
oid - an OID value
collection - a CollectionItem value
Returns:
a Map value
Throws:
Exception - if an error occurs

getMap

public Map getMap(OID cid)
           throws Exception
Get the elements of a Map.

Parameters:
cid - the ID of the Set
Returns:
the Map
Throws:
Exception - if an error occurs

getMapSize

public long getMapSize(OID cid)
                throws Exception
Get the number of objects contained in a map

Parameters:
cid - the ID of the list
Returns:
the number of objects contained in the map
Throws:
Exception - if an error occurs

putInMap

public Object putInMap(OID cid,
                       Object key,
                       Object value)
                throws Exception
Put an element in a Map.

Parameters:
cid - the ID of the Map
key - the key
value - the value
Returns:
the previous value associated with the key
Throws:
Exception - if an error occurs

getFromMap

public Object getFromMap(OID cid,
                         Object key)
                  throws Exception
Get the value associated to a key from a Map.

Parameters:
cid - the ID of the Map
key - the key
Returns:
the value associated with the key
Throws:
Exception - if an error occurs

mapContainsKey

public boolean mapContainsKey(OID cid,
                              Object key)
                       throws Exception
Says if a Map contains a key.

Parameters:
cid - the ID of the Map
key - the key to search
Returns:
wether the Map contains the key
Throws:
Exception - if an error occurs

mapContainsValue

public boolean mapContainsValue(OID cid,
                                Object value)
                         throws Exception
Says if a Map contains a value.

Parameters:
cid - the ID of the Map
value - the value to search
Returns:
wether the Map contains the value
Throws:
Exception - if an error occurs

removeFromMap

public Object removeFromMap(OID cid,
                            Object key)
                     throws Exception
Remove a key from a Map.

Parameters:
cid - the ID the Map
key - the key to remove
Returns:
the previous value associated to the key, or null
Throws:
Exception - if an error occurs

clearMap

public void clearMap(OID cid)
              throws Exception
Remove all objects from a set.

Parameters:
cid - the ID of the set to clear
Throws:
Exception - if an error occurs

removeField

public void removeField(OID oid,
                        FieldItem field,
                        Object value)
                 throws Exception
Remove a field from an existing object.

Parameters:
oid - the ID of the object that contains the field
field - the ID of the field to remove
value - Deprecated
Exception

newName

public String newName(String className)
               throws Exception
Generate a new name for an instance.

Parameters:
className - the className of the instance for which to generate a name
Returns:
the generated name, null if failure
Exception

getNameCounters

public Map getNameCounters()
                    throws Exception
Gets the name counters used to generate new names.

Returns:
a Map associating counter names to a Long value. The value is the next value to be used.
Exception
See Also:
updateNameCounters(Map)

updateNameCounters

public void updateNameCounters(Map counters)
                        throws Exception
Sets the name counters used to generate new names.

Parameters:
counters - a Map associating counter names to a Long value. The value is the next value to be used. A counter is updated only if the suplied value is greater than the current value.
Exception
See Also:
getNameCounters()

getOIDFromName

public OID getOIDFromName(String name)
                   throws Exception
Get the ID of an object from its name.

Parameters:
name - the candidate object name
Returns:
null if not found
Exception

getNameFromOID

public String getNameFromOID(OID oid)
                      throws Exception
Get the name of an object from its oid.

Parameters:
oid - the candidate object oid
Exception

bindOIDToName

public void bindOIDToName(OID oid,
                          String name)
                   throws Exception
Bind an existing object to a logical name to that it can be found later on.

This method allows the user to create persistence roots.

Parameters:
oid - an existing object ID
name - the name that is given to it
Exception

deleteName

public void deleteName(String name)
                throws Exception
Delete a name from the storage.

Parameters:
name - the name to remove
Exception

getClassID

public String getClassID(OID oid)
                  throws Exception
Get the class ID of a given object.

Parameters:
oid - the object's class ID
Throws:
Exception - if an error occurs

getRootObjects

public Collection getRootObjects()
                          throws Exception
Get OIDs of all root objects.

Returns:
the root objects
Throws:
Exception - if an error occurs

getObjects

public Collection getObjects(ClassItem cl)
                      throws Exception
Get all instances of a class, or all objects if cl == null.

Parameters:
cl - the class
Returns:
the instances
Exception

close

public void close()
Closes the storage.


startTransaction

public void startTransaction()
                      throws Exception
Starts a transaction

Exception

commit

public void commit()
            throws Exception
Commit started transaction

Exception

rollback

public void rollback()
              throws Exception
Rollback started transaction

Exception