Domain Relationships

A domain relationship specifies a relationship between two domain classes. There are two basic kinds of domain relationships, embedding relationships and reference relationships. However, the designer of a domain-specific language can create many other kinds of relationships by using these two basic kinds.

Embedding Relationships

An embedding relationship is a containment relationship. If one domain class is embedded in another domain class, the first domain class is a child of the second domain class. An embedded element appears under its parent in the DSL Explorer in the generated model and in the XML representation of the model. By default, embedded elements are automatically deleted when their parents are deleted. An embedding relationship is displayed as a solid line in the DSL Definition diagram.

Every run-time element in a model, except the root element, must be the target of exactly one embedding relationship, so that all the elements in the model form a tree. There must be exactly one root element in a model. Therefore you must follow these restrictions when you create an embedding relationship:

• Every class except the root class must be the child of at least one embedding relationship.

• The parent role of the embedding relationship must have a maximum multiplicity of 1. This requirement ensures that instances of the target domain class cannot be contained by more than one instance of the source domain class.

• If a domain class is the target of more than one embedding relationship, each target role must have a multiplicity of 0..1 or 0..*. This requirement ensures that instances of the child class are not forced to have more than one parent.

For more information, see "Roles" and "Multiplicities" later in this topic.

Reference Relationships

A reference relationship is a general relationship between two domain classes. A reference relationship is displayed as a dashed line on the DSL Definition diagram.

Roles

Every domain relationship has two roles, a source role and a target role.

In the following picture, the line between the left Person domain class and the ParentRelation domain relationship is the source role. Similarly, the line between the ParentRelation domain relationship and the right Person domain class is the target role.

You can click either of the role lines to see the properties of the role in the Properties window.

In the code that is generated from a relationship, there is a class for each domain relationship. Each instance of the relationship connects two instances of domain classes, or connects an instance to itself. The Name of a role is the name of a property of the relationship. If you have an instance of the relationship, you can navigate from it to the instance of the domain class. For example:

ParentRelation relationship = ...;
Person  p =  relationship.Parent;
Person c = relationship.Child;

Each role also defines a PropertyName. In the generated code, the PropertyName becomes the name of a property of t domain class at that role. If you have an instance of the domain class, you can use the PropertyName to navigate to the opposite end of the relationship. If the multiplicity of the role is greater than 1, the property will be a collection:

Person person = ...;
foreach (Person p in person.Parent) { ...}
foreach (Person c in person.Child) {...}

The DisplayName property of a role is used in the DSL Explorer to show relationships between elements. By default, the value of the DisplayName property is the same as that of the Name property unless the value of the Name property is camel-cased. In such a case, the string is separated into multiple words when it is displayed. For example, a Name property that has the value NameTextExample has the DisplayName value Name Text Example.

Multiplicities

Multiplicities specify how many elements can have the same role in a domain relationship. For example, in the picture, the zero-to-many (0..*) multiplicity setting on the Parent role specifies that any instance of the Person domain class can have as many ParentRelation relationship instances as you want to give it. A multiplicity of one (1..1) on a role specifies that each instance of the domain class must have exactly one instance of the relationship.

Configure the multiplicity of a role by modifying the Multiplicity property in the Properties window. The following table describes the settings for this property.

In most cases, the number of relationships that are connected to a given element is the same as the number of elements that are connected through those relationships. However, to allow a single pair of elements to be connected by more than one instance of a domain relationship, you can set the AllowDuplicates property of the relationship. This can be useful if the domain relationship has its own properties.

See Also

Concepts

Domain Relationships in the Generated API

Change History