This is an automated email from the ASF dual-hosted git repository.

slachiewicz 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 a2c5f65c Use JSR-330 annotations on the Doxia developer pages
a2c5f65c is described below

commit a2c5f65c5f2d84b18d0e18f37ad0c9642a6c5111
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sun Nov 1 15:19:38 2026 +0000

    Use JSR-330 annotations on the Doxia developer pages
---
 content/markdown/doxia/developers/macros.md     | 44 +++++++------------------
 content/markdown/doxia/developers/modules.md.vm | 24 +++++++++-----
 content/markdown/doxia/developers/sink.md       | 36 ++++++++++++--------
 content/markdown/maven-jsr330.md                | 31 +++++++++++++++++
 4 files changed, 81 insertions(+), 54 deletions(-)

diff --git a/content/markdown/doxia/developers/macros.md 
b/content/markdown/doxia/developers/macros.md
index e3d569fc..3f1b07ac 100644
--- a/content/markdown/doxia/developers/macros.md
+++ b/content/markdown/doxia/developers/macros.md
@@ -26,41 +26,21 @@ under the License.
 
 # Create a New Doxia Macro
 
-You need to add the following [plexus-component-metadata 
plugin](https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/)
 configuration to generate the correct Plexus _component.xml_ file from 
annotations for the project containing your macro:
-
-```xml
-<project>
-  ...
-  <build>
-    ...
-    <plugins>
-      <plugin>
-        <groupId>org.codehaus.plexus</groupId>
-        <artifactId>plexus-component-metadata</artifactId>
-        <executions>
-          <execution>
-            <goals>
-              <goal>generate-metadata</goal>
-            </goals>
-          </execution>
-        </executions>
-      </plugin>
-      ...
-    </plugins>
-  ...
-  </build>
-  ...
-</project>
-```
+A macro is a JSR-330 component named after the macro. Set up the project that 
contains it as described in [How to use 
JSR-330](/maven-jsr330.html#How_to_use_JSR-330): a `javax.inject` dependency 
and the `sisu-maven-plugin` index.
 
 You should implement the _AbstractMacro_ class:
 
 ```java
+import javax.inject.Named;
+import javax.inject.Singleton;
+
 import org.apache.maven.doxia.macro.AbstractMacro;
+import org.apache.maven.doxia.macro.MacroExecutionException;
+import org.apache.maven.doxia.macro.MacroRequest;
+import org.apache.maven.doxia.sink.Sink;
 
-/**
- * @plexus.component role="org.apache.maven.doxia.macro.Macro" role-hint="my"
- */
+@Singleton
+@Named("my")
 public class MyMacro
     extends AbstractMacro
 {
@@ -80,13 +60,13 @@ To use it, you need to write the following markups:
 - APT
 
     ```text
-    %{my|myParam=myValue} <!-- my is the macro name defined by role-hint -->
+    %{my|myParam=myValue} <!-- my is the macro name set by @Named -->
     ```
 
 - XDoc
 
     ```xml
-    <macro name="my"> <!-- my is the required macro name defined by role-hint 
-->
+    <macro name="my"> <!-- my is the required macro name set by @Named -->
       <param name="myParam" value="myValue"/>
     </macro>
     ```
@@ -97,4 +77,4 @@ To use it, you need to write the following markups:
 - [Doxia Macros Guide](../macros/index.html)
 - [Doxia API Reference](../doxia/apidocs/index.html)
 - [Doxia Sitetools API Reference](../doxia-sitetools/apidocs/index.html)
-- [Upgrading from Plexus Javadoc Tags to Plexus Java 
Annotations](/plugin-developers/cookbook/plexus-plugin-upgrade.html)
+- [Maven & JSR-330](/maven-jsr330.html)
diff --git a/content/markdown/doxia/developers/modules.md.vm 
b/content/markdown/doxia/developers/modules.md.vm
index fc9d11de..f21c5a54 100644
--- a/content/markdown/doxia/developers/modules.md.vm
+++ b/content/markdown/doxia/developers/modules.md.vm
@@ -43,18 +43,20 @@ First, the easiest way is to create a POM with 
_doxia-modules_ as parent:
 </project>
 ```
 
-Secondly, you should implement some Doxia classes, depending on what features 
you want: parsing or generating markup.
+Secondly, you should implement some Doxia classes, depending on what features 
you want: parsing or generating markup. Parsers, parser modules and sink 
factories are JSR-330 components, named by `@Named`; the _doxia-modules_ parent 
already writes the component index. For details, see [Maven & 
JSR-330](/maven-jsr330.html#How_to_name_components).
 
 ${esc.h}${esc.h} Parsing
 
 - _MyParser_ class
 
     ```java
+    import javax.inject.Named;
+    import javax.inject.Singleton;
+    
     import org.apache.maven.doxia.parser.AbstractParser;
-    import org.apache.maven.doxia.parser.Parser;
-    import org.codehaus.plexus.component.annotations.Component;
     
-    @Component( role = Parser.class, hint = "my" )
+    @Singleton
+    @Named("my")
     public class MyParser
         extends AbstractParser
     {
@@ -79,10 +81,13 @@ ${esc.h}${esc.h} Parsing
 - _MyParserModule_ class
 
     ```java
+    import javax.inject.Named;
+    import javax.inject.Singleton;
+    
     import org.apache.maven.doxia.parser.module.AbstractParserModule;
-    import org.codehaus.plexus.component.annotations.Component;
     
-    @Component( role = ParserModule.class, hint = "my" )
+    @Singleton
+    @Named("my")
     public class MyParserModule
         extends AbstractParserModule
     {
@@ -109,10 +114,13 @@ ${esc.h}${esc.h} Generating
 - _MySinkFactory_ class
 
     ```java
+    import javax.inject.Named;
+    import javax.inject.Singleton;
+    
     import org.apache.maven.doxia.sink.SinkFactory;
-    import org.codehaus.plexus.component.annotations.Component;
     
-    @Component( role = SinkFactory.class, hint = "my" )
+    @Singleton
+    @Named("my")
     public class MySinkFactory
         implements SinkFactory
     {
diff --git a/content/markdown/doxia/developers/sink.md 
b/content/markdown/doxia/developers/sink.md
index 199856de..7129dec3 100644
--- a/content/markdown/doxia/developers/sink.md
+++ b/content/markdown/doxia/developers/sink.md
@@ -32,22 +32,30 @@ under the License.
 Doxia can be used to transform an arbitrary input document to any supported 
output format. The following snippet shows how to use a Doxia _Parser_ to 
transform an apt file to html:
 
 ```java
-  File userDir = new File( System.getProperty ( "user.dir" ) );
-  File inputFile = new File( userDir, "test.apt" );
-  File outputFile = new File( userDir, "test.html" );
-
-  SinkFactory sinkFactory = (SinkFactory) lookup( SinkFactory.ROLE, "html" ); 
// Plexus lookup
-
-  Sink sink = sinkFactory.createSink( outputFile.getParentFile(), 
outputFile.getName() ) );
-
-  Parser parser = (AptParser) lookup( Parser.ROLE, "apt" ); // Plexus lookup
-
-  Reader reader = ReaderFactory.newReader( inputFile, "UTF-8" );
-
-  parser.parse( reader, sink );
+  @Inject
+  public MyConverter( @Named( "xhtml" ) SinkFactory sinkFactory, @Named( "apt" 
) Parser parser )
+  {
+      this.sinkFactory = sinkFactory;
+      this.parser = parser;
+  }
+
+  public void convert()
+      throws IOException, ParseException
+  {
+      File userDir = new File( System.getProperty( "user.dir" ) );
+      File inputFile = new File( userDir, "test.apt" );
+      File outputFile = new File( userDir, "test.html" );
+
+      Sink sink = sinkFactory.createSink( outputFile.getParentFile(), 
outputFile.getName() );
+
+      try ( Reader reader = Files.newBufferedReader( inputFile.toPath(), 
StandardCharsets.UTF_8 ) )
+      {
+          parser.parse( reader, sink );
+      }
+  }
 ```
 
-It is recommended that you use [Plexus](https://codehaus-plexus.github.io/) to 
look up the parser. In principle you could instantiate the parser directly ( 
`Parser parser = new AptParser();` ) but then some special features like macros 
will not be available.
+It is recommended that you inject the parser and the sink factory by name, as 
described in [How to name 
components](/maven-jsr330.html#How_to_name_components). In principle you could 
instantiate the parser directly ( `Parser parser = new AptParser();` ) but then 
some special features like macros will not be available.
 
 You could also use the [Doxia Converter 
Tool](/doxia/doxia-tools/doxia-converter/index.html) to parse a given file/dir 
to another file/dir. To move a site from APT to Markdown, see [Migrating APT to 
Markdown](/doxia/migrating-apt-to-markdown.html).
 
diff --git a/content/markdown/maven-jsr330.md b/content/markdown/maven-jsr330.md
index 68ab944c..180c9260 100644
--- a/content/markdown/maven-jsr330.md
+++ b/content/markdown/maven-jsr330.md
@@ -196,6 +196,37 @@ public class Jsr330Mojo
 }
 ```
 
+## How to name components
+
+Where a library offers several implementations of one interface, `@Named` 
gives each implementation the name that
+callers select it by. Plexus called this name the role hint. Doxia parsers, 
sink factories and macros work this way:
+
+```java
+import javax.inject.Named;
+import javax.inject.Singleton;
+
+import org.apache.maven.doxia.parser.AbstractTextParser;
+
+@Singleton
+@Named("my")
+public class MyParser extends AbstractTextParser {
+    ...
+}
+```
+
+A component that needs one implementation injects it by interface and name, 
which replaces the Plexus
+`lookup(Parser.ROLE, "my")` call:
+
+```java
+@Inject
+public MyComponent(@Named("my") Parser parser) {
+    this.parser = parser;
+}
+```
+
+The implementation is found only if its JAR contains the index that the 
`sisu-maven-plugin` writes, as described in
+[How to use JSR-330](#How_to_use_JSR-330).
+
 ## Lifecycle annotations (JSR-250)
 
 Sisu managed beans also support lifecycle annotations defined by 
[JSR-250](https://jcp.org/en/jsr/detail?id=250) (for example `@PostConstruct`).

Reply via email to