A relationship is a special type of property that defines how two or more object instances are associated with each other. For example, a Company
class that represents a company could have a one-to-many relationship with an Employee
class that represents an employee (that is, each company may have one or more employees while each employee is associated with a specific company).
A relationship differs from a property in that every relationship is two-sided: for every relationship definition there is a corresponding inverse relationship that defines the other side.
You can add a new relationship to a class definition in two ways:
Adding a relationship to the class definition using the Class Editor.
Using the New Property wizard
To add a relationship using the Class Editor, position the cursor on a blank line in the Class Editor and enter a relationship declaration:
Class MyApp.Company Extends %Persistent
Relationship TheEmployees As Employee [cardinality=many, inverse=TheCompany];
A relationship definition must specify values for both the cardinality and inverse keywords.
As this relationship has two sides, also enter the inverse relationship in the class definition of Employee
Class MyApp.Employee Extends %Persistent
Relationship TheCompany As Company [cardinality=one, inverse=TheEmployees];
If the two sides of the relationship do not correctly correspond to each other, there are errors when you try to compile.
New Property Wizard to Create a Relationship Property
You can use the New Property Wizard
to create a new relationship property. To invoke this wizard, use
. Alternatively, right-click the Class Inspector and select
or select New Property
on the toolbar.
The New Property wizard prompts you for information. The procedure is identical to creating a new, non-relationship property except that you specify Relationship
on the property type.
Name and Description Page
The New Property wizard prompts you for the following information (you can later modify any of these values):
(required) Name of the relationship. This name must be a valid relationship (property) name and must not conflict with the name of a previously defined relationship or property.
(optional) Description of the new relationship. This description is used when the class' documentation is displayed in the online class library documentation.
A description may include HTML formatting tags. For more details see Using HTML in Descriptions
in the Class Definition Language reference.
The New Property wizard asks you to choose from a variety of property types. Choose Relationship
and enter the name of the class on the inverse side of the relationship.
Relationship Characteristics Page
The New Property wizard asks for additional relationship characteristics. These include:
This relationship property refers to a single instance of the related object. The resulting property acts like a simple reference field.
This relationship property refers to a one or more instances of the related object. The resulting property acts like a collection of objects.
Parent: this object's parent
Identical to cardinality of one
except that this is a dependent relationship and this property refers to the parent of this object. Note: When you create a parent-child relationship, you are not given the option to create an index because children aren't stored independently but within the parent; you can see that by looking at the global structure. The children are indexed automatically by creating an extra subscript.
Children: the object's children
Identical to cardinality of many
except that this is a dependent relationship and this property refers to a collection of child objects.
This relationship property references objects of the following type
Select a class from the Browse button or enter a new class name for the inverse side of the relationship.
The name of the corresponding property in the referenced class
Select a property from the class or enter a new property name for the inverse side of the relationship.
Select any of the additional changes that you would like to implement:
Create a new class <inverse class>
This field is active if you entered a class name that does not exist for the inverse relationship on the last screenSelect this to create the class in this package. The new class is added to the package. You must compile the new class before you can compile the class that contains the relationship.
Create a new property Parent
in class <inverse class>
This field is active if you entered a property that does not exist for the inverse relationship on the last screenSelect this to create the property in the package and class named in the last screen. The new property is added to the class. You must compile the class with this new property before you can compile the class that contains the relationship.
Modify property Parent
of class <inverse class>
This property is active if you entered a property that already exists for the inverse relationship on the last screenSelect this to modify that property to be a relationship with this property.
Define an index for this relationship.
Check to define an index for this property. This is applicable only for One-To-Many relationships; it is disabled for Parent-Child relationships
Results of Creating a New Relationship with the New Property Wizard
After creating a new relationship with the New Property wizard, the Class Editor window is updated to include the new relationship definition. For example:
/// This is an Employee class
class MyApp.Employee extends %Persistent
/// We have a one-to-many relationship with Company
Relationship Company As Company [cardinality=one, inverse=Employees];
If you want to make further modifications to this relationship, you can do this using either the Class Editor or the Class Inspector.
Additionally you can use the Modify Relationship wizard, which has the advantage of automatically determining the changes required to the inverse of a relationship.
You can invoke the Modify Relationship wizard by following these steps:
Display the list of properties in the Class Inspector
Right-click the desired relationship in the list of properties and select
command from the pop-up menu.