org.objectweb.jac.core.rtti
Interface RttiConf

All Known Implementing Classes:
RttiAC

public interface RttiConf

This class defines the rtti aspect.

It allows the programmer to add some runtime type information on the classes of its applications.

Some configuration methods are useless since the type information is retrieved through bytecode analysis. They are kept in the interface in case of.

Author:
Renaud Pawlak, Laurent Martelli
See Also:
ClassItem, MethodItem, FieldItem, CollectionItem

Method Summary
 void addAccessedFields(MethodItem method, String[] accessedFields)
          Adds some accessed fields to a given method.
 void addAdder(CollectionItem collection, String method)
          Adds an adding method for a collection
 void addAllowedCast(ClassItem src, ClassItem dest)
          Specify that a type can be safely casted into another type.
 void addDependentField(FieldItem field, String dependentField)
          Declares a field dependency.
 void addFieldDependency(FieldItem field, FieldItem dependentField)
          Tells that when field changes, dependentField changes too.
 void addMixinMethod(ClassItem cli, MethodItem method)
          Adds a mixin method to a class.
 void addRemover(CollectionItem collection, String method)
          Adds a removing method for a collection
 void addWrittenFields(AbstractMethodItem method, String[] writtenFields)
          Adds some written fields to a given method.
 void declareAssociation(FieldItem roleA, FieldItem roleB)
          Declares an association made of two roles.
 void declareCalculatedField(ClassItem cl, String fieldName, String getterName)
          Declare a calculated field, which is a field with only a getter and no actual field.
 void definePrimaryKey(CollectionItem collection, String[] fields)
          Defines primary keys for a collection.
 void defineRepository(ClassItem type, String repositoryName, CollectionItem repositoryCollection)
          Declare a repository to get instances of a class from, instead of fetching all instances of the class, when ObjectRepository.getObjects(ClassItem) is called.
 void newVirtualClass(String className, ClassItem actualType)
          Create a new virtual class.
 void setAdder(CollectionItem collection, String method)
          Sets the adder of a collection.
 void setAggregation(FieldItem field, boolean isAggregation)
          Tells wether a relation is an aggregation or not.
 void setClass(ClassItem cli, String className)
          Sets a user defined class on a class.
 void setClass(MemberItem member, String className)
          Sets a user defined class on a class' member.
 void setClonedFields(String className, String[] fields)
          This configuration method tells that the fields (references or collections) must be cloned when the class is cloned.
 void setComponentType(CollectionItem collection, String type)
          Sets the component type of a collection, i.e. the type of objects it contains.
 void setDynamicFieldType(FieldItem field, MethodItem method)
          Use a method to dynamically determine the type of a field
 void setFieldType(FieldItem field, String type)
          Declares a field to be of a given type
 void setGetter(FieldItem field, String getterName)
          Sets the getter of a field
 void setIndexedField(CollectionItem collection, FieldItem indexedField)
          Tells that a Map implementing a collection indexes a field of the contained objects.
 void setIsIndex(CollectionItem collection, boolean isIndex)
          Specify wether a Map implementing a collection is a mere index for the collection (this is not the default).
 void setNullAllowed(FieldItem field)
          This configuration method tells that the field can be set to null (forbidden by default)
 void setNullAllowed(FieldItem field, boolean allowed)
          This configuration method tells wether the field can be set to null or not.
 void setNullAllowedParameters(AbstractMethodItem method, boolean[] nulls)
          Tells if JAC object-typed (references) arguments of a method can take null value while the method's invocation or if they should be choosen in existing instances list.
 void setOppositeRole(FieldItem field, FieldItem oppositeRole)
          Sets the opposite role of a reference or collection field
 void setParametersFields(AbstractMethodItem method, FieldItem[] fields)
          Specifies that the parameters of a method will be assigned to a given field.
 void setParametersType(AbstractMethodItem method, String[] types)
          Declare a method's parameters to be of a given type
 void setRemover(CollectionItem collection, String method)
          Sets the remover of a collection.
 void setSetter(FieldItem field, String setterName)
          Sets the setter of a field
 

Method Detail

addWrittenFields

public void addWrittenFields(AbstractMethodItem method,
                             String[] writtenFields)
Adds some written fields to a given method.

This configuration method must be used when a method changes some field values and does not follow the naming conventions (it is not a setter or an adder for instance).

Parameters:
method - the method
writtenFields - some new fields the method writes

