How auto-stereotyping works
A modeller draws ordinary UML, and a rule applies the stereotype the model already implies. That keeps a resource's method holding without anyone remembering to apply a stereotype by hand, and it is the one part of Anvil a resource extends rather than calls.
This page explains why the engine is shaped the way it is. Anvil: write an auto-stereotype rule states the contract a rule author writes against; the two describe the same machine from opposite ends.
What one engine holds
A resource declares one AutoStereotypeRuleSet and holds one AutoStereotypeEngine over it. The
rule set carries the identity that every registration below derives from — the options group, the
profile URI, the logger and the list of rules — so the resource states that identity once.
| The engine holds | Which does |
|---|---|
AutoStereotypeOptions | Reads a rule's switch from a project |
AutoStereotypeOptionsConfigurator | Declares one switch per rule in the Project Options dialog |
RuleSuspension | Holds the code-side gate, per thread |
ModelEventTrace | Traces every commit, annotated with each rule's verdict |
CommitListenerInstaller | Attaches one AutoStereotypeListener per open project |
The rules list is the one place a rule is named. The listener reads it to evaluate every rule
against every committed transaction, and the configurator reads the same list to declare the
switches. A rule therefore cannot reach a model without a switch, and a switch cannot exist without a
rule.
Installing is the whole registration
install() declares the options group, installs the trace and attaches the rule listeners.
uninstall() undoes each of those in reverse order. Both are idempotent, and on install that
guard carries weight rather than being defensive.
ProjectOptions.addConfigurator appends to a static list, and removeConfigurator takes one
occurrence off it. An engine that installed twice would leave one configurator behind that a single
uninstall() could not take back, and that survivor would configure every project the installation
opens afterwards, against unloaded classes. Every removal in the Open API looks its argument up by
identity, which is why the engine holds each registration in a field.
A transaction manager belongs to a project rather than to the application, so there is nothing to
attach a rule listener to until a project opens — which is also what Plugin.init() requires, since
it runs before any project exists. CommitListenerInstaller covers that lifecycle for both the rules
and the trace.
The rules listen on the commit channel
The listener registers on addTransactionCommitListener, and recorded event traces decided that
rather than the JavaDoc. The ForExecute channel misses transactions driven from code rather than
from a command — the tool's own scaffolding, a script, another plugin — so a rule registered there
would hold only for edits a user made by hand. The IncludingUndoAndRedo channel fires while the
user is undoing, where re-applying a stereotype fights the undo it is riding on.
The trace registers on all three and stamps each block with its channel, so that reading is repeatable rather than a decision fixed once. See Anvil: trace model events.
Planning reads and the Runnable writes
A commit listener is notified with a batch of events and returns a Runnable, which the tool runs
once every listener has been notified. The engine plans during the notification, which only reads,
and applies from the Runnable. The writes then join the committing session, so one user action
stays one undo step, and the read phase costs nothing beyond the reads a decision needs.
A rule is written against the batch rather than against a single event, for a reason the traces show. The same condition can turn true on the event that sets a Property's type, on the event that moves the element to a new owner, or on both inside one transaction. Naming one trigger event would miss the others.
The listener opens a session only when none is already active. The tool normally runs the Runnable
while the committing session is still open, and joining that session is what keeps the stereotype in
the same undo step as the edit that earned it. A session the listener did not create is left to
whoever created it.
Where the listener does create one, it releases it from a finally and calls exactly one of
closeSession or cancelSession. A catch on RuntimeException would not reach the failure this
domain actually produces: a NoClassDefFoundError, raised when a module is unloaded while a
transaction commits. An Error unwinding past an open session leaves the undo stack corrupted and
every later edit blocked, which is worse than a stereotype that was missed.
Three gates, in order
A rule passes three gates before it writes, and they are held by different parties.
| Gate | Held by | Scope | Persists |
|---|---|---|---|
RuleSuspension | The resource's own code | One engine, one thread | Nothing in the model |
| Profile presence | The project's used profiles | One project | In the model |
| Project Options switch | The modeller | One project | In the model |
AutoStereotypeListener.plan consults them in that order. The suspension comes first, so a suspended
plan reads no model state at all. The profile comes next: a project that does not use the profile the
rule set's profileUri names can hold none of the resource's stereotypes, so no rule of the set
could match there and every switch below is beside the point. Neither gate turns anything on — a rule
the modeller switched off stays off in a project carrying the profile.
The suspension is scoped to the calling thread because the commit listener runs inside closeSession
on the thread that closes the session. That scope is what leaves a modeller's own edit stereotyped
while a background automation runs suspended. It also sets the requirement no code here can enforce —
the automation's session must close inside the suspended region — which is why
AutoStereotypeEngine.withRulesSuspended and suspendRules both document it, and why the rule
how-to repeats it.
The state is a nesting depth rather than a flag, so a helper that suspends inside an automation that
already suspended returns to a suspended state. An exit with no region open is clamped at zero and
reported: a counter allowed to go negative would arm a later enter that then did nothing, and the
automation that owned the imbalance would run quietly while a different one failed.
The ThreadLocal entry backing the depth is removed once it returns to zero, rather than left at
zero. CATIA Magic runs background work on pooled threads, and an entry left behind would outlive the
automation that created it, on a thread the pool later hands to unrelated work.
The switch belongs to the model
Whether a model follows a resource's method is a property of the model rather than of the workstation that opens it. Each rule is therefore switched from the project options, so an MBSE lead sets it once and every team member inherits it, on Teamwork Cloud as well as locally.
The configurator does its work in configure, which the Open API documents as establishing default
values, rather than in configureLoadedOptions, which sets real ones. Declaring a default must not
mark a project modified, because a resource that dirties every project it opens is unusable. A
property is created only when it is absent, so a project already carrying the modeller's choice keeps
it.
The group is declared with a predicate on the rule set's profile URI. A project that does not carry the resource's profile can hold none of its stereotypes, so no rule of it could fire there and the group stays out of that project's dialog.
The switch is read fresh on every transaction rather than cached, so a modeller who flips it mid-session is obeyed from the next edit. The read takes the listener's own project as a parameter rather than asking for the active project, because with two projects open a transaction committing in the background one would otherwise read the foreground one's setting.
Two silences read differently. A project that has never been asked carries no property, and
AutoStereotypeRuleSet.defaultEnabled decides what a rule does there. A read that throws says nothing
about the modeller's choice, so it answers false and the rule stays silent until the setting can be
read again — answering with the default would let a rule the modeller switched off write to the model
on any transient failure.
The trace and the engine read one verdict
A rule declares its conditions as a labelled list rather than folding them into one boolean, because two readers need them. The engine reads the list as a conjunction and decides whether to apply. The tracer reads the identical list and prints which label failed and what stood in the way, which is the question a rule author asks while establishing a trigger set.
Both readers derive from a single private verdict inside AutoStereotypeRule, so a trace can never
describe a rule differently from the way the engine runs it. A rule that stated its condition once
for the engine and restated it in prose for the tracer would drift, and the trace would describe a
rule nobody wrote.
Every failure resolves to the same verdict, no match, and two safeguards live at that level rather than in any one rule:
- A rule declaring no conditions has stated no reason to apply, and matches nothing.
- A rule whose own code throws while evaluating a candidate yields no match, rather than letting an exception reach the transaction that is committing.
Both exist so that a rule which cannot be evaluated never writes.
The verdict is computed from candidates rather than from the event's source. A rule sweeps back from a definition to the usages that refer to it, and those usages report no event of their own, so a tracer reading only the source could not show whether the sweep-back caught them.
Failures are contained to what failed
The batch drops any candidate the same transaction deletes. A transaction that deletes an element still reports every property change made on the way out, and stereotyping such an element would write to something that no longer exists.
An element that fails to take its stereotype is reported against itself and the batch continues. A read-only element, or one belonging to an unloaded module, makes the write throw, and aborting the batch there would leave the rest of a user's edit silently unstereotyped.
Both outcomes go to the log and nowhere else. Auto-stereotyping is meant to be invisible while it
works, and GUILog.log(String) would put the notification window in front of the diagram once per
edit that landed. See Anvil: log from a
resource.
Trigger sets come from traces, not from the metamodel
What the model reports contradicts a reading of the UML metamodel often enough that guessing does not
work. Ownership of a Property arrives as UMLClass and of a CallBehaviorAction as activity,
and PropertyNames.OWNER fires for neither. Applying a stereotype to a definition reports no event
at all on the usages that refer to it.
A rule's candidatesOf is therefore established from a recorded trace of the modelling action it
must catch. The consequence reaches beyond one rule: a change to the engine that alters which events
reach candidatesOf invalidates every rule already written against it, in every consumer. Such a
change calls for re-recording the affected traces rather than reasoning about the difference.
What stays internal, and why
Only AutoStereotypeEngine, AutoStereotypeRule, AutoStereotypeRuleSet, Condition and
condition(...) are public. AutoStereotypeOptions, AutoStereotypeListener,
AutoStereotypeOptionsConfigurator, RuleOptionLabels and RuleSuspension stay internal, because a
resource takes all five through the engine rather than wiring them itself.
That boundary is what makes one rule's ownership of one switch inescapable: no caller outside the
library can construct an option that is not a rule's. A resource that needs to read a switch calls
AutoStereotypeEngine.isEnabled(project, rule), which exposes the answer without exposing the type
that stores it. The two readers on a rule — plan for the engine, explain for the tracer — are
internal for the same reason: how a rule is driven stays a decision this library can revise.
Widening any of them is a decision to support a second way of installing the engine, rather than a convenience.
Related
- Anvil: write an auto-stereotype rule — the contract, step by step.
- Anvil: trace model events — the trace this page refers to, and how to read one without an engine.