Component Collections Support

This section explains and gives a practical example of how support of component collections is implemented in Entity Developer for NHibernate.

This section contains examples of mapping for the following associations:

•	Classic mapping of component collections;

•	A special case of component collections mapping for a many-to-many association.

Classic mapping of component collections:

Classic mapping of component collections is pretty much alike mapping of a one-to-many association between two entities of a model. The major difference is that the model does not have an entity corresponding to a details table, and instead of it the model contains a complex type consisting of a set of properties similar to a part of the details table field set. Whereas an association is built between an entity corresponding to a master table, and a complex type corresponding to a part of the details table field set. The master entity contains a navigation property which is a reference to a collection of complex type details.

Within the database, one-to-many mapping is arranged as a table with a primary key for the one side of mapping, and a table containing a field which references the primary key of the master table, for the other side.

Example:

The database contains the Dept and Emp tables, which have a foreign key constraint between them.

The DEPTNO field in the Emp table receives the ID value of the associated record in the Dept table.

images_collections-db-diagram

We perform the following sequence of operations:

•	create a NHibernate model;

•	add the Dept and Emp tables to the model;

•	select a part of Emp entity properties (e.g. the properties ENAME, JOB, MGR), and by dragging and dropping detach them into a separate complex type, call it PartialEmpType, and then delete the Emp entity;

•	after that we add an association between the Dept master entity and the PartialEmpType details complex type and customize it as displayed in the screenshot below:

images_collections-association-dialog

In the Association Editor dialog box, besides the regular parameters of a one-to-many association like collection type, navigation properties names etc., in the Join Table input field the details table name is specified, and in the Schema field the name of the schema it exists in, is entered. In the dialog box in is necessary to set the name of the foreign key column of the details table, which references the primary key of the master table.

This dialog box also makes it possible to define private mapping for the details complex type properties to the details table fields, if this association mapping is different from general mapping of complex type properties.

By default for this association type for End 1 of the navigation property the Generate related property check box is off, but if you set it, the parent reference to the master entity will become available for the details complex type.

As a result, we have the following model:

images_collections-data-model

Note

If you define collection type of a navigation property as Set, it is very important to implement Equals() and GetHashCode() correctly for classes corresponding to model complex types. To generate these methods with an Entity Developer template, select the template node in the object tree of the Model Explorer tool window, select the Implement Equals template property in the Properties tool window and set it to True.

The property is generated in the master entity class, containing a reference to the collection of instances of the details complex type class.

Mapping of component collections for a many-to-many association:

Many-to-many associations use an intermediate table that has a foreign key to tables of both associated entities. An object uses several objects of another type, and one of these latter objects refers several objects of the first type. As is always the case for many-to-many mappings in relational databases, we need the third table which provides references for a many-to-many relationship. Mapping like this allows you to map extra columns of a many-to-many association join table to a complex type.

Example:

The database contains the Employees, Territories and EmployeeTerritories tables, the last one provides references for the many-to-many relationship. The EmployeeTerritories table contains 1 extra column, which is EmployeeTerritoriesDescription.

images_collections-MtoM-db-diagram

We perform the following sequence of operations:

•	create a NHibernate model;

•	add the Employees, Territories, and EmployeeTerritories tables;

•	select the EmployeeTerritoriesDescription property of the EmployeeTerritories entity and by dragging and dropping detach it into a separate complex type, call it ‘EmployeeTerritoriesExtra’, delete the EmployeeTerritorу entity;

•	then we add a many-to-many association between the Employee and Territory entities and customize it as displayed in the screenshot:

images_collections-MtoM-association-dialog

In the Association Editor dialog box, besides the regular parameters of a many-to-many association, such as collection type, navigation properties names, etc., in the Join Table input field the join table name providing references for the many-to-many relationship is specified, and in the Schema field the name of the schema it exists in, is entered. In the dialog box it is necessary to set the name of the foreign key column of the join table, which provides references for the many-to-many relationship. To specify mapping for the join table extra fields for a many-to-many association, in the Component field of the Association Editor dialog box set the required complex type, containing the set of properties corresponding to the set of the join table extra fields. This dialog box also makes it possible to define private mapping for complex type properties to join table extra fields, if this association mapping is different from general mapping of complex type properties.

As a result we have the following model:

images_collections-MtoM-data-model

Note

If you define collection type of the navigation property as Set, it is very important to implement Equals() and GetHashCode() correctly for classes corresponding to model complex types. To generate these methods with an Entity Developer template, select the template node in the object tree of the Model Explorer tool window, select Implement Equals template property in the Properties tool window and set it to True.

In classes corresponding to entities connected with a many-to-many association, the property is generated containing a reference to the class collection for the complex type, consisting in its turn of a set of properties, corresponding to the set of the join table extra fields. Again, in the complex type class, references are generated to classes corresponding to entities connected with a many-to-many association. Therefore, when a many-to-many association is organized in such a way, we have a possibility to access both values of join table extra columns, by means of referring to complex type fields themselves, and instances of relation classes by referring to the respective complex type reference field.

Component Collections Support

Example:

Example:

See Also