org.objectweb.jac.core.rtti
Class CollectionItem

java.lang.Object
  |
  +--org.objectweb.jac.core.rtti.MetaItem
        |
        +--org.objectweb.jac.core.rtti.MetaItemDelegate
              |
              +--org.objectweb.jac.core.rtti.MemberItem
                    |
                    +--org.objectweb.jac.core.rtti.FieldItem
                          |
                          +--org.objectweb.jac.core.rtti.CollectionItem

public class CollectionItem
extends FieldItem

This class defines a meta item that corresponds to a java.lang.reflect.Field meta element that is of an array, a collection, or a map type.

Author:
Renaud Pawlak, Laurent Martelli
See Also:
Collection, Map, Arrays, Field

Field Summary
protected  ClassItem componentType
           
static CollectionItem[] emptyArray
           
 
Fields inherited from class org.objectweb.jac.core.rtti.MemberItem
role, roleClassType, roleName, roleType
 
Fields inherited from class org.objectweb.jac.core.rtti.MetaItemDelegate
delegate, parent
 
Fields inherited from class org.objectweb.jac.core.rtti.MetaItem
attrACs
 
Constructor Summary
CollectionItem(Field delegate, ClassItem parent)
          Creates a CollectionItem for a real field
CollectionItem(String name, List path, ClassItem parent)
          Creates a CollectionItem for an expression field.
CollectionItem(String name, MethodItem getter, ClassItem parent)
          Creates a CollectionItem for a calculated field.
 
Method Summary
 void add(Object substance, Object newItem, Object extraInfos)
          Adds an item to the collection.
 void addAddingMethod(MethodItem addingMethod)
          Adds a new adding method for this field.
 void addRemovingMethod(MethodItem removingMethod)
          Adds a new removing method for this field.
 void addThroughAdder(Object substance, Object value)
          Adds an item to the collection, using the adder method if it has one.
 void clear(Object substance)
          Clears the collection on the given object.
 void clearMethods()
          Clears all the methods that has been set to be removers or adders for this collection item.
 FieldItem clone(ClassItem parent)
          Copies this field to an other class.
 boolean contains(Object substance, Object object)
          Tells wether an object's collection contains an given object
 Collection getActualCollection(Object substance)
          Gets the collection object represented by this collection item.
 Collection getActualCollectionThroughAccessor(Object substance)
          Gets the collection object represented by this collection item by using the accessor defined in the class containing this collection if any.
 MethodItem getAdder()
          Returns the adder of the collection, or null if it has no adder.
 MethodItem[] getAddingMethods()
          Gets the method items that access this collection for adding.
 CollectionItem getCollection()
          Returns the actual collection item.
 ClassItem getComponentType()
          Returns the type of the objects contained in this collection.
protected  Map getMap(Object substance)
           
 Object getMap(Object substance, Object key)
           
 MethodItem getRemover()
          Returns the remover of the collection, or null if it has no remover.
 MethodItem[] getRemovingMethods()
          Gets the methods that access this collection for removing.
 boolean hasAdder()
          Returns true if the collection has at least one adding method.
 boolean hasRemover()
          Returns true if the collection has at least one removing method.
 boolean isAddingMethod(MethodItem method)
           
 boolean isArray()
          Tells if this collection is actually an array.
 boolean isIndex()
           
 boolean isList()
          Tells if this collection item is compliant with a java.util.List interface.
 boolean isMap()
          Tells if this collection item is compliant with a java.util.Map interface.
 boolean isPrimitive()
          Always returns false for collections (maybe not very semantically clear).
 boolean isReference()
          Always returns false for collections (maybe not very semantically clear).
 boolean isRemovingMethod(MethodItem method)
           
 boolean isSet()
          Tells if this collection item is compliant with a java.util.Set interface.
 void putThroughAdder(Object substance, Object value, Object key)
           
 void remove(Object substance, Object item, Object extraInfos)
          Removes an item from the collection.
 void removeThroughRemover(Object substance, Object item)
          Removes an item from the collection, using the remover method if it has one.
 void setAdder(MethodItem adder)
          Sets the adder of the collection.
 void setAddingMethods(MethodItem[] addingMethods)
          Sets the methods that access this collection for adding.
 void setComponentType(ClassItem componentType)
          Sets the component type of the collection.
 void setRemover(MethodItem remover)
          Sets the remover of the collection.
 void setRemovingMethods(MethodItem[] removingMethods)
          Sets the methods that access this collection for removing.
 Collection toCollection(Object value)
          A useful method to convert any kind of collection to a java.util.Collection compatible instance.
 
