This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new f1bfb988 simplify documentation on JSR-330 / Sisu
f1bfb988 is described below
commit f1bfb988adbd886276ea31e7bf92c35ee3399fd5
Author: Hervé Boutemy <[email protected]>
AuthorDate: Sun May 28 16:43:48 2023 +0200
simplify documentation on JSR-330 / Sisu
---
content/markdown/maven-jsr330.md | 204 +++++----------------------------------
1 file changed, 24 insertions(+), 180 deletions(-)
diff --git a/content/markdown/maven-jsr330.md b/content/markdown/maven-jsr330.md
index 65359822..5212d59a 100644
--- a/content/markdown/maven-jsr330.md
+++ b/content/markdown/maven-jsr330.md
@@ -20,43 +20,35 @@ under the License.
## Why JSR-330?
Maven has a long history of using dependency injection (DI) by way of
[Plexus][plexus], so the intent of using
-[JSR-330][jsr330] is to replace a custom DI mechanism (with custom
`@Component`/`@Requirement` annotations) with something standard ( with
`@Named`/`@Inject` anotations). The implementation Maven
+[JSR-330][jsr330] is to replace a custom DI mechanism (with custom Plexus
`@Component`/`@Requirement` annotations) with something standard (with
`@Named`/`@Inject` annotations). The implementation Maven
uses - since 3.0-beta-3 - is named [Sisu][sisu] and is based on [Guice
3.x][guice], which directly supports JSR-330.
-If you are using [Plexus annotations and APIs][plexus-container] currently,
+If you are using [Plexus annotations and APIs][plexus-annotations] currently,
there is no rush to switch and no big bang conversions are necessary: Plexus,
JSR-330 and Guice APIs all happily
co-exist within Maven\'s core and you can choose to use JSR-330 when you wish.
There are hundreds of components
-written using the Plexus APIs.
+written using the Plexus APIs.
If you want to use JSR-330, you must understand that your code won\'t be
compatible with Maven 3.0.x
but only with Maven 3.1.0 and later. Even though JSR-330 has been available in
core since Maven 3.0-beta-3, it was made available to plugins and
extensions only in Maven 3.1.0 (see [MNG-5343][MNG-5343] for more details).
-If you are interested the background of moving from Plexus to Guice and
JSR-330, you can refer to the following articles:
+If you are interested the background of moving from Plexus to Guice and
JSR-330, you can refer to the following "Plexus to Guice" articles from 2010:
[part 1][p2g1], [part 2][p2g2] and [part 3][p2g3].
-- [Plexus to Guice Part 1][p2g1]
-- [Plexus to Guice Part 2][p2g2]
-- [Plexus to Guice Part 3][p2g3]
-
-If you are interested in migrating from Plexus to JSR-330, Sisu has a [Plexus
Migration documentation][SisuPlexusMigration] that is done for you.
+If you are interested in migrating from Plexus Annotations to JSR-330, Sisu
has a [Plexus Migration documentation][SisuPlexusMigration] that is done for
you.
## How to use JSR-330
When you use JSR-330 in Maven plugins or extensions, there are two things you
need to setup in your build:
1. First you want a dependency on `javax.inject` so you can use the `@Inject`,
`@Named`, and `@Singleton` annotations
-in your plugins and extensions.
+in your plugins and extensions (eventually in addition to [Plexus
annotations][plexus-annotations]).
2. Second you need to setup the [`sisu-maven-plugin`][sisu-maven-plugin] to
index the JSR-330 components
-you want made available to Maven. The `sisu-maven-plugin` creates its index in
`META-INF/sisu/javax.inject.Named`.
+you want made available to Maven. The [`sisu-maven-plugin`][sisu-maven-plugin]
creates its index in `META-INF/sisu/javax.inject.Named` (eventually in addition
to [`plexus-component-metadata`][plexus-component-metadata]).
-If you take a look in that file with the example from the next paragraph, you
will see something like the following:
+### Implementation Details
-```java
-org.apache.maven.lifecycle.profiler.LifecycleProfiler
-org.apache.maven.lifecycle.profiler.internal.DefaultSessionProfileRenderer
-org.apache.maven.lifecycle.profiler.internal.DefaultTimer
-```
+If you take a look in that `META-INF/sisu/javax.inject.Named` file with the
example from the next paragraph, you will see a list of full class names.
Enumerating the implementations means that no classpath scanning is required
in runtime to find them, which keeps Maven\'s
startup time fast. Note that our container is configured by default to only
use the index. While this keeps things fast,
@@ -64,165 +56,16 @@ if you use JSR-330 components in dependencies that do not
contain an index, thos
not be discovered. This is a compromise that is reasonable given Maven is a
command-line tool where startup speed
is important.
-## How to use JSR-330 in extensions
-
-Let\'s take a look at an example extension. We\'ll take a look at the POM, and
a little bit of the implementation
-so you can get an idea of how JSR-330 extensions work. Really, it\'s just a
simple JSR-330 component.
-If you want to look at the full implementation, you can find it
[here][tesla-profiler] on Github.
-
-Ok, so let\'s take a look at the POM:
-
-```xml
-<?xml version="1.0"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
https://maven.apache.org/xsd/maven-4.0.0.xsd";>
- <modelVersion>4.0.0</modelVersion>
- <groupId>org.apache.maven</groupId>
- <artifactId>maven-profiler</artifactId>
- <version>0.0.1-SNAPSHOT</version>
- <name>Maven :: Profiler</name>
- <properties>
- <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
- </properties>
- <dependencies>
- <dependency>
- <groupId>javax.inject</groupId>
- <artifactId>javax.inject</artifactId>
- <version>1</version>
- </dependency>
- <dependency>
- <groupId>org.apache.maven</groupId>
- <artifactId>maven-core</artifactId>
- <version>3.0.3</version>
- </dependency>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.8.2</version>
- </dependency>
- </dependencies>
- <build>
- <plugins>
- <plugin>
- <groupId>org.eclipse.sisu</groupId>
- <artifactId>sisu-maven-plugin</artifactId>
- <version>0.3.3</version>
- <executions>
- <execution>
- <id>generate-index</id>
- <goals>
- <goal>main-index</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</project>
-```
+## How to use JSR-330 in plugins
-So, as mentioned, we have the `javax.inject` dependency and the
`sisu-maven-plugin` configured to create
-the JSR-330 component index. When you build and place the extension JAR in the
`${MAVEN_HOME}/lib/ext` directory,
-it will automatically get picked up by Maven. In the case of this example, we
have an implementation of
-an `EventSpy` that times the executions of individual mojos within a phase in
the lifecycle.
+Let\'s take a look at an example plugin: If you want to look at this example
project, you can find the code [in Maven Core ITs][jsr330-plugin].
-```java
-package org.apache.maven.lifecycle.profiler;
+The POM is setup for JSR-300 as previously mentioned, with the `javax.inject`
dependency and the `sisu-maven-plugin` configured to create
+the JSR-330 component index.
-import javax.inject.Inject;
-import javax.inject.Named;
-import javax.inject.Singleton;
-
-import org.apache.maven.eventspy.AbstractEventSpy;
-import org.apache.maven.execution.ExecutionEvent;
-
-@Named
-@Singleton
-public class LifecycleProfiler extends AbstractEventSpy {
-
- //
- // Components
- //
- private SessionProfileRenderer sessionProfileRenderer;
-
- //
- // Profile data
- //
- private SessionProfile sessionProfile;
- private ProjectProfile projectProfile;
- private PhaseProfile phaseProfile;
- private MojoProfile mojoProfile;
-
- @Inject
- public LifecycleProfiler(SessionProfileRenderer sessionProfileRenderer) {
- this.sessionProfileRenderer = sessionProfileRenderer;
- }
-
- @Override
- public void init(Context context) throws Exception {
- }
-
- @Override
- public void onEvent(Object event) throws Exception {
- if (event instanceof ExecutionEvent) {
-
-
- ExecutionEvent executionEvent = (ExecutionEvent) event;
- if (executionEvent.getType() == ExecutionEvent.Type.SessionStarted) {
- //
- //
- //
- sessionProfile = new SessionProfile();
- } else if (executionEvent.getType() == ExecutionEvent.Type.SessionEnded)
{
- //
- //
- //
- sessionProfile.stop();
-
- sessionProfileRenderer.render(sessionProfile);
-
- } else if (executionEvent.getType() ==
ExecutionEvent.Type.ProjectStarted) {
- //
- // We need to collect the mojoExecutions within each project
- //
- projectProfile = new ProjectProfile(executionEvent.getProject());
- } else if (executionEvent.getType() ==
ExecutionEvent.Type.ProjectSucceeded || executionEvent.getType() ==
ExecutionEvent.Type.ProjectFailed) {
- //
- //
- //
- projectProfile.stop();
- sessionProfile.addProjectProfile(projectProfile);
- } else if (executionEvent.getType() == ExecutionEvent.Type.MojoStarted) {
- String phase = executionEvent.getMojoExecution().getLifecyclePhase();
- //
- // Create a new phase profile if one doesn't exist or the phase has
changed.
- //
- if(phaseProfile == null) {
- phaseProfile = new PhaseProfile(phase);
- } else if (!phaseProfile.getPhase().equals(phase)) {
- phaseProfile.stop();
- projectProfile.addPhaseProfile(phaseProfile);
- phaseProfile = new PhaseProfile(phase);
- }
- mojoProfile = new MojoProfile(executionEvent.getMojoExecution());
- } else if (executionEvent.getType() == ExecutionEvent.Type.MojoSucceeded
|| executionEvent.getType() == ExecutionEvent.Type.MojoFailed) {
- //
- //
- //
- mojoProfile.stop();
- phaseProfile.addMojoProfile(mojoProfile);
- }
- }
- }
-}
-```
-
-## How to use JSR-330 in plugins
-
-Let\'s take a look at an example plugin. The POM is setup in a similar way to
an extension, but we add a dependency
-to `maven-plugin-api` and `maven-plugin-annotations` to extend the
`AbstractMojo` and use the Java 5 plugin
-annotations in our example.
+In addition, we add classical Maven plugin dependencies
+`maven-plugin-api` and `maven-plugin-annotations` to extend the `AbstractMojo`
and use the Java Plugin Tools Annotations with associated
`maven-plugin-plugin` (see [Maven Plugin Tools](/plugin-tools/)).
```xml
<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
@@ -235,7 +78,7 @@ annotations in our example.
<packaging>maven-plugin</packaging>
<name>maven-jsr330-plugin Maven Plugin</name>
- <url>https://maven.apache.org</url>
+ <description>As sample Maven Plugin that uses JSR-330
components</description>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
@@ -248,11 +91,13 @@ annotations in our example.
<groupId>javax.inject</groupId>
<artifactId>javax.inject</artifactId>
<version>1</version>
+ <scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-plugin-api</artifactId>
<version>${mavenVersion}</version>
+ <scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.maven.plugin-tools</groupId>
@@ -295,7 +140,7 @@ annotations in our example.
<plugin>
<groupId>org.eclipse.sisu</groupId>
<artifactId>sisu-maven-plugin</artifactId>
- <version>0.3.3</version>
+ <version>0.3.5</version>
<executions>
<execution>
<id>generate-index</id>
@@ -312,8 +157,8 @@ annotations in our example.
Now let\'s take a look at the plugin code. You\'ll notice that we\'re using
constructor injection
which makes testing a lot easier. If you want to test your `Jsr330Component`,
you do not need the container
-to instantiate the `Mojo`. In this simple case, you can actually test this
plugin without using the plugin
-testing harness because you can instantiate the `Jsr330Component` and
`Jsr330Mojo` directly and wire
+to instantiate the `Mojo`. In this simple case, you can actually test this
plugin without using the [plugin
+testing harness](/plugin-testing/maven-plugin-testing-harness/index.html)
because you can instantiate the `Jsr330Component` and `Jsr330Mojo` directly and
wire
everything up manually using the constructor. Constructor injection, which
Plexus lacks, greatly simplifies testing.
```java
@@ -350,16 +195,15 @@ public class Jsr330Mojo
}
```
-If you want to look at this example project, you can find the code [in Maven
Core ITs][jsr330-plugin].
-
[tesla-profiler]: https://github.com/tesla/tesla-profiler
[p2g1]:
https://www.sonatype.com/people/2010/01/from-plexus-to-guice-1-why-guice/
[p2g2]:
https://www.sonatype.com/people/2010/01/from-plexus-to-guice-2-the-guiceplexus-bridge-and-custom-bean-injection/
[p2g3]:
https://www.sonatype.com/people/2010/01/from-plexus-to-guice-3-creating-a-guice-bean-extension-layer/
[jsr330]: https://www.jcp.org/en/jsr/detail?id=330
[sisu]: https://eclipse.org/sisu/
-[plexus]: https://codehaus-plexus.github.io/
-[plexus-container]:
https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/
+[plexus]: https://codehaus-plexus.github.io/plexus-containers/
+[plexus-component-metadata]:
https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/
+[plexus-annotations]:
https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/
[jsr330-plugin]:
https://github.com/apache/maven-integration-testing/tree/master/core-it-suite/src/test/resources/mng-5382
[guice]: https://code.google.com/p/google-guice/
[sisu-maven-plugin]: https://eclipse.org/sisu/docs/api/org.eclipse.sisu.mojos/
