JAC project
AOPSYS
CEDRIC & LIP6 labs

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.
 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
 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 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.
 

Method Detail

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

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

Contact JAC development team:
Renaud Pawlak
Lionel Seinturier
Laurent Martelli