You can use collection operators in OCL expressions to filter, combine, compare, count, and calculate values from a collection of model objects or values.
A collection is a group of values or objects, such as all Products in a Category or all instances of a class. Collection operators take a collection as input and return a new value, object, or collection. In OCL, this is a transformation: evaluating an expression does not change the underlying data.
Find collection operators in the OCL-Editor
Use the OCL-Editor to inspect the operators available for the collection currently produced by your expression.
- Open the OCL-Editor in the context where you are writing the expression.
- Enter or select an expression that returns a collection. For example, start from an association that contains many objects, such as
self.Products. - Inspect the operators offered for that collection type.
- Select an operator and continue the expression. The available operators depend on the type of values in the collection.
For example, if self.Products is a collection of Product objects, you can use collection operations to select Products by a condition or derive a value from their attributes. If an expression produces strings, numbers, dates, or Booleans instead, the editor exposes operations for that resulting simple type.
For the complete operator reference, see Documentation:OCLOperators. For operators that apply beyond collections, see Documentation:OCL General Operators.
What you can do with a collection
Collection operators support common query and calculation tasks. The exact operators and result types are shown by the OCL-Editor for the expression you are editing.
| Goal | Example scenario | Result |
|---|---|---|
| Filter objects | Find Products in a Category whose Price is greater than 1000. | A collection containing only the matching Products. |
| Calculate from values | Calculate the total of product prices in a Category. | A numeric value derived from the collection. |
| Compare collections | Compare two collections to find objects present in one but not the other. | A collection representing the difference. |
| Test a collection | Determine whether two collections contain the same objects. | Compare their symmetric difference with an empty collection. |
| Provide an empty typed result | Return no Customer objects from one branch of conditional logic while another branch returns Customers. | An empty collection whose element type is Customer. |
See Documentation:Examples on collection operators for worked collection expressions and Documentation:Collections for collection concepts and further examples.
Common collection operators include:
| Operators | Description |
|---|---|
| ->append | Add another object last |
| ->asBag | Returns a Bag containing all elements of self. |
| ->asSequence | Returns a Sequence containing all elements of self. Element ordering is preserved when possible. |
| ->asSet | Returns a Set containing all elements of self. |
| ->at | Get the objects at X where the first index is 1 |
| ->at0 | Get the objects at X where the first index is 0 |
| ->collect | Returns a collection containing the result of applying expr on all elements contained in self. |
| ->count | Count how many meet a certain criteria |
| ->dictionary | Efficiently looks up values |
| ->difference | The difference between 2 collections |
| ->excluding | The collection except for this single object |
| ->exists | Returns true if at least one element in self validates the condition expr, false otherwise. |
| ->filterOnType | Only keep the ones of a certain type |
| ->first | Return the first object |
| ->forAll | Returns true if all the elements contained in self validate the condition expr, false otherwise. |
| ->groupBy | Build a collection of tuples grouped by some aspect |
| ->includes | Does the collection include the object |
| ->includesAll | Does the collection include the whole other collection |
| ->including | Returns the list with the element in the parameter included. |
| ->IndexOf | The 1 based index of an object in the collection possibly -1 if not existing |
| ->indexOf0 | The 0 based index of an object in the collection possibly -1 if not existing |
| ->intersection | The intersection of two collections |
| ->isEmpty | Returns true if the collection is empty |
| ->notEmpty | Returns true if self contains at least one element, false otherwise. |
| ->reject | Returns a collection with all elements of self except for those who validate the OclExpression expr. |
| ->select | Returns a collection with all elements of self that validate the OclExpression expr. |
| ->size | Returns the number of elements contained in self. |
| ->sum | Returns the sum of all elements contained in self if they support the '+' operation. |
| ->last | Returns the last object in the collection |
| ->orderBy | Sorts the collection on one or more properties |
| ->orderDescending | Sort the from biggest to smallest |
| ->orderGeneric | Sorts the list of properties with interchangeable sort order: (expr1, OclSortDirection::ascending, expr2, OclSortDirection::descending...) |
| ->prepend | Returns an OrderedSet containing object followed by all elements of self. |
| ->subsequence | Returns a smaller collection from a start to stop |
| ->symmetricDifference | The symmetric difference between the collections; ie all the objects in collection1 or collection2 but not in both |
| ->union | The set of objects in collection1 and objects in collection2 |
See this page for examples on collection operators.
Collection results are flattened
When an expression navigates from a collection through an association, MDriven expands the individual results into one collection rather than returning a collection of collections. This reduction of nested collection structure is called flattening.
For example, if every Thing has a collection of Details, the expression Thing.allinstances.Details returns one set containing the Details from all Things. It does not return one separate Details collection for each Thing.
This matters when you navigate across a to-many association: you can continue to work with the combined result using collection operators.
Use the right expression context
OCL is functional: it takes input and produces a result without changing data. Use it for queries, derivations, constraints, and values displayed in a ViewModel.
For example, an OCL expression can select Products with a price above a threshold or calculate a total. It does not add or remove association links.
If you need to change class-object collections, such as adding Products to a Category association, perform that work in the Action Editor using mutable class-object collections. This distinction is important: raw-data collections are immutable in expressions, while class-object collections can be changed in the Action Editor.
Empty and comparison results
OCL is strongly typed, including when a collection has no elements. Use emptyList when you need an empty collection of a specific class type. For example, Customer.emptyList is an empty collection that remains known as a Customer collection, so later collection operations can use it safely.
To identify objects that occur in one of two collections but not both, use symmetricDifference. A practical equality check is to evaluate the symmetric difference of two collections: if the result is empty, the collections contain the same objects.
Learn by evaluating live data
Evaluate expressions against sample data in the debugger to see both the value and type returned at each step. Start with a collection, apply one operator, and inspect the result before extending the expression. This makes it easier to distinguish an object collection from a scalar result such as a number or Boolean.
For a live walkthrough of finding and testing collection operators, watch OCL Operators, explained with live data in MDriven.