Agent Embedder Maven Plugin

Use this goal, if (and only if) you have an executable JAR (with a Main-Class attribute in its manifest) and wish to run a java agent automatically when running the JAR with java -jar my.jar on JRE 9+.

Normally, you would need an additional -javaagent:/path/to/agent.jar JVM argument, but since Java 9 there is the Launcher-Agent-Class mechanism. I.e., even though this plugin works just fine on Java 8, you do need to launch the modified executable JAR on JRE 9+ to enjoy the benefits of this JVM feature.

The javaAgents specified for this goal will be unpacked from their JARs and embedded into the main artifact's root directory to make them visible to the java agent classloader during runtime. JVM classloaders cannot load agents from nested JARs.

The main artifact is expected to exist already when executing this goal. Typically, the Maven module already uses another plugin creating a build artifact during the package phase, which is why this goal by default also runs in the same phase. Make sure to configure this plugin to run after the plugin creating the main artifact, so you have something for it to operate on. This can be done most easily by simply listing both plugins in the POM file in the desired chronological execution order, if they are to run in the same phase. Another option would be to let them run in different phases, making sure that this plugin runs later than the one creating the artifact. We recommend to stick to convention over configuration and use the package phase. For example:

<!-- Create executable Spring Boot fat JAR -->
<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<!-- Embed Java agent(s) for automatic execution -->
<plugin>
  <groupId>dev.aspectj</groupId>
  <artifactId>agent-embedder-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>embed-agents</id>
      <goals>
        <goal>embed</goal>
      </goals>
      <configuration>
        <javaAgents>
          <!-- ... -->
        </javaAgents>
        <removeEmbeddedAgents>true</removeEmbeddedAgents>
      </configuration>
    </execution>
  </executions>
</plugin>

Unique features not offered by the Java 9+ Launcher-Agent-Class mechanism:

• Via Launcher-Agent-Class, the JVM only supports a single agent for auto-start, not multiple ones. Multiple agents can only be specified on the JVM command line. But this plugin installs its own launcher agent, which in turn is capable of starting multiple java agents.
• Launcher-Agent-Class also does not support agent option strings like the JVM command line does. This plugin, however, does support agent arguments via its launcher agent. See the javaAgents section for more details.