Using Caché Studio
Adding Relationships to a Class
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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 the chapter Relationships in Using Caché Objects.
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, use Class > Add > Property. Alternatively, right-click the Class Inspector and select Add Property 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):
Property Name
(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.
For a general discussion on names see the chapter Caché Classes in Using Caché Objects.
Description
(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.
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:
Cardinality
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 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.
Inverse:
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.
Additional Changes
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:
  1. Display the list of properties in the Class Inspector
  2. Right-click the desired relationship in the list of properties and select Add/Modify Relationship command from the pop-up menu.