JAC project
AOPSYS
CEDRIC & LIP6 labs

org.objectweb.jac.aspects.persistence
Class PersistenceAC

java.lang.Object
  |
  +--org.objectweb.jac.core.AspectComponent
        |
        +--org.objectweb.jac.aspects.persistence.PersistenceAC
All Implemented Interfaces:
BaseProgramListener, PersistenceConf, Serializable

public class PersistenceAC
extends AspectComponent
implements PersistenceConf

This AC defines a generic and configurable persistence aspect.

See Also:
Serialized Form

Nested Class Summary
static class PersistenceAC.NoSuchWrapperException
           
 
Field Summary
static String DISABLE_PRELOAD
           
static String NO_CACHE
           
static String PERSISTENT
          The global identifier for a persistent class in the RTTI.
static String PRELOAD_FIELD
           
static String RESTORE
           
static String ROOT
          The global identifier for a persistence root class in the RTTI.
protected  Storage storage
          The used storage.
static String VALUE_CONVERTER
           
 
Fields inherited from class org.objectweb.jac.core.AspectComponent
application, blockKeywords, firstCall, NOT_SHARED, SHARED, startWeavingCCount, startWeavingCount, startWeavingMethod, startWeavingType, systemListener, wrappers
 
Fields inherited from interface org.objectweb.jac.core.BaseProgramListener
FOUND_OBJECT
 
Constructor Summary
PersistenceAC()
           
 
Method Summary
 boolean beforeRunningWrapper(Wrapper wrapper, String wrappingMethod)
          This method is called when a wrapper is going to be applied to a wrappee.
 void checkUnload()
          This method is a callback for the timer that defines the max idle time.
 void configureStorage(ClassItem storageClass, String[] storageParameters)
          Specify which storage class to use and the parameters to use to instanciate it.
 void defineMaxIdleCheckPeriod(long period)
          Defines the period that is used to check that the collection max idle time has not been reached.
 void disableCache(CollectionItem collection)
          This configuration method allows to disable the cache for a given collection.
 String[] getDefaultConfigs()
          Returns defaults configuration files that must be loaded before the user's configuration
 OID getOID(Wrappee wrappee)
           
 Storage getStorage()
          Returns the storage.
static boolean isFieldPreloaded(FieldItem field)
           
 void makePersistent(String classExpr, String nameExpr)
          Configure persistence for one class.
 void maxIdle(CollectionItem collection, long maxIdle)
          Set a max idle time for a collection.
 void onExit()
          This method is upcalled when the system exits.
 void preloadAllFields(ClassItem cl)
          Set all fields of a class to be preloaded
 void preloadField(FieldItem field)
          Sets a field or collection to be preloaded
protected  void registerObject(OID oid, Object object)
          Add an object in the list of persistent objects.
 void registerStatics(String classExpr, String nameExpr)
          Registers a static name, that is a name that will not be changed by the persistence AC.
 void setValueConverter(ClassItem cl, ClassItem converter)
          Associate a String-Object converter with a class
 void whenConfigured()
          This method should be defined by the programmer when specific actions are needed once the aspect component has be configured.
 void whenDeleted(Wrappee object)
          Upcalled when an object is deleted.
 void whenDeserialized(SerializedJacObject orgObject)
          This method allows the deserialization of the OID of a persistent object.
 void whenFree(Wrappee object)
          Upcalled when an object is freed from the memory.
 void whenGetObjects(Collection objects, ClassItem cl)
          Load objects from the storage when required.
 String whenNameObject(Object object, String name)
          Delegates naming to the storage
 void whenObjectMiss(String name)
          The persistence aspect checks whether an object was in the storage when a NameRepository.getObject call failed.
 void whenSerialized(SerializedJacObject finalObject)
          This method add the OID info to the serialized JAC object when a serialization is requested by another aspect.
 
Methods inherited from class org.objectweb.jac.core.AspectComponent
addWrapper, afterApplicationStarted, afterRunningWrapper, afterWrap, afterWrappeeInit, attr, attrdef, beforeConfiguration, beforeReload, beforeWrappeeInit, configure, defines, defineTimer, doRegister, doUnregister, getApplication, getBlockKeywords, getConfigurationMethods, getConfigurationMethodsName, getConfigurationMethodsName, getName, getWrappers, init, isConfigurationMethod, isSystemListener, pointcut, pointcut, pointcut, pointcut, pointcut, pointcut, pointcut, pointcut, setApplication, setAttribute, setAttribute, setAttribute, setSystemListener, simulateUsingNewInstance, unweave, unwrapAll, weave, whenClone, whenCloseDisplay, whenDeserialized, whenReload, whenRemoteInstantiation, whenSerialized, whenTopologyChanged, whenUsingNewClass, whenUsingNewInstance, whenUsingNewInstance
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ROOT