Methods inherited from class org.objectweb.jac.core.rtti.FieldItem
addAccessingMethod, addDependentField, addWritingMethod, get, getAccessingMethods, getActualField, getAttribute, getDependentFields, getField, getGetter, getModifiers, getName, getOppositeRole, getPathLeaves, getPathTop, getRelativeField, getSetter, getSubstance, getSubstances, getThroughAccessor, getType, getWritingMethods, hasAccessingMethods, hasWritingMethods, isAggregation, isCalculated, isFinal, isStatic, isTransient, isWrappable, lastField, set, setAccessingMethods, setAggregation, setConvert, setGetter, setOppositeRole, setSetter, setThroughWriter, setType, setWritingMethods, startsWith, toFields
 
Methods inherited from class org.objectweb.jac.core.rtti.MemberItem
addDependentMethod, equals, getClassItem, getDependentMethods, getLongName, getMemberFromFullName, getTypeItem, isRole, setRole, toString
 
Methods inherited from class org.objectweb.jac.core.rtti.MetaItemDelegate
getDelegate, getParent, setParent
 
Methods inherited from class org.objectweb.jac.core.rtti.MetaItem
getAttribute, getAttribute, getAttributeAlways, getBoolean, getItemClass, registerAccessController, setAttribute, setItemClass, unsetAttribute, unsetAttributesFor
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

componentType

protected ClassItem componentType

emptyArray

public static final CollectionItem[] emptyArray
Constructor Detail

CollectionItem

public CollectionItem(Field delegate,
                      ClassItem parent)
               throws InvalidDelegateException
Creates a CollectionItem for a real field

Parameters:
delegate - the field the collection corresponds to
parent - the class the collection belongs to

CollectionItem

public CollectionItem(String name,
                      List path,
                      ClassItem parent)
               throws InvalidDelegateException
Creates a CollectionItem for an expression field.

Parameters:
name - the expression
path - the list of FieldItem the expression is made of
parent - the class the collection belongs to

CollectionItem

public CollectionItem(String name,
                      MethodItem getter,
                      ClassItem parent)
Creates a CollectionItem for a calculated field.

Parameters:
name - the name of the collection
getter - the getter of the calculated collection
parent - the class the collection belongs to
Method Detail

getAddingMethods

public MethodItem[] getAddingMethods()
Gets the method items that access this collection for adding.

Returns:
value of addingMethods.
See Also:
hasAdder()

hasAdder

public boolean hasAdder()
Returns true if the collection has at least one adding method.

See Also:
getAddingMethods()

getAdder

public MethodItem getAdder()
Returns the adder of the collection, or null if it has no adder.


setAdder

public void setAdder(MethodItem adder)
Sets the adder of the collection.

Parameters:
adder - the adder

setAddingMethods

public void setAddingMethods(MethodItem[] addingMethods)
Sets the methods that access this collection for adding.

Parameters:
addingMethods - value to assign to addingMethods.

addAddingMethod

public void addAddingMethod(MethodItem addingMethod)
Adds a new adding method for this field.

Parameters:
addingMethod - the method to add

getCollection

public CollectionItem getCollection()
Returns the actual collection item. In the case of an expression field, this is the last element of the path, otherwise it is the field itself.


getComponentType

public ClassItem getComponentType()
Returns the type of the objects contained in this collection.

Returns:
the type of objects in this collection or null if it is undefined.

setComponentType

public void setComponentType(ClassItem componentType)
Sets the component type of the collection.

Parameters:
componentType - the component type

isAddingMethod

public boolean isAddingMethod(MethodItem method)

addThroughAdder

public final void addThroughAdder(Object substance,
                                  Object value)
Adds an item to the collection, using the adder method if it has one.

Parameters:
substance - object on which to add
value - object to add to the collection

putThroughAdder

public final void putThroughAdder(Object substance,
                                  Object value,
                                  Object key)

getRemovingMethods

public MethodItem[] getRemovingMethods()
Gets the methods that access this collection for removing.

Returns:
value of removingMethods.

hasRemover

public boolean hasRemover()
Returns true if the collection has at least one removing method.

See Also:
getRemovingMethods()

getRemover

public MethodItem getRemover()
Returns the remover of the collection, or null if it has no remover.


setRemover

public void setRemover(MethodItem remover)
Sets the remover of the collection.

Parameters:
remover - the remover

setRemovingMethods

public void setRemovingMethods(MethodItem[] removingMethods)
Sets the methods that access this collection for removing.

Parameters:
removingMethods - value to assign to removingMethods.

addRemovingMethod

public void addRemovingMethod(MethodItem removingMethod)
Adds a new removing method for this field.

Parameters:
removingMethod - the method to add

isRemovingMethod

public boolean isRemovingMethod(MethodItem method)

