Adding Relationships to a Class
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.
For more information on relationships, see Relationships.
You can add a new relationship to a class definition in two ways:
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, select Class > Add > Property. Alternatively, right-click the Class Inspector and select Add > New Property. 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.
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.
See Rules and Guidelines for Identifiers.
(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. See Creating Class Documentation in Defining and Using Classes.
Property Type Page
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:
One: one other object
This relationship property refers to a single instance of the related object. The resulting property acts like a simple reference field.
Many: many other objects
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
Results of Creating a New Relationship with the New Property Wizard
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 Add/Modify Relationship from the pop-up menu.