addAccessedFields

public void addAccessedFields(MethodItem method,
                              String[] accessedFields)
Adds some accessed fields to a given method.

This configuration method must be used when a method reads some field values and does not follow the naming conventions (it is not a getter for instance).

Parameters:
method - the method
accessedFields - some new fields the method reads

declareCalculatedField

public void declareCalculatedField(ClassItem cl,
                                   String fieldName,
                                   String getterName)
Declare a calculated field, which is a field with only a getter and no actual field.

Parameters:
cl - the class item of te calculated field
fieldName - the name of the calculated field
getterName - the name of the getter method
See Also:
addDependentField(FieldItem,String)

setSetter

public void setSetter(FieldItem field,
                      String setterName)
Sets the setter of a field

Parameters:
field - the field
setterName - name of the setter method

setGetter

public void setGetter(FieldItem field,
                      String getterName)
Sets the getter of a field

Parameters:
field - the field
getterName - name of the getter method

addDependentField

public void addDependentField(FieldItem field,
                              String dependentField)
Declares a field dependency. It will cause the field to be refreshed when the dependent field's value changes.

Parameters:
field - the field to refresh
dependentField - the name of the field it depends on. It must be in the same class as field.
See Also:
declareCalculatedField(ClassItem,String,String)

addFieldDependency

public void addFieldDependency(FieldItem field,
                               FieldItem dependentField)
Tells that when field changes, dependentField changes too.


addAdder

public void addAdder(CollectionItem collection,
                     String method)
Adds an adding method for a collection

Parameters:
collection - the collection's name
method - the name of the adding method

setAdder

public void setAdder(CollectionItem collection,
                     String method)
Sets the adder of a collection.

Parameters:
collection - the collection
method - the name of the adder method

addRemover

public void addRemover(CollectionItem collection,
                       String method)
Adds a removing method for a collection

Parameters:
collection - the collection
method - the name of the removing method

setRemover

public void setRemover(CollectionItem collection,
                       String method)
Sets the remover of a collection.

Parameters:
collection - the collection
method - the name of the remover method

setFieldType

public void setFieldType(FieldItem field,
                         String type)
Declares a field to be of a given type

Parameters:
field - the field
type - the type
See Also:
setDynamicFieldType(FieldItem,MethodItem)

setDynamicFieldType

public void setDynamicFieldType(FieldItem field,
                                MethodItem method)
Use a method to dynamically determine the type of a field

Parameters:
field - the field
method - a static method taking as arguments a FieldItem and an Object (holder of the field), and return a ClassItem or a VirtualClassItem or a String.
See Also:
setFieldType(FieldItem,String)

setComponentType

public void setComponentType(CollectionItem collection,
                             String type)
Sets the component type of a collection, i.e. the type of objects it contains.

Parameters:
collection - the collection
type - the component type of the collection

setParametersType

public void setParametersType(AbstractMethodItem method,
                              String[] types)
Declare a method's parameters to be of a given type

Parameters:
method - the method
types - the types of each parameteropf the method

newVirtualClass

public void newVirtualClass(String className,
                            ClassItem actualType)
Create a new virtual class. Virtual classes allow you extend and refine the types used by the application, so that aspects can behave differently.

Parameters:
className - name of the new class
actualType - the actual primitive type that is extended

defineRepository

public void defineRepository(ClassItem type,
                             String repositoryName,
                             CollectionItem repositoryCollection)
Declare a repository to get instances of a class from, instead of fetching all instances of the class, when ObjectRepository.getObjects(ClassItem) is called.

Parameters:
type - the type of objects to add in the repository
repositoryName - the name of the object holding the repository
repositoryCollection - the collection to get the objects from. Any expression field can be used.
See Also:
ObjectRepository.getObjects(ClassItem)

setClonedFields

public void setClonedFields(String className,
                            String[] fields)
This configuration method tells that the fields (references or collections) must be cloned when the class is cloned.

Parameters:
className - the class name
fields - the names of the fields that are cloned

setClass

public void setClass(ClassItem cli,
                     String className)
Sets a user defined class on a class. This can be used by aspects user-defined configuration.

Parameters:
cli - the class to redefine
className - the new class name

setClass

public void setClass(MemberItem member,
                     String className)
Sets a user defined class on a class' member. This can be used by aspects user-defined configuration.

Parameters:
member - the member whose type to redefine
className - the new class name

setParametersFields

