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`).