Anvil
Explanation

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:

ChangeSafe
Adding a behavioryes
Renaming a behavioryes — the name is not the reference
Editing a body or its documentationyes
Superseding a behavior with a differently named neighbouryes
Deleting a behaviorno
Reordering its parametersno — 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.

  • contributing/add-a-query-operation.md in 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

On this page