clearMethods

public void clearMethods()
Clears all the methods that has been set to be removers or adders for this collection item.

Overrides:
clearMethods in class FieldItem
See Also:
addAddingMethod(MethodItem), setAddingMethods(MethodItem[]), MethodItem.removeAddedCollection(CollectionItem), addRemovingMethod(MethodItem), setRemovingMethods(MethodItem[]), MethodItem.removeRemovedCollection(CollectionItem)

clear

public void clear(Object substance)
Clears the collection on the given object.

For maps and collections, it delegates to the clear method. For array, it resets the adding index so that added elements will crush existing ones.

Parameters:
substance - the object where to clean the collection

isArray

public boolean isArray()
Tells if this collection is actually an array.

Returns:
true if an array

getActualCollection

public Collection getActualCollection(Object substance)
Gets the collection object represented by this collection item.

It returns a java.util.Collection representation of the actual collection (i.e. either a Collection, a Map, or an array).

The programmer should rather use the methods that gets the actual collection by using the accessor for this collection if any since it allows possible aspects applications if needed.

Returns:
the actual object collection representation
See Also:
getActualCollectionThroughAccessor(Object), toCollection(Object)

getActualCollectionThroughAccessor

public Collection getActualCollectionThroughAccessor(Object substance)
Gets the collection object represented by this collection item by using the accessor defined in the class containing this collection if any.

Use this method to be sure that all the aspects will be applied to the substance when the collection is retrieved.

It returns a java.util.Collection representation of the actual collection (i.e. either a Collection, a Map, or an array).

Returns:
the actual object collection representation
See Also:
getActualCollection(Object), toCollection(Object)

toCollection

public Collection toCollection(Object value)
A useful method to convert any kind of collection to a java.util.Collection compatible instance.

Supported converted value types are java.util.Collection, java.util.Map, and Java arrays.

Parameters:
value - an object of one of the supported types
Returns:
the collection compliant converted value

add

public void add(Object substance,
                Object newItem,
                Object extraInfos)
Adds an item to the collection.

The extraInfos param must represent a key if the collection is an hastable. If the collection is a java.util collection or if it is an array, the extra informations can be null (in this case, the new item is added at the end of the collection), and they can be not null. In this case, it must be an Integer instance that represents the index of the new item within the collection (must be a list in this case).

Parameters:
substance - the collection where to add the new item
newItem - the item to add
extraInfos - this optional parameter must be used when the collection need some other information when adding a item to it as, for instance the key for a map or the index for a list

removeThroughRemover

public void removeThroughRemover(Object substance,
                                 Object item)
Removes an item from the collection, using the remover method if it has one.

Parameters:
substance - object on which to remove
item - object to remove from the collection

remove

public void remove(Object substance,
                   Object item,
                   Object extraInfos)
Removes an item from the collection.

The extraInfos param must represent a key if the collection is an hastable. If the collection is a java.util collection or if it is an array, the extra informations can be null (in this case, the new item is added at the end of the collection), and they can be not null. In this case, it must be an Integer instance that represents the index of the new item within the collection (must be a list in this case).

Parameters:
substance - the collection where to remove the new item
item - the item to remove (can be null if extra infos are not null)
extraInfos - this optional parameter must be used when the collection need some other information when adding a item to it as, for instance the key for a map, or the index in a list

contains

public boolean contains(Object substance,
                        Object object)
Tells wether an object's collection contains an given object

Parameters:
substance -
object - the object to search
Returns:
true if substance.collection.contains(object)

getMap

public Object getMap(Object substance,
                     Object key)

getMap

protected Map getMap(Object substance)
              throws IllegalAccessException
IllegalAccessException

isList

public boolean isList()
Tells if this collection item is compliant with a java.util.List interface.

Returns:
true if compliant

isMap

public boolean isMap()
Tells if this collection item is compliant with a java.util.Map interface.

Returns:
true if compliant

isIndex

public boolean isIndex()

isSet

public boolean isSet()
Tells if this collection item is compliant with a java.util.Set interface.

Returns:
true if compliant

isPrimitive

public boolean isPrimitive()
Always returns false for collections (maybe not very semantically clear).

Overrides:
isPrimitive in class FieldItem
Returns:
false
See Also:
FieldItem.isReference()

isReference

public boolean isReference()
Always returns false for collections (maybe not very semantically clear).

Overrides:
isReference in class FieldItem
Returns:
false
See Also:
FieldItem.isPrimitive(), FieldItem.isWrappable(Object)

clone

public FieldItem clone(ClassItem parent)
Description copied from class: FieldItem
Copies this field to an other class.

Overrides:
clone in class FieldItem
Parameters:
parent - the class to copy the field to