public void setParametersFields(AbstractMethodItem method,
                                FieldItem[] fields)
Specifies that the parameters of a method will be assigned to a given field.

Other aspects (such as the GUI aspect) may use this information to provide better default behaviour for the paramters.

Parameters:
method - the of the method
fields - an array of field items, one per parameter of the method. Elements of this array may be null if some parameters are not assigned to any field.

setNullAllowed

public void setNullAllowed(FieldItem field)
This configuration method tells that the field can be set to null (forbidden by default)

Parameters:
field - the field
See Also:
setNullAllowed(FieldItem,boolean)

setNullAllowed

public void setNullAllowed(FieldItem field,
                           boolean allowed)
This configuration method tells wether the field can be set to null or not. (forbidden by default)

Parameters:
field - the field
allowed - wether to allow null values
See Also:
setNullAllowed(FieldItem)

setNullAllowedParameters

public void setNullAllowedParameters(AbstractMethodItem method,
                                     boolean[] nulls)
Tells if JAC object-typed (references) arguments of a method can take null value while the method's invocation or if they should be choosen in existing instances list.

Parameters:
method - the method
nulls - a flags array that tells for each parameter whether it can be null (true) or not (false). It has no effect if the parameter is not a JAC object (a reference)

setIsIndex

public void setIsIndex(CollectionItem collection,
                       boolean isIndex)
Specify wether a Map implementing a collection is a mere index for the collection (this is not the default). In this case, CollectionItem.getActualCollection() returns the values contained in the hashtable, otherwise the (key,values) entries are returned.

Parameters:
collection - the collection
isIndex - wether the map is an index
See Also:
setIndexedField(CollectionItem,FieldItem), CollectionItem.getActualCollection(Object), CollectionItem.getActualCollectionThroughAccessor(Object)

setIndexedField

public void setIndexedField(CollectionItem collection,
                            FieldItem indexedField)
Tells that a Map implementing a collection indexes a field of the contained objects.

Parameters:
collection - the collection
indexedField - the field which is indexed by the map
See Also:
setIsIndex(CollectionItem,boolean), CollectionItem.getActualCollection(Object), CollectionItem.getActualCollectionThroughAccessor(Object)

definePrimaryKey

public void definePrimaryKey(CollectionItem collection,
                             String[] fields)
Defines primary keys for a collection.

It is used to check for double entries in the collection by checking the precised fields (it is the same as primary keys in a database).


setAggregation

public void setAggregation(FieldItem field,
                           boolean isAggregation)
Tells wether a relation is an aggregation or not. By default, relations are not aggregations.

Parameters:
field - the relation
isAggregation - wether the relation is an aggregations or not.

addAllowedCast

public void addAllowedCast(ClassItem src,
                           ClassItem dest)

Specify that a type can be safely casted into another type.

It can be useful it you changed the type of a field to a subclass of the original type that only adds new methods, and a persistence aspect complains that it cannot load this field anymore. dest should have constructor which takes a value of type src as the only argument.

Parameters:
src - type of the value to be casted
dest - type the value should be casted to

setOppositeRole

public void setOppositeRole(FieldItem field,
                            FieldItem oppositeRole)
Sets the opposite role of a reference or collection field

Parameters:
field - the field whose opposite role to set
oppositeRole - the opposite role of the fieldb
See Also:
declareAssociation(FieldItem,FieldItem)

declareAssociation

public void declareAssociation(FieldItem roleA,
                               FieldItem roleB)
Declares an association made of two roles.

When declared, the relations that constitutes the association's roles are tagged in the RTTI by the RttiAC.OPPOSITE_RELATION attribute (then they can be interpreted by other aspects such as Integrity, GUI or Persistence).

For instance, if you have a Customer class and an Order class:

    ,----------. 1    n ,-------.
    | Customer |--------| Order |
    `----------'        `-------'
 

Parameters:
roleA - the starting role (e.g. Customer.orders)
roleB - the ending role (e.g. Order.customer)

addMixinMethod

public void addMixinMethod(ClassItem cli,
                           MethodItem method)
                    throws InvalidDelegateException
Adds a mixin method to a class.

A mixin method of class is a method which is not defined in the code of that class, but which will be made available on that class's ClassItem.

Parameters:
cli - a class
method - a static method whose 1st argument must be cli.
InvalidDelegateException
See Also:
MixinMethodItem.invoke(Object,Object[])