public static final String ROOT
The global identifier for a persistence root class in the RTTI.

See Also:
Constant Field Values

PERSISTENT

public static final String PERSISTENT
The global identifier for a persistent class in the RTTI.

See Also:
Constant Field Values

VALUE_CONVERTER

public static final String VALUE_CONVERTER
See Also:
Constant Field Values

PRELOAD_FIELD

public static final String PRELOAD_FIELD
See Also:
Constant Field Values

DISABLE_PRELOAD

public static final String DISABLE_PRELOAD
See Also:
Constant Field Values

NO_CACHE

public static final String NO_CACHE
See Also:
Constant Field Values

RESTORE

public static final String RESTORE
See Also:
Constant Field Values

storage

protected Storage storage
The used storage.

Constructor Detail

PersistenceAC

public PersistenceAC()
Method Detail

onExit

public void onExit()
Description copied from interface: BaseProgramListener
This method is upcalled when the system exits.

Specified by:
onExit in interface BaseProgramListener
Overrides:
onExit in class AspectComponent

setValueConverter

public void setValueConverter(ClassItem cl,
                              ClassItem converter)
Description copied from interface: PersistenceConf
Associate a String-Object converter with a class

In order to stock objects in database, those objects must be converted in a String format. Basic classes are already implemented, but for new classes (such as java.awt.Dimension) new converters must be used. New converters can be used with fhis function.

Specified by:
setValueConverter in interface PersistenceConf
Parameters:
cl - the class to convert
converter - the converter used. The class must implement org.objectweb.jac.aspects.persistenceconf.StringConverter.
See Also:
StringConverter

checkUnload

public void checkUnload()
This method is a callback for the timer that defines the max idle time.

For all the collections that have a max idle time, it checks that this time is not reached. If it is reached, it unloads the collection.

See Also:
defineMaxIdleCheckPeriod(long), maxIdle(CollectionItem,long)

defineMaxIdleCheckPeriod

public void defineMaxIdleCheckPeriod(long period)
Description copied from interface: PersistenceConf
Defines the period that is used to check that the collection max idle time has not been reached.

If a collection max idle time is defined and that it has not been used for this time, then the collection is unloaded from the memory by the peristence.

This method is not mandatory, by default, a check period of 200.000 ms is defined.

Specified by:
defineMaxIdleCheckPeriod in interface PersistenceConf
Parameters:
period - the period time check in ms
See Also:
PersistenceConf.maxIdle(CollectionItem,long)

maxIdle

public void maxIdle(CollectionItem collection,
                    long maxIdle)
Description copied from interface: PersistenceConf
Set a max idle time for a collection.

The idle time corresponds to the time the collection is loaded in memory without having been accessed. By default, a collection stays in memory when it is loaded. For big collections, it might be interested to define a max idle time. When the max idle time is reached, the persistence aspect unloads this collection from the memory. The collection will be reloaded on the next access.

The frequency the max idle time has be reached is global to all collection and can be defined by defineMaxIdleCheckPeriod

Specified by:
maxIdle in interface PersistenceConf
Parameters:
collection - the collection that has a max idle
maxIdle - the max idle time in ms
See Also:
PersistenceConf.defineMaxIdleCheckPeriod(long)

whenConfigured

public void whenConfigured()
Description copied from class: AspectComponent
This method should be defined by the programmer when specific actions are needed once the aspect component has be configured.

Overrides:
whenConfigured in class AspectComponent

configureStorage

public void configureStorage(ClassItem storageClass,
                             String[] storageParameters)
Description copied from interface: PersistenceConf
Specify which storage class to use and the parameters to use to instanciate it. The choice of the storage's constructor is based on the number of arguments, so there should not be several constructors with the same number of arguments. Available storage are FSStorage and PostgresStorage

Specified by:
configureStorage in interface PersistenceConf
Parameters:
storageClass - the storage class
storageParameters - the parameters
See Also:
FSStorage, PostgresStorage

registerStatics

public void registerStatics(String classExpr,
                            String nameExpr)
Description copied from interface: PersistenceConf
Registers a static name, that is a name that will not be changed by the persistence AC.

Note that the root objects, as defined by the rtti aspect are automatically considered as static objects by the persistence aspect. Thus, it is useless to define a root object static.

Specified by:
registerStatics in interface PersistenceConf
Parameters:
classExpr - class expression of static objects
nameExpr - name expression of static objects
See Also:
RttiConf.addRoot(String)

makePersistent

public void makePersistent(String classExpr,
                           String nameExpr)
Description copied from interface: PersistenceConf
Configure persistence for one class.

The persistence type must be PersistenceAC.ROOT (a named object that is an entry point in the storage) or PersistenceAC.PERSISTENT for a regular persistent class.

