Anvil
How-to guides

Anvil: log from a resource

The raw Open API version of this page is Open API: log from a plugin.

A resource writes its lines into CATIA Magic's own Log4j log, under a category it names itself. The logging and format packages carry everything this page uses, and both are on the runtime side of what Anvil publishes.

Take one logger

ResourceLog.of answers with the logger for a category and caches it, so a second call for the same name answers with the same logger. Keep it in a top-level property and reuse it:

import com.mbseconsulting.anvil.format.IdStyle
import com.mbseconsulting.anvil.format.fString
import com.mbseconsulting.anvil.logging.ResourceLog

private val log = ResourceLog.of("ACME")

log.info { "applied ${stereotype.fString()} to ${element.fString(IdStyle.SHORT)}" }

Name the category for the resource, short and symbolic — ACME rather than a class or a package name. CATIA Magic prints it as %c, a reader greps for it, and one configuration entry raises it.

A resource that runs the auto-stereotyping engine passes the same logger to its AutoStereotypeRuleSet, so the engine and the tracer write under the resource's category too.

Pass a lambda, never a built string

Every method takes () -> String. CATIA Magic's root logger sits at info, so a debug or trace call costs one boolean while nobody is listening and builds nothing:

log.debug { "candidates: ${candidates.fString(IdStyle.SHORT)}" }

Choose a level

MethodCarries
trace { }High-volume detail, such as one line per model event
debug { }Detail for diagnosing a problem, invisible until someone raises the category
info { }Something the resource did that a reader of the log would want to know
warn(throwable) { }Something went wrong and the resource carried on
error(throwable) { }Something went wrong and the resource could not carry on

warn and error take the throwable first, before the lambda, and it defaults to null:

log.error(exception) { "could not apply ${stereotype.fString()}" }
log.warn { "no profile found for \"${project.name}\"" }

Render model values with fString

toString on a model element answers with an implementation class and a hash. fString answers with the metaclass, the name, the applied stereotypes and the identifier:

Class "Concept A" «Concept» (_2026x_1_328c0658_1786288981600_428316_3213)

fString accepts any value, so a collection, a map or a plain string renders through the same call, and every read inside it is guarded: an element the committing transaction has just deleted renders as a placeholder rather than throwing out of the log call.

Anvil: render model values covers the IdStyle argument, what each field of the rendering means, and hString for a Message Window sink.

Attribute a block of work

forAction sets Log4j's action_name for the duration of a block, so every line inside carries the name in CATIA Magic's own pattern and no message repeats it:

log.forAction("Auto-stereotype") { applications.forEach(::applyOne) }

The previous value is restored on the way out, because a resource shares that context with the tool.

Read the lines back

CATIA Magic configures Log4j at <install>/data/log4j2.xml. One entry raises the resource's category and touches nothing else:

<Logger name="ACME" level="debug"/>

The tool's configuration carries monitorInterval="30", so the entry takes effect within thirty seconds and needs no restart. Leave additivity at its default. Every custom entry in the tool's own configuration sets additivity="false", and copying that idiom takes the resource's lines out of the tool log rather than adding to them.

What not to reach for

println and System.out write to the console that launched the process, which a modeller running an installed CATIA Magic never sees.

A logger obtained straight from LogManager.getLogger loses the caller location Anvil prepends and the lambda guard that keeps a failed message from failing its caller. It also lands under a category nobody knows to raise.

Nothing in this project reaches the Message Window. GUILog.log(String) delegates to log(message, open = true), which opens the notification window on every call, so a resource logging once per model change puts that window in front of the modeller once per edit. A resource that must interrupt a modelling session makes that decision itself, at the moment it interrupts, and calls GUILog with the flag it wants — or reaches for Notify.of(category), which builds that sink for you as a transient balloon instead of a window — see Anvil: notify a modeller. hString renders a model element as an mdel:// anchor for a resource that builds such a sink; the Message Window turns the anchor into a link that selects the element.

On this page