Skip to content

Propagate the mojo execution scope to threads started by a plugin, or document that it is not supported? #13827

Open

Description

@slachiewicz

Question

Should Maven offer plugins a way to run work on another thread inside the current mojo execution scope, or is the expectation that plugins never let scoped components be created off the Mojo thread?

Case

maven-site-plugin's site:run serves pages from the JDK HTTP server's own threads, after execute() has started the server. A Doxia parser contributed by a site dependency, the Asciidoctor one, injects MavenProject. Parsers are looked up per document, so it is instantiated on a server thread and fails with

OutOfScopeException: Cannot access Key[type=MavenProject, annotation=[none]] outside of a scoping block
  at MojoExecutionScopeModule.configure(MojoExecutionScopeModule.java:47)

site:site works, since it renders on the Mojo thread (apache/maven-site-plugin#987, MSITE-849).

MojoExecutionScope keeps its state in a ThreadLocal (3.9.x org.apache.maven.execution.scope.internal, 4.x org.apache.maven.impl.di). SessionScope does not; it uses a CopyOnWriteArrayList, so session-scoped components work from any thread. Plugins see only org.apache.maven.execution.scope (the annotations and WeakMojoExecutionListener), so they cannot enter or seed the mojo execution scope themselves.

What the plugin does now

apache/maven-site-plugin#1350 keeps the server's thread pool for requests and hands only document rendering to the Mojo thread, which loops over a queue until the server stops. It works with every Maven version, but it serializes rendering and any plugin starting a server or a worker pool has to rediscover it.

Options

  1. Context propagation API. In the exported org.apache.maven.execution.scope package (and the Maven 4 API equivalent), something that captures the current mojo execution scope on the Mojo thread and returns a wrapper (Runnable/Callable/Executor) that enters the captured state on whichever thread runs the task and exits it afterwards.
  2. Guidance only. Document that mojo-execution-scoped objects are only available on the Mojo thread, and that components meant to be created by plugins on other threads must not inject them; the producer of the component (here Doxia Sitetools) should pass what is needed explicitly. That is being discussed for this case in Give Doxia parsers the document and site context instead of Maven injection maven-doxia-sitetools#736.
  3. Something else that already exists and I missed.

The site plugin needs option 2 or its current workaround anyway while it supports Maven 3.9. The question is whether option 1 is worth adding for 3.10 or 4.x, or whether option 2 is the intended model.

Activity

  1. gnodet commented on Nov 4, 2026

    @gnodet
    Contributor

    The root cause here is that MojoExecutionScope has always been ThreadLocal-based (since MNG-5530 in 2012), and that is intentional: when running with -T N, multiple mojo executions run concurrently on different threads, and the ThreadLocal isolates their scoped state.

    Maven 3.9.x

    Option 2 (documentation + guidance) is the right answer for 3.x. The workaround in apache/maven-site-plugin#1350 — routing document rendering back to the mojo thread via a queue — is the correct pattern. Plugins that spawn worker threads must not let those threads look up @MojoExecutionScoped components, because there is no scope state on those threads. This should be documented clearly.

    Maven 4

    The situation is cleaner by design:

    A v4 plugin gets a fresh Injector per mojo execution (created in DefaultMavenPluginManager), with Session, Project, MojoExecution, and Log bound directly as plain instances via bindInstance. There is no ThreadLocal involved at all. A mojo simply declares:

    @Inject Session session;
    @Inject Project project;
    @Inject MojoExecution mojoExecution;

    ...and gets the right instances for that execution automatically. If the mojo spawns worker threads, it passes those objects explicitly as parameters — no scope, no magic.

    v4 mojos are thread-safe by design: each execution gets a fresh mojo instance with its own injector, so no mojo state is ever shared between concurrent executions. This is what makes v4 mojos safe to run in parallel builds without locking.

    If a plugin needs to share state across multiple mojo invocations (e.g. an initialize mojo and a verify mojo sharing computed data), it can inject a @SessionScoped or @Singleton bean — those are resolved from the shared container, not the per-execution local injector, so they survive across executions for the duration of the build. Those shared beans are the only place where explicit thread-safety is required.

    A core extension (.mvn/extensions.xml) lives in the shared container and can use @SessionScoped for session-lifetime components. The existing @MojoExecutionScoped (v3 annotation, Plexus/Sisu/Guice path) still works for extensions that need per-execution lifecycle — but even then, the ThreadLocal constraint applies: the scope is only valid on the mojo thread.

    On org.apache.maven.api.di.MojoExecutionScoped (the v4 annotation)

    This annotation exists in maven-api-di but is unfinished and unusable: the Guice binding in MojoExecutionScopeModule is commented out, there is no proxy path for injecting it into a wider scope (unlike @SessionScoped which creates a JDK proxy transparently), and no production code in Maven itself uses it. We should remove it from the v4 API to avoid confusion — v4 plugins do not need it (they get execution context via direct injection), and extensions that need scoped components should use the established v3 annotation or @SessionScoped.

    On Option 1 (context propagation API)

    Not justified. It would work around a design problem rather than fixing it. Plugins that need concurrent work should pass context explicitly, not rely on transparent scope propagation across threads.

    Long-term for site:run

    Migrating maven-site-plugin to the v4 API is the right fix. Doxia parsers would receive Session and Project via direct injection or explicit parameter passing — no scoped lookups, no ThreadLocal, no thread issues.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    questionFurther information is requested

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions