ASSOCIATORS OF Statement

[This is preliminary documentation and subject to change.]

The ASSOCIATORS OF statement supports the traversal of associations programmatically by retrieving all endpoint instances that are associated with a particular source instance.

The syntax of the ASSOCIATORS OF statement is:

associators of {SourceObject} where
    AssocClass = AssocClassName
    ClassDefsOnly
    RequiredAssocQualifier = QualifierName
    RequiredQualifier = QualifierName
    ResultClass = ClassName
    ResultRole = PropertyName
    Role = PropertyName

To specify a source instance, use any valid object path. As with the SELECT statement, the WHERE clause is optional and is used to further define the query. That is, the following statement is perfectly valid:

associators of {Adapter="AHA-294X"}

ASSOCIATORS OF statements that include a WHERE clause use one or more of the predefined keywords: AssocClass, ClassDefsOnly, RequiredAssocQualifiler, RequiredQualifier, ResultClass, ResultRole, or Role.

The AssocClass keyword indicates that the returned endpoints must be associated to the source through the specified class or one of its derived classes. For example, the following statement returns only endpoints that are associated to the source through the AdapterDriver association class or any of its derived classes:

associators of {Adapter="AHA-294X"} where AssocClass=AdapterDriver
 

The ClassDefsOnly keyword indicates that a list of class names is returned rather than actual instances of the classes. These are the classes that the endpoint instances belong to. For example, the following statement returns the Driver and Protocol class names:

associators of {Adapter="AHA-294X"} where ClassDefsOnly

The RequiredAssocQualifier keyword indicates that the returned endpoints must be associated to the source object through an association class that includes the specified qualifier. This type of filtering is used to eliminate broad ranges of endpoints unless they associate to the target through a particular set of tagged association classes. For example, the following statement returns endpoint instances if the association class includes a qualifier called SpecialTag:

associators of {Adapter="AHA-294X"} 
    where RequiredAssocQualifier = SpecialTag

The RequiredQualifier keyword indicates that the returned endpoints associated to the source object must include the specified qualifier. The RequiredQualifier keyword can be used to include particular types of instances in the result set. For example, the following statement returns endpoint instances that include a qualifier called AdapterTag:

associators of {Adapter="AHA-294X"} 
    where RequiredQualifier = AdapterTag
 

The ResultClass keyword indicates that the returned endpoints associated to the source object must belong to or derive from the specified class. For example, the following statement returns endpoint instances that are derived from the SystemDriver class:

associators of {Adapter="AHA-294X"} 
    where ResultClass = SystemDriver
 

The ResultRole keyword indicates that the returned endpoints must play a particular role in their association with the source object. The role is defined by the the specified property and must be a reference property of type ref. For example, the ResultRole keyword can be used to retrieve all endpoints that play the role of child in their association with a source object, as following query illustrates:

associators of {Adapter="AHA-294X"} 
    where ResultRole = child
 

The Role keyword indicates that the returned endpoints participate in an association with the source object where the source object plays a particular role. The role is defined by the the specified property and must be a reference property of type ref. For example, the Role keyword can be used to retrieve all endpoints associated with a source object that plays the child role, as the following query illustrates:

associators of {Adapter="AHA-294X"} 
    where Role = child