The profile-binding contract
profile.runtime carries the typed API that every profile binding sits on: ProfileReference,
StereotypeReference, the two tag references, EnumerationReference and the Generated marker. A
plugin author calls it directly, and generated code is written against it, which makes it the one
package here whose signatures a change cannot be reasoned about locally.
This page explains that contract and what guards it. Anvil: use profile bindings states how a plugin author calls the API.
The binding resolves, and holds nothing
Every operation on a StereotypeReference resolves the live Stereotype from the element's own
project and caches nothing. Three properties of CATIA Magic force that.
A binding is a compile-time object, and a Stereotype is a model element belonging to one project. A
cached instance would be wrong the moment a second project opened, and stale the moment a module
reloaded. Resolution is therefore a per-call read from Project.getProject(element), which also
means a binding is safe to declare as a top-level object.
The profile URI is the resolution key, and the profile's name is carried for diagnostics alone. A profile can be renamed, imported under a different label, or shipped twice; the URI is what a project matches. The same reasoning runs one level down for enumeration literals, which are matched on XMI id first and on name second, because an id survives a rename.
Resolution failure is an error naming both halves — the reference and what was missing — rather than
a null. A profile that is not loaded in a project and a stereotype that is not defined in a profile
are two different mistakes, and a binding that answered null for both would push the diagnosis onto
the caller.
The guards state what the Open API does not
The Open API does not block a write to an element that cannot take one, so the binding does. Every
mutating operation runs three checks in a fixed order — disposed, read-only, proxy into an unloaded
module — and applyTo adds a fourth, that the stereotype's metaclass fits the element.
Every mutating operation also asserts an open session first. A model write outside a session fails silently and leaves no undo entry, which is the failure mode a resource author is least equipped to notice, so the assertion converts it into an exception at the call that caused it.
applyTo seeds tagged values through TagDefaults, and it removes now-redundant parent stereotypes
after applying. A tag write goes through setStereotypePropertyValue with setAnotherEnd = true, so
a tag that is one end of a bidirectional association keeps its far end consistent; that argument is
inert on a tag with no association, which is why every write can take it.
The generator lives in Forge
The .mdzip-to-Kotlin generator is not in this repository. Forge runs it from its
generateProfileBindings task during a consuming project's build, and writes the emitted sources into
that consumer's own profile package.
The split is a dependency decision. Forge builds Anvil, so an Anvil that compiled against Forge would
close a cycle. What crosses between them is a source-level contract instead: Forge's
KotlinBindingEmitter writes code against these signatures, and this repository publishes the
signatures that code compiles against.
The consequence is that profile.runtime is a published contract two repositories deep. A signature
change here can compile cleanly, pass every test here, and break the sources Forge emits into every
consumer at their next build.
Main.kt is what puts the runtime where generated code can reach it
The sources Forge emits into a consumer are compiled against profile.runtime, and at run time they
have to find it. They find this installed copy, because Main.kt loads from it.
gradle.properties sets com.mbseconsulting.forge.plugin.ownClassloader=false and
com.mbseconsulting.forge.plugin.classLookup=GlobalFirst, so the jar carrying the plugin entry class
enters CATIA Magic's shared class loader rather than a private one of its own. Once Main loads,
every type beside it in that jar is resolvable by any other plugin in the session.
No line in the class does this. The class installs the diagram image export and nothing more; its
existence is what gets its jar loaded into the shared space at all. A consumer therefore bundles no
copy of profile.runtime, and every consumer in a session resolves the same one.
The marker keeps generated code out of the coverage gate
Emitted code carries @Generated from profile.runtime. JaCoCo 0.8.2 and later drop every class and
method carrying an annotation whose simple name contains "Generated" and whose retention reaches the
class file, so the marker is what keeps generated bindings out of a consumer's coverage report and out
of the coverage gate Forge wires into check. The number that gate reads then measures the code the
consumer wrote.
Both halves of the JaCoCo rule are load-bearing. Renaming the annotation, or retaining it at source
level, disables the filter silently — and in the consumer's build rather than in this repository's
tests. Retention is RUNTIME where BINARY would also satisfy JaCoCo, so that GeneratedTest can
read the retention back off the compiled annotation with getAnnotation instead of parsing bytecode.
Hand-written bindings carry no marker and stay measured. They are the author's code, and the author's tests are what a coverage report is measuring.
The witness fails this build instead of a consumer's
src/test/kotlin/.../witness/EmittedShapeWitness.kt is the guard on the contract. It is the
emitter's verbatim output for a fixture profile, compiled by compileTestKotlin and never executed,
so it carries no @Test. A profile.runtime signature change that the emitted shape depends on
fails this repository's own build, rather than a consumer's generated sources a release later.
Two rules follow from what the file is:
- Re-copy it from the emitter when the emitted shape changes. Never hand-edit it to clear a compile error, because an edited witness still compiles and witnesses nothing.
- Nothing in it is hand-written. Everything from
@file:Generateddown is byte-identical to Forge's golden resource, and Spotless stamps the licence header above that line. ThelicenseHeaderstep stops at the@file:delimiter, so the header needs no hand edit, and the file carries no explanatory comment: the step replaces whatever sits above that delimiter, and this page holds the explanation instead.build.gradle.ktssuppresses one ktlint rule for this path,enum-entry-name-case, which the emitted entries_1,_2and_3break. Every other step runs over the file and leaves the emitter's layout untouched.
Forge holds the other half of the guard. Its EmittedShapeGoldenTest pins that body, byte for byte,
as src/test/resources/golden/EmittedShapeWitness.kt.txt, so an emitter change that alters the
emitted shape fails there first, in Forge's own build. That test compares the emitter's output against
the golden file alone and cannot see this witness, so keeping the two in step once the golden changes
is a manual step: copy the regenerated golden over the witness, then run spotlessApply to stamp the
licence header back on.
Dassault's own profiles take the adapter path
A profile Dassault ships — SysML, MagicDraw, Standard, Validation — generates like any other profile. A dedicated adapter layer over Dassault's own typed wrappers is the intended path for that case instead. Prefer the adapter once it exists, rather than generating bindings for a profile Anvil does not own.
Related
- Anvil: use profile bindings — the API from a caller's side.
- The Forge guide to generating profile bindings owns the generator itself and how a consumer configures it.