Helma logo
helma.org » Home > docs > guide > mapping > Collection Mappings

Collection Mappings

The following section describes the entries used to define collections of objects. There are two kinds of collections: First, every object can itself act as a collection, and second, it can define additional properties to be used as collections. Direct descendents are defined with entries starting with _children, while additional collections are defined using their property name. Otherwise the syntax for the two is the same.

The following are examples for simple collection mappings for both the direct descendants and those contained in a collection-property called prop4. The .foreign entry is used in both cases to specify a column in the foreign table used to collect the objects. Exactly those objects will be collected whose FOREIGN_DB_COLUMN value equals the LOCAL_DB_COLUMN value of the object holding the collection. Leaving away .local and .foreign creates a collection of all available objects of the specified prototype. 

_children = collection (protoype) 
_children.local = LOCAL_DB_COLUMN 
_children.foreign = FOREIGN_DB_COLUMN 

prop4 = collection (protoype) 
prop4.local = LOCAL_DB_COLUMN 
prop4.foreign = FOREIGN_DB_COLUMN
By executing obj.add(otherObj) resp. obj.prop4.add(otherObj), the FOREIGN_DB_COLUMN will be set to the value of LOCAL_DB_COLUMN.

By default, child objects can be accessed from the containing parent object through their index-position or ID value. Additionally the entry .accessname can be used to specify a database column in the child table. The value of this column will be used as name of the objects contained in this collection. 
prop4.accessname = DB_COLUMN
With the above mapping, an object contained in the prop4 collection with a DB_COLUMN value of "xyz" would be reachable as this.prop4.xyz from the containing object.

filter can be used to add an additional condition for the selection of objects which is not dependent on the object holding the collection. order contains the sorting to be applied to the child objects. group tells Helma to group the objects in the collection according to the value in DB_GROUPCOLUMN. 
prop4.filter = DB_FILTERCOLUMN is not null 
prop4.order = DB_ORDERCOLUMN desc 
prop4.group = DB_GROUPCOLUMN 
prop4.group.order = DB_GROUPORDERCOLUMN
prop4.group.prototype = SomePrototype
Notice the two appearences of order above. The first one, prop4.order sorts the objects, the second, prop4.group.order sorts the grouped objects, that Helma will create as a result of the group entry. With this it's also possible to sort the grouped objects ascending, but the contents of the grouped objects descending.

The prop4.group.prototype property sets the Prototype to be used for the group objects generated by Helma.

Filters can contain references to the values of the current object's database entry fields. This is the syntax for these variables: ${FIELD_NAME}. The variables are then replaced by the actual values of the fields before the query is executed.
With these variables, the above collection could also be described like this: 
prop4 = collection (protoype) 
prop4.filter = FOREIGN_DB_COLUMN = ${LOCAL_DB_COLUMN}
filter.additionalTables allows adding additional tables to the query, so that their fields can be used in the condition of the filter as well. The table of the collection's prototype is allways the first table in the query.
Table references can be aliased using TABLE_NAME AS ALIAS_NAME or TABLE_NAME ALIAS_NAME. 
#Node is stored in in the database table NODE

#subChildren is a collection containing all the Node's children's children:
subChildren = collection(Node)
subChildren.filter.additionalTables = NODE AS CHILDREN
subChildren.filter = NODE.FOREIGN_DB_COLUMN = ${LOCAL_DB_COLUMN} AND NODE.LOCAL_DB_COLUMN = CHILDREN.FOREIGN_DB_COLUMN
Another example: Short arrays of objects of which the sequence can be changed without using a position field for each object can be created with the SQL statements ID_FIELD IN (ID_LIST) and FIND_IN_SET(ID_FIELD, ID_LIST), ID_LIST being a string field that contains the IDs seperated by commas. This comes in handy when the objects are used in more than one such array and the objects stored in such a way should know about all their referencing objects. 
#Object1/type.properties

#the id list string containing a comma seperated list of OBJECT2 ids:
strObject2Ids = OBJECT2_IDS

#object2s lists the Object2 objects as referenced by strObject2Ids:
object2s = collection(Object2)
object2s.filter = OBJECT2.ID IN (${OBJECT1.OBJECT2_IDS})

#Object2/type.properties

#object1s lista all Object1 objects that are referencing this Object2 through their object2s collection:
object1s = collection(Object1)
object1s.filter.additionalTables = OBJECT2
object1s.filter = OBJECT2.ID = ${ID} AND FIND_IN_SET(OBJECT2.ID, OBJECT1.OBJECT2_IDS)


Up: Object-Relational Mapping Guide
Previous: Object Reference Mappings Next: Additional Join Conditions

... comment


Page last modified on 2005-11-17 12:12 by hns

 
vividvisions, Wednesday, 27. September 2006, 22:42
Missing:
collection.hints

... link  


... comment
This site is powered by helma