Anvil
Explanation

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 holdsWhich does
AutoStereotypeOptionsReads a rule's switch from a project
AutoStereotypeOptionsConfiguratorDeclares one switch per rule in the Project Options dialog
RuleSuspensionHolds the code-side gate, per thread
ModelEventTraceTraces every commit, annotated with each rule's verdict
CommitListenerInstallerAttaches 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.

GateHeld byScopePersists
RuleSuspensionThe resource's own codeOne engine, one threadNothing in the model
Profile presenceThe project's used profilesOne projectIn the model
Project Options switchThe modellerOne projectIn 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.

On this page