TechTalk Genome v4.2

<ManyToManyCollection> Element

Defines the property as a many-to-many collection.

<Member name=" property ">
<ManyToManyCollection [ trackReference="true|false" ] [orderBy="order-by-clause"] >
connection-specification-element
</ManyToManyCollection>
</Member>
property
A property name specifying a property of type Collection<T> , representing a many-to-many association.
connection-specification-element
An element specifying how the many-to-many association is represented in the database. This element can be one of the following: <Explicit> element , <Automatic> element , <Reverse> element .
trackReference
If true or omitted, updates of the parent or child reference properties are tracked to update the appropriate collections automatically. If false, then setting the reference properties does not affect any of the cached collections.
order-by-clause
Specifies the order of the items when enumerating the collection. The order-by-clause uses the same syntax as the OrderBy OQL method.

Remarks

A many-to-many (n:m) association between two persistent classes is typically stored as a separate association table that provides a "parent" and a "child" foreign key to the associated tables. As opposed to one-to-many associations, the role of the "child" and "parent" in the association is arbitrary; not only can a parent object have multiple children, but a child object can also have multiple parents. The same many-to-many association can be abstracted with two collections: the child collection on the parent type and a parent collection on the child type. The domain model can implement both directions of the association or one selected direction as well.

The <ManyToManyCollection> element is used to map the collection of type Collection<T> of a many-to-many (n:m) association to the database. The connection-specification-element specifies the mapping of the association table that connects the associated types.

The <Automatic> element implicitly generates an association class invisible in the object model and an association table for the database. Additional attributes can be applied to explicitly specify the structure of the association table in the database.

If the association type of the many-to-many association should appear in the domain model it has to be mapped as an individual type. In this case, the <Explicit> element has to be used to reference the mapped type in the collection mapping.

If both directions of the many-to-many association are implemented, the detailed mapping of the connection must be specified only once for the association. Hence, one of the two collections has to be mapped as the "reverse" counterpart of the other collection by using the <Reverse> element . Note, however, that this constraint is introduced only to ensure consistency of the mapping. It can be freely decided which collection is mapped as the main direction and which as the reverse direction, because it does not imply any difference in the declaration or behaviour of the collections.

The add and remove operations of the collection are implemented by creating and deleting the association object with the appropriate parent and child references accordingly. When modifying a collection, the appropriate reverse collection is updated automatically in the context as well. Removing an object from the collection only deletes the association, not the object itself. However, if a child or parent object is deleted, it is automatically removed from the collection(s) as well.

If the <Explicit> element is used for a many-to-many association, it is recommended to declare the reference properties as read-only (without a property setter). This approach explicitly expresses on the interface that the association is maintained through the collection. If trackReference is enabled, the updates of the reference are tracked by Genome and the corresponding collections are automatically updated. Reference tracking is enabled by default.

If the order-by-clause is specified for a collection, items are returned in the specified order when enumerating the collection. When populating the collection, Genome retrieves the items in the specified order from the database. Moreover, the order of the items is maintained even if the collection is changed in the context, e.g. when new objects are added to the collection. This process, however, requires client side evaluation of the order clause for the items, so it is advisable to use simple order expressions (e.g. direct persistent fields) in the order clause.

Examples

                      
  <Type name="Cage">

      <Member name="Keepers">
          <ManyToManyCollection>
              <Automatic/>
          </ManyToManyCollection>
      </Member>
      
  </Type>
              

Requirements

Type: TechTalk.Genome.Mapping.ManyToManyCollectionXmlData

Assembly: TechTalk.Genome.dll

Version: 4.2.11

Editions: Professional, Evaluation, Express

Database Platforms: Microsoft SQL Server 2000, Microsoft SQL Server 2005, Oracle 9i Release 2, Oracle 10g Release 2

See Also

<OneToManyCollection> Element | <NearObjectReference> Element | Member Mappings