How query operations work
A framework accumulates queries it asks of the model over and over. Written as structured
expressions inside a .mdzip, each one costs three things: no reviewer reads a change to it, no
Kotlin caller can invoke it, and nothing proves it correct. Anvil answers all three by making the
Kotlin function the deliverable and the model behavior a binding to it.
The tool already works this way
CATIA Magic answers the same question for itself. UML Standard Profile::MagicDraw Profile::Built-In Operations holds forty-five OpaqueBehaviors whose language is Binary and whose body names a
Java class — the behavior's own name rarely matches it. Find's body names the class Find, but
Filter, Map, Union and IsEmpty bind to CollectionFilter, CollectionMap, CollectionUnion
and CollectionIsEmpty. Every structured expression a modeller authors composes those binaries.
SysML Profile ships two more of its own, genuinely under a Built-in Operations package of its own;
MagicGrid Profile's five OpaqueBehaviors sit elsewhere, under `MagicGrid Profile::Constraints::ValSuite
- Requirements`, backing that profile's validation rules rather than composable expressions.
Anvil's operations sit in the same slot, with Groovy in place of Binary.
The two halves
The Kotlin function is the deliverable. It is reviewed in a diff, covered by a test, versioned with the library, and called directly by any plugin. The OpaqueBehavior is a one-line binding:
language: Groovy
body: com.mbseconsulting.anvil.query.AnvilQueries.derivedPropertyValue(element, feature)Nothing else is required. All plugins and their runtime libraries load in one classloader unless a descriptor declares its own, and neither Anvil nor the plugin carrying Groovy declares one, so Anvil's classes are visible to a script with no registration and no configuration.
@file:JvmName("AnvilQueries") is what makes the body's target stable, and
@file:JvmMultifileClass is what lets more than one file share it. Without the first, a file class is
named after its file; without the second, two files claiming the same JVM name fail to compile.
A function's receiver type also settles a choice on the Open API side. ProjectUtilities, for
instance, overloads isElementInAttachedProject on the legacy ModelElement as well as on
Element; an operation declared against Element selects that overload, and Kotlin fails to compile
rather than choosing silently should the two ever stop being unambiguous.
Two unit tests hold the halves together. Both read the .mdzip as a zip and parse its XMI, so
neither opens a project nor needs the tool installed. GroovyBodyShapeTest asserts that every body is a
single call in Groovy, which enforces "a call, never logic" mechanically rather than by review.
BindingResolutionTest asserts that every class, method and parameter a body names exists, which
turns a Kotlin rename that misses the library into a failing build here rather than a broken session
in a consumer's model.
A third piece produces the OpaqueBehavior those two tests read. tools/model-library/add_behavior.py
appends one to the archive offline, minting its xmi:id in the format CATIA Magic mints its own. It
reads the archive's own session hash and continues its sequence number past the archive's current
highest value, which rules out a collision with any id already in this archive; across a future
CATIA Magic session touching the same archive, the guarantee rests on the hash, millis and rand6
segments instead, the same odds the tool itself relies on. The guards then confirm what it wrote:
that the XMI parses, and that the class, method and parameters the body names exist. They cannot
confirm CATIA Magic's own expression editor accepts the result, because nothing outside the tool
exercises the tool — that check still runs by hand, once per batch, before a consumer relies on what
the archive now holds.
The additive-only contract
An expression references a behavior by element ID. Deleting a behavior and recreating it produces a new ID, and every downstream expression then resolves to nothing — no error, no annotation, an empty result. The library is therefore append-only:
| Change | Safe |
|---|---|
| Adding a behavior | yes |
| Renaming a behavior | yes — the name is not the reference |
| Editing a body or its documentation | yes |
| Superseding a behavior with a differently named neighbour | yes |
| Deleting a behavior | no |
| Reordering its parameters | no — the parameter list is matched positionally |
This contract outlives any operation shipped under it, which is why it constrains the library rather than any one behavior.
What ships, and when
The library is a candidate pool rather than a work list. The editor discovers operations from every
OpaqueBehavior in a project and its usages, so a consumer sees a behavior only once their project uses
the Anvil_Queries module — from then on, every behavior already in the library appears in that
consumer's editor list forever, so each one is admitted on demand, when a caller needs it. Three
families never enter: element creation, which the element factory owns; mutators, which belong to a
plugin; and library self-tooling, which an IDE answers once the logic is Kotlin.
When a binding earns a compiled implementation
A Groovy body dispatches through a script engine. Where that cost is measured and matters — an operation inside a derived property evaluated across a large model is the likely first case — the same function gains a compiled binding. Measurement is the trigger; nothing is escalated on suspicion.
Escalation changes two fields on the existing behavior, language to Binary and body to a class
name, and adds an adapter class implementing ParameterizedExpression plus one
registerBinaryImplementers call in Main.init(). The element keeps its ID, so no downstream
expression notices. Those two field changes are not a drop-in replacement for the existing guards,
though: they fail GroovyBodyShapeTest's every binding is Groovy outright, and a bare class name has
no parentheses to parse as a call, so it fails that same test's every body is a single call and
BindingResolutionTest's checkNotNull(singleCall(...)) as well. Escalating a binding is therefore a
guard change, not just a model edit — expect a red build until the guards are updated alongside it. The
compiler checks neither the adapter's arity nor its parameter types, because the engine matches
getValue reflectively against the behavior's parameter list — so a Binary binding needs a signature
test that a Groovy binding does not.
Why no listener configuration
An expression node that navigates the model can tell the engine which changes invalidate its result.
The tool's own code draws the line by what an operation touches. Filter and Map extend
CollectionAsResultOperation directly, Union reaches the same base through
CollectionBinaryOperation, and IsEmpty arrives at the same position by its own route, extending
AbstractExpressionSourceTraceContainer and implementing ParameterizedExpression itself rather
than through that base. All four implement ParameterizedExpression alone, with no configuration
provider, because each transforms a collection handed to it and the metachain node upstream carries
the configuration. StructureDecompositionExpression and ImpliedRelation navigate from an element
themselves, and both implement a configuration provider.
Anvil's operations navigate, so they fall on the second side of that line — but only where something caches their result. A Kotlin call site has nothing to invalidate, a one-shot expression evaluation has nothing to invalidate, and a Groovy body offers nowhere to declare a provider at all. The configuration earns its cost when an operation is composed into a derived property, a smart package, an active validation rule or a dependency matrix, and that case is a reason to escalate the binding to Binary and give the class a provider.
Related pages
contributing/add-a-query-operation.mdin the repository — the steps for adding one- What the metamodel does not tell you — where the Open API's declared shape and the tool's behaviour part company, and which reading an operation follows
- The profile-binding contract — the other published contract this repository holds across a repository boundary