You can retrieve one object from a many-valued association by supplying a qualifier in brackets; use this when you want the association end to behave as a keyed lookup in OCL or EAL.
What is a qualified association?
A qualified association is a many end of an association that you access with one or more qualifier values. Instead of navigating to the full collection, you place the qualifier arguments in brackets after the association name.
SomeObject.SomeManyObjectsAssociation[someQualifier1, someQualifier2]The expression returns one object of the many association's element type. For example, if ThingWithQualifyTest is a many association end containing Thing objects, this expression requests one Thing:
self.ThingWithQualifyTest['A-100']Use qualification when the qualifier identifies the object you need. If you need to work with all associated objects, navigate the association end without brackets instead.
How MDriven resolves a qualifier
When you use brackets on a many association end, MDriven looks on the source object for a method with this naming pattern:
Qualify_<SomeManyObjectsAssociation>(someQualifier1, someQualifier2):ObjectType
Replace:
<SomeManyObjectsAssociation>with the exact association-end name.someQualifier1, someQualifier2with the qualifier parameters that your lookup needs.ObjectTypewith the element type of the many association.
For example, an association end named ThingWithQualifyTest whose element type is Thing can use this method on NewClassAddedNow:
Qualify_ThingWithQualifyTest(someQualifier:String):Thing
The qualifier expression passes its bracket argument to this method. The method decides which associated object to return.
Create a custom qualifier
- In MDriven Designer, identify the source class that owns the many association end. In this example, the source class is
NewClassAddedNow. - Identify the exact name of the many association end. In this example, it is
ThingWithQualifyTest. - Add a method to the source class named
Qualify_ThingWithQualifyTest. - Add parameters in the same order and with the types you want to use in the bracket expression.
- Set the return type to the association element type,
Thingin this example. - Define the method body in EAL, or implement it in C#.
- If you will call the qualified association from OCL, set the method's
IsQueryproperty totrue.
Example: look up a Thing by Attribute1
The following EAL body searches the associated Thing objects for an object whose Attribute1 equals the supplied string, then returns the first match:
self.ThingWithQualifyTest->select(a|a.Attribute1=someQualifier)->first
With that method in place, use the association end with a qualifier:
self.ThingWithQualifyTest[someQualifier]For a concrete value, the lookup can be written as:
self.ThingWithQualifyTest['Blue']This invokes Qualify_ThingWithQualifyTest with someQualifier set to 'Blue'. The method then selects associated objects where Attribute1 is 'Blue' and returns the first one.
Multiple qualifier arguments
A qualifier can contain more than one argument. Add matching parameters to the qualifier method in the same order as the bracket arguments.
Qualify_ThingWithQualifyTest(someQualifier1:String, someQualifier2:String):Thing
Call it with both values:
self.ThingWithQualifyTest[someQualifier1, someQualifier2]Default integer qualification
If MDriven cannot find a matching Qualify_<AssociationEnd> method, it uses a generic qualifier operator that accepts an integer. The result corresponds to the at0 operator.
Use a custom qualifier method when an integer position is not the lookup you need, such as when you want to find an associated object by an attribute value.
OCL requirement
To use the qualifier operator in OCL, mark the Qualify_<AssociationEnd> method as IsQuery=true.
Without IsQuery=true, the qualifier method is available only in EAL, not through the OCL qualifier expression. Check this setting before troubleshooting an expression such as self.ThingWithQualifyTest['Blue'].