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.
You can use the New Property Wizard to create a new relationship property. To invoke this wizard, select
. Alternatively, right-click the Class Inspector and select
. You can also click the New Property
button 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.
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.
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.
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 it is a dependent relationship and this property refers to the parent of this object. 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 by clicking 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 only if the class name you specified on the previous page of the wizard does not exist. Select this option to add the new class 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 only if the property of the referenced class that you specified on the previous page of the wizard does not exist. Select this option to add this new property 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 field is active only if the property of the referenced class already exists. Select this option to modify the referenced property to be a relationship with the property that you are defining.
Define an index for this relationship.
Select to define an index for this property. This is applicable only for One-To-Many relationships; it is disabled for Parent-Child relationships
After creating a new relationship with the New Property wizard, the Class Editor 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.
To open the Modify Relationship wizard:
Display the list of properties in the Class Inspector.
Right-click the desired relationship in the list of properties and select
from the pop-up menu.