ROOT objects are always wrapped, PERSISTENT are only wrapped when they become persistent, that is when they are linked to an already persistent object.

Specified by:
makePersistent in interface PersistenceConf
Parameters:
classExpr - class expression of static objects
nameExpr - name expression of static objects

getStorage

public Storage getStorage()
Returns the storage.

Returns:
the storage

whenObjectMiss

public void whenObjectMiss(String name)
The persistence aspect checks whether an object was in the storage when a NameRepository.getObject call failed.

Specified by:
whenObjectMiss in interface BaseProgramListener
Overrides:
whenObjectMiss in class AspectComponent
See Also:
BaseProgramListener.whenObjectMiss(String)

whenNameObject

public String whenNameObject(Object object,
                             String name)
Delegates naming to the storage

Specified by:
whenNameObject in interface BaseProgramListener
Overrides:
whenNameObject in class AspectComponent
Parameters:
object - the object to name
name - current name of the object or null
Returns:
the proposed name for the object

registerObject

protected void registerObject(OID oid,
                              Object object)
Add an object in the list of persistent objects.

Parameters:
oid - the OID of the object
object - the object

getOID

public OID getOID(Wrappee wrappee)

whenDeserialized

public void whenDeserialized(SerializedJacObject orgObject)
This method allows the deserialization of the OID of a persistent object.

Parameters:
orgObject - the JAC object structure that is beeing deserialized
See Also:
whenSerialized(SerializedJacObject)

whenSerialized

public void whenSerialized(SerializedJacObject finalObject)
This method add the OID info to the serialized JAC object when a serialization is requested by another aspect.

This adding allows, for instance, the OID to be transmitted to remote containers.

Parameters:
finalObject - the object that is being serialized

whenGetObjects

public void whenGetObjects(Collection objects,
                           ClassItem cl)
Load objects from the storage when required.

Specified by:
whenGetObjects in interface BaseProgramListener
Overrides:
whenGetObjects in class AspectComponent
Parameters:
objects - the returned list (can be modified)
cl - the class that was used by the program to filter its instances (can be null for all the objects)
See Also:
ObjectRepository

beforeRunningWrapper

public boolean beforeRunningWrapper(Wrapper wrapper,
                                    String wrappingMethod)
Description copied from class: AspectComponent
This method is called when a wrapper is going to be applied to a wrappee.

By overloading this method, the aspect component can skip the wrapper, for instance if the current collaboration shows that the wrapper has allready been applied.

If the method returns true, then the wrapper is run, else it is skipped. Default: return true.

Specified by:
beforeRunningWrapper in interface BaseProgramListener
Overrides:
beforeRunningWrapper in class AspectComponent
Parameters:
wrapper - the wrapper that is going to be runned
wrappingMethod - the name of the may-be runned wrapping method
Returns:
a boolean that tells if the wrapper has to be runned (true) or not (false)
See Also:
Wrappee, Wrapping.wrap(Wrappee,Wrapper,String,AbstractMethodItem), Wrapper, Wrapper.proceed(Interaction)

whenDeleted

public void whenDeleted(Wrappee object)
Description copied from interface: BaseProgramListener
Upcalled when an object is deleted.

Specified by:
whenDeleted in interface BaseProgramListener
Overrides:
whenDeleted in class AspectComponent

whenFree

public void whenFree(Wrappee object)
Description copied from interface: BaseProgramListener
Upcalled when an object is freed from the memory.

Specified by:
whenFree in interface BaseProgramListener
Overrides:
whenFree in class AspectComponent

preloadField

public void preloadField(FieldItem field)
Description copied from interface: PersistenceConf
Sets a field or collection to be preloaded

By default, persistent fields are loaded when accessed. Preloading a field force it to be loaded when the object is created : in the constructor.

Specified by:
preloadField in interface PersistenceConf
Parameters:
field - the field to preload

preloadAllFields

public void preloadAllFields(ClassItem cl)
Description copied from interface: PersistenceConf
Set all fields of a class to be preloaded

Same as preloadField, but for all fields of the class

Specified by:
preloadAllFields in interface PersistenceConf
Parameters:
cl - the class
See Also:
#preloadField(ClassItem,String)

isFieldPreloaded

public static boolean isFieldPreloaded(FieldItem field)

disableCache

public void disableCache(CollectionItem collection)
Description copied from interface: PersistenceConf
This configuration method allows to disable the cache for a given collection.

Then, the collection will never be loaded in the memory but the objects will be accessed directly in the storage.

Specified by:
disableCache in interface PersistenceConf

getDefaultConfigs

public String[] getDefaultConfigs()
Description copied from class: AspectComponent
Returns defaults configuration files that must be loaded before the user's configuration

Overrides:
getDefaultConfigs in class AspectComponent

Contact JAC development team:
Renaud Pawlak
Lionel Seinturier
Laurent Martelli