You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by gn...@apache.org on 2025/04/02 01:28:55 UTC
(maven) branch add-api-javadoc created (now 28efb8958f)
This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a change to branch add-api-javadoc
in repository https://gitbox.apache.org/repos/asf/maven.git
at 28efb8958f Add missing Javadoc to API subprojects
This branch includes the following new commits:
new 28efb8958f Add missing Javadoc to API subprojects
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven) 01/01: Add missing Javadoc to API subprojects
Posted by gn...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch add-api-javadoc
in repository https://gitbox.apache.org/repos/asf/maven.git
commit 28efb8958f68dd4c3ca74f5596a447eb49e65edb
Author: Guillaume Nodet <gn...@gmail.com>
AuthorDate: Wed Apr 2 03:28:43 2025 +0200
Add missing Javadoc to API subprojects
- Add class-level and method-level Javadoc to various classes in api/ subprojects
- Add missing package-info.java for org.apache.maven.di.tool package
- Enhance existing package-info.java files with more detailed documentation
- Ensure consistent Javadoc style across the API
---
.../org/apache/maven/api/annotations/Config.java | 27 +++++
.../java/org/apache/maven/api/ExtensibleEnums.java | 77 ++++++++++++++
.../maven/api/services/MavenBuilderException.java | 26 +++++
.../apache/maven/api/services/ModelProblem.java | 32 +++++-
.../maven/api/services/ProblemCollector.java | 32 +++++-
.../maven/api/services/ProjectBuilderRequest.java | 111 +++++++++++++++++++++
.../org/apache/maven/di/tool/DiIndexProcessor.java | 43 ++++++++
.../org/apache/maven/di/tool/package-info.java} | 21 ++--
.../org/apache/maven/api/model/package-info.java | 16 ++-
.../maven/api/spi/ExtensibleEnumProvider.java | 35 ++++++-
.../org/apache/maven/api/spi/LanguageProvider.java | 18 ++++
.../apache/maven/api/spi/LifecycleProvider.java | 29 ++++++
.../org/apache/maven/api/spi/ModelTransformer.java | 24 ++++-
.../apache/maven/api/spi/PackagingProvider.java | 24 +++++
.../apache/maven/api/spi/PathScopeProvider.java | 21 ++++
.../apache/maven/api/spi/ProjectScopeProvider.java | 18 ++++
.../java/org/apache/maven/api/spi/SpiService.java | 13 +++
.../org/apache/maven/api/spi/TypeProvider.java | 23 +++++
.../java/org/apache/maven/api/xml/XmlNode.java | 64 ++++++++++++
.../java/org/apache/maven/api/xml/XmlService.java | 45 +++++++++
20 files changed, 679 insertions(+), 20 deletions(-)
diff --git a/api/maven-api-annotations/src/main/java/org/apache/maven/api/annotations/Config.java b/api/maven-api-annotations/src/main/java/org/apache/maven/api/annotations/Config.java
index 08254a59b6..28a3c6edce 100644
--- a/api/maven-api-annotations/src/main/java/org/apache/maven/api/annotations/Config.java
+++ b/api/maven-api-annotations/src/main/java/org/apache/maven/api/annotations/Config.java
@@ -24,18 +24,45 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+/**
+ * Annotation used to mark fields that represent configuration properties.
+ * This annotation provides metadata about how the configuration property
+ * should be handled, including its source, type, default value, and whether it's read-only.
+ *
+ * @since 4.0.0
+ */
@Experimental
@Documented
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.FIELD)
public @interface Config {
+ /**
+ * Specifies the source of the configuration property.
+ *
+ * @return the source of the configuration property, defaults to USER_PROPERTIES
+ */
Source source() default Source.USER_PROPERTIES;
+ /**
+ * Specifies the type of the configuration property.
+ *
+ * @return the fully qualified class name of the property type, defaults to "java.lang.String"
+ */
String type() default "java.lang.String";
+ /**
+ * Specifies the default value of the configuration property.
+ *
+ * @return the default value as a string, defaults to empty string
+ */
String defaultValue() default "";
+ /**
+ * Specifies whether the configuration property is read-only.
+ *
+ * @return true if the property is read-only, false otherwise
+ */
boolean readOnly() default false;
/**
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnums.java b/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnums.java
index b23e85da75..46a24b9b44 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnums.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/ExtensibleEnums.java
@@ -24,28 +24,69 @@
import java.util.Objects;
import java.util.Set;
+/**
+ * Utility class for creating extensible enum implementations.
+ * This class provides factory methods for creating instances of extensible enums
+ * such as Language, PathScope, and ProjectScope.
+ *
+ * @since 4.0.0
+ */
abstract class ExtensibleEnums {
+ /**
+ * Creates a new Language instance with the specified ID.
+ *
+ * @param id the identifier for the language
+ * @return a new Language instance
+ */
static Language language(String id) {
return new DefaultLanguage(id);
}
+ /**
+ * Creates a new PathScope instance with the specified ID, project scope, and dependency scopes.
+ *
+ * @param id the identifier for the path scope
+ * @param projectScope the project scope associated with this path scope
+ * @param dependencyScopes the dependency scopes associated with this path scope
+ * @return a new PathScope instance
+ */
static PathScope pathScope(String id, ProjectScope projectScope, DependencyScope... dependencyScopes) {
return new DefaultPathScope(id, projectScope, dependencyScopes);
}
+ /**
+ * Creates a new ProjectScope instance with the specified ID.
+ *
+ * @param id the identifier for the project scope
+ * @return a new ProjectScope instance
+ */
static ProjectScope projectScope(String id) {
return new DefaultProjectScope(id);
}
+ /**
+ * Base implementation of the ExtensibleEnum interface.
+ * Provides common functionality for all extensible enum implementations.
+ */
private static class DefaultExtensibleEnum implements ExtensibleEnum {
private final String id;
+ /**
+ * Creates a new DefaultExtensibleEnum with the specified ID.
+ *
+ * @param id the identifier for this enum value, must not be null
+ */
DefaultExtensibleEnum(String id) {
this.id = Objects.requireNonNull(id);
}
+ /**
+ * Returns the identifier for this enum value.
+ *
+ * @return the identifier
+ */
public String id() {
return id;
}
@@ -66,10 +107,20 @@ public String toString() {
}
}
+ /**
+ * Implementation of the PathScope interface.
+ */
private static class DefaultPathScope extends DefaultExtensibleEnum implements PathScope {
private final ProjectScope projectScope;
private final Set<DependencyScope> dependencyScopes;
+ /**
+ * Creates a new DefaultPathScope with the specified ID, project scope, and dependency scopes.
+ *
+ * @param id the identifier for this path scope
+ * @param projectScope the project scope associated with this path scope, must not be null
+ * @param dependencyScopes the dependency scopes associated with this path scope, must not be null
+ */
DefaultPathScope(String id, ProjectScope projectScope, DependencyScope... dependencyScopes) {
super(id);
this.projectScope = Objects.requireNonNull(projectScope);
@@ -77,26 +128,52 @@ private static class DefaultPathScope extends DefaultExtensibleEnum implements P
Collections.unmodifiableSet(new HashSet<>(Arrays.asList(Objects.requireNonNull(dependencyScopes))));
}
+ /**
+ * Returns the project scope associated with this path scope.
+ *
+ * @return the project scope
+ */
@Override
public ProjectScope projectScope() {
return projectScope;
}
+ /**
+ * Returns the dependency scopes associated with this path scope.
+ *
+ * @return an unmodifiable set of dependency scopes
+ */
@Override
public Set<DependencyScope> dependencyScopes() {
return dependencyScopes;
}
}
+ /**
+ * Implementation of the ProjectScope interface.
+ */
private static class DefaultProjectScope extends DefaultExtensibleEnum implements ProjectScope {
+ /**
+ * Creates a new DefaultProjectScope with the specified ID.
+ *
+ * @param id the identifier for this project scope
+ */
DefaultProjectScope(String id) {
super(id);
}
}
+ /**
+ * Implementation of the Language interface.
+ */
private static class DefaultLanguage extends DefaultExtensibleEnum implements Language {
+ /**
+ * Creates a new DefaultLanguage with the specified ID.
+ *
+ * @param id the identifier for this language
+ */
DefaultLanguage(String id) {
super(id);
}
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/MavenBuilderException.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/MavenBuilderException.java
index 27292d4f08..a39cb9aa1a 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/MavenBuilderException.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/MavenBuilderException.java
@@ -28,13 +28,30 @@
@Experimental
public abstract class MavenBuilderException extends MavenException {
+ /**
+ * The collection of problems associated with this exception.
+ */
private final ProblemCollector<BuilderProblem> problems;
+ /**
+ * Constructs a new exception with the specified message and cause.
+ * This constructor creates an empty problem collector.
+ *
+ * @param message the detail message
+ * @param cause the cause of this exception
+ */
public MavenBuilderException(String message, Throwable cause) {
super(message, cause);
problems = ProblemCollector.empty();
}
+ /**
+ * Constructs a new exception with the specified message and problems.
+ * The message will be enhanced with details from the problems.
+ *
+ * @param message the detail message
+ * @param problems the collection of problems associated with this exception
+ */
public MavenBuilderException(String message, ProblemCollector<BuilderProblem> problems) {
super(buildMessage(message, problems), null);
this.problems = problems;
@@ -44,6 +61,10 @@ public MavenBuilderException(String message, ProblemCollector<BuilderProblem> pr
* Formats message out of problems: problems are sorted (in natural order of {@link BuilderProblem.Severity})
* and then a list is built. These exceptions are usually thrown in "fatal" cases (and usually prevent Maven
* from starting), and these exceptions may end up very early on output.
+ *
+ * @param message the base message to enhance
+ * @param problems the collection of problems to include in the message
+ * @return a formatted message including details of all problems
*/
protected static String buildMessage(String message, ProblemCollector<BuilderProblem> problems) {
StringBuilder msg = new StringBuilder(message);
@@ -54,6 +75,11 @@ protected static String buildMessage(String message, ProblemCollector<BuilderPro
return msg.toString();
}
+ /**
+ * Returns the problem collector associated with this exception.
+ *
+ * @return the problem collector containing all problems related to this exception
+ */
public ProblemCollector<BuilderProblem> getProblemCollector() {
return problems;
}
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java
index f074182881..07ba7bbe92 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java
@@ -29,15 +29,43 @@
public interface ModelProblem extends BuilderProblem {
/**
- * Version
+ * Enumeration of model versions that can be validated.
+ * These versions correspond to different levels of validation that can be applied
+ * during model building, based on the POM schema version.
+ * <p>
+ * The validation levels are cumulative, with higher versions including all validations
+ * from lower versions plus additional checks specific to that version.
*/
enum Version {
- // based on ModeBuildingResult.validationLevel
+ /**
+ * Base validation level that applies to all POM versions.
+ * Includes fundamental structural validations.
+ */
BASE,
+
+ /**
+ * Validation for Maven 2.0 POM format.
+ */
V20,
+
+ /**
+ * Validation for Maven 3.0 POM format.
+ */
V30,
+
+ /**
+ * Validation for Maven 3.1 POM format.
+ */
V31,
+
+ /**
+ * Validation for Maven 4.0 POM format.
+ */
V40,
+
+ /**
+ * Validation for Maven 4.1 POM format.
+ */
V41
}
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProblemCollector.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProblemCollector.java
index 13d8c35520..6e5a9d29f6 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProblemCollector.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProblemCollector.java
@@ -92,6 +92,9 @@ default int totalProblemsReported() {
/**
* Returns count of problems reported for given severities.
+ *
+ * @param severities the severity levels to count problems for
+ * @return the total count of problems for the specified severities
*/
int problemsReportedFor(BuilderProblem.Severity... severities);
@@ -99,6 +102,8 @@ default int totalProblemsReported() {
* Returns {@code true} if reported problem count exceeded allowed count, and issues were lost. When this
* method returns {@code true}, it means that element count of stream returned by method {@link #problems()}
* and the counter returned by {@link #totalProblemsReported()} are not equal (latter is bigger than former).
+ *
+ * @return true if the problem collector has overflowed and some problems were not preserved
*/
boolean problemsOverflow();
@@ -106,6 +111,7 @@ default int totalProblemsReported() {
* Reports a problem: always maintains the counters, but whether problem is preserved in memory, depends on
* implementation and its configuration.
*
+ * @param problem the problem to report
* @return {@code true} if passed problem is preserved by this call.
*/
boolean reportProblem(P problem);
@@ -126,12 +132,18 @@ default Stream<P> problems() {
/**
* Returns all reported and preserved problems for given severity. Note: counters and element count in this
* stream does not have to be equal.
+ *
+ * @param severity the severity level to get problems for
+ * @return a stream of problems with the specified severity
*/
@Nonnull
Stream<P> problems(BuilderProblem.Severity severity);
/**
- * Creates "empty" problem collector.
+ * Creates an "empty" problem collector that doesn't store any problems.
+ *
+ * @param <P> the type of problem
+ * @return an empty problem collector
*/
@Nonnull
static <P extends BuilderProblem> ProblemCollector<P> empty() {
@@ -159,7 +171,11 @@ public Stream<P> problems(BuilderProblem.Severity severity) {
}
/**
- * Creates new instance of problem collector.
+ * Creates new instance of problem collector with configuration from the provided session.
+ *
+ * @param <P> the type of problem
+ * @param protoSession the session containing configuration for the problem collector
+ * @return a new problem collector instance
*/
@Nonnull
static <P extends BuilderProblem> ProblemCollector<P> create(@Nullable ProtoSession protoSession) {
@@ -173,13 +189,23 @@ static <P extends BuilderProblem> ProblemCollector<P> create(@Nullable ProtoSess
}
/**
- * Creates new instance of problem collector. Visible for testing only.
+ * Creates new instance of problem collector with the specified maximum problem count limit.
+ * Visible for testing only.
+ *
+ * @param <P> the type of problem
+ * @param maxCountLimit the maximum number of problems to preserve
+ * @return a new problem collector instance
*/
@Nonnull
static <P extends BuilderProblem> ProblemCollector<P> create(int maxCountLimit) {
return new Impl<>(maxCountLimit);
}
+ /**
+ * Default implementation of the ProblemCollector interface.
+ *
+ * @param <P> the type of problem
+ */
class Impl<P extends BuilderProblem> implements ProblemCollector<P> {
private final int maxCountLimit;
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilderRequest.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilderRequest.java
index 505098468c..82129b4f1b 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilderRequest.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilderRequest.java
@@ -45,21 +45,67 @@
@Immutable
public interface ProjectBuilderRequest extends Request<Session> {
+ /**
+ * Gets the path to the project to build.
+ * This is typically the path to a pom.xml file or a directory containing a pom.xml file.
+ *
+ * @return an optional containing the path to the project, or empty if not specified
+ */
@Nonnull
Optional<Path> getPath();
+ /**
+ * Gets the source of the project to build.
+ * This is an alternative to specifying a path, allowing the project to be built from
+ * a model source such as a string or input stream.
+ *
+ * @return an optional containing the source of the project, or empty if not specified
+ */
@Nonnull
Optional<Source> getSource();
+ /**
+ * Determines whether a stub model should be allowed when the POM is missing or unreadable.
+ * A stub model contains only minimal information derived from the project's coordinates.
+ *
+ * @return true if a stub model should be allowed, false otherwise
+ */
boolean isAllowStubModel();
+ /**
+ * Determines whether the project builder should recursively build parent/child projects.
+ * When true, the builder will process parent POMs and child modules as needed.
+ *
+ * @return true if the build should be recursive, false otherwise
+ */
boolean isRecursive();
+ /**
+ * Determines whether plugins should be processed during project building.
+ * When true, the builder will process plugin information which may include
+ * resolving plugin dependencies and executing plugin goals that participate in project building.
+ *
+ * @return true if plugins should be processed, false otherwise
+ */
boolean isProcessPlugins();
+ /**
+ * Gets the list of remote repositories to use for resolving dependencies during project building.
+ * These repositories will be used in addition to any repositories defined in the project itself.
+ *
+ * @return the list of remote repositories, or null if not specified
+ */
@Nullable
List<RemoteRepository> getRepositories();
+ /**
+ * Creates a new ProjectBuilderRequest with the specified session and source.
+ *
+ * @param session the Maven session
+ * @param source the source of the project to build
+ * @return a new ProjectBuilderRequest
+ * @throws NullPointerException if session or source is null
+ */
@Nonnull
static ProjectBuilderRequest build(@Nonnull Session session, @Nonnull Source source) {
return builder()
@@ -68,6 +114,14 @@ static ProjectBuilderRequest build(@Nonnull Session session, @Nonnull Source sou
.build();
}
+ /**
+ * Creates a new ProjectBuilderRequest with the specified session and path.
+ *
+ * @param session the Maven session
+ * @param path the path to the project to build
+ * @return a new ProjectBuilderRequest
+ * @throws NullPointerException if session or path is null
+ */
@Nonnull
static ProjectBuilderRequest build(@Nonnull Session session, @Nonnull Path path) {
return builder()
@@ -76,11 +130,20 @@ static ProjectBuilderRequest build(@Nonnull Session session, @Nonnull Path path)
.build();
}
+ /**
+ * Creates a new builder for constructing a ProjectBuilderRequest.
+ *
+ * @return a new ProjectBuilderRequestBuilder
+ */
@Nonnull
static ProjectBuilderRequestBuilder builder() {
return new ProjectBuilderRequestBuilder();
}
+ /**
+ * Builder for creating ProjectBuilderRequest instances.
+ * This builder provides a fluent API for setting the various properties of a request.
+ */
@NotThreadSafe
class ProjectBuilderRequestBuilder {
Session session;
@@ -94,36 +157,84 @@ class ProjectBuilderRequestBuilder {
ProjectBuilderRequestBuilder() {}
+ /**
+ * Sets the Maven session for this request.
+ *
+ * @param session the Maven session
+ * @return this builder instance
+ */
public ProjectBuilderRequestBuilder session(Session session) {
this.session = session;
return this;
}
+ /**
+ * Sets the request trace for this request.
+ * The trace is used for debugging and monitoring purposes.
+ *
+ * @param trace the request trace
+ * @return this builder instance
+ */
public ProjectBuilderRequestBuilder trace(RequestTrace trace) {
this.trace = trace;
return this;
}
+ /**
+ * Sets the path to the project to build.
+ * This is typically the path to a pom.xml file or a directory containing a pom.xml file.
+ *
+ * @param path the path to the project
+ * @return this builder instance
+ */
public ProjectBuilderRequestBuilder path(Path path) {
this.path = path;
return this;
}
+ /**
+ * Sets the source of the project to build.
+ * This is an alternative to specifying a path, allowing the project to be built from
+ * a model source such as a string or input stream.
+ *
+ * @param source the source of the project
+ * @return this builder instance
+ */
public ProjectBuilderRequestBuilder source(Source source) {
this.source = source;
return this;
}
+ /**
+ * Sets whether plugins should be processed during project building.
+ * When true, the builder will process plugin information which may include
+ * resolving plugin dependencies and executing plugin goals that participate in project building.
+ *
+ * @param processPlugins true if plugins should be processed, false otherwise
+ * @return this builder instance
+ */
public ProjectBuilderRequestBuilder processPlugins(boolean processPlugins) {
this.processPlugins = processPlugins;
return this;
}
+ /**
+ * Sets the list of remote repositories to use for resolving dependencies during project building.
+ * These repositories will be used in addition to any repositories defined in the project itself.
+ *
+ * @param repositories the list of remote repositories
+ * @return this builder instance
+ */
public ProjectBuilderRequestBuilder repositories(List<RemoteRepository> repositories) {
this.repositories = repositories;
return this;
}
+ /**
+ * Builds a new ProjectBuilderRequest with the current builder settings.
+ *
+ * @return a new ProjectBuilderRequest instance
+ */
public ProjectBuilderRequest build() {
return new DefaultProjectBuilderRequest(
session, trace, path, source, allowStubModel, recursive, processPlugins, repositories);
diff --git a/api/maven-api-di/src/main/java/org/apache/maven/di/tool/DiIndexProcessor.java b/api/maven-api-di/src/main/java/org/apache/maven/di/tool/DiIndexProcessor.java
index 7452561056..383d2cbc9f 100644
--- a/api/maven-api-di/src/main/java/org/apache/maven/di/tool/DiIndexProcessor.java
+++ b/api/maven-api-di/src/main/java/org/apache/maven/di/tool/DiIndexProcessor.java
@@ -42,12 +42,30 @@
import org.apache.maven.api.di.Named;
+/**
+ * Annotation processor that generates an index file for classes annotated with {@link Named}.
+ * This processor scans for classes with the {@code @Named} annotation and creates a file
+ * at {@code META-INF/maven/org.apache.maven.api.di.Inject} containing the fully qualified
+ * names of these classes.
+ *
+ * @since 4.0.0
+ */
@SupportedAnnotationTypes("org.apache.maven.api.di.Named")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
public class DiIndexProcessor extends AbstractProcessor {
+ /**
+ * Set of fully qualified class names that have been processed and contain the {@link Named} annotation.
+ */
private final Set<String> processedClasses = new HashSet<>();
+ /**
+ * Processes classes with the {@link Named} annotation and generates an index file.
+ *
+ * @param annotations the annotation types requested to be processed
+ * @param roundEnv environment for information about the current and prior round
+ * @return whether or not the set of annotations are claimed by this processor
+ */
@Override
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
logMessage(
@@ -71,6 +89,12 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
return true;
}
+ /**
+ * Gets the fully qualified class name for a type element, including handling inner classes.
+ *
+ * @param typeElement the type element to get the class name for
+ * @return the fully qualified class name
+ */
private String getFullClassName(TypeElement typeElement) {
StringBuilder className = new StringBuilder(typeElement.getSimpleName());
Element enclosingElement = typeElement.getEnclosingElement();
@@ -87,6 +111,13 @@ private String getFullClassName(TypeElement typeElement) {
return className.toString();
}
+ /**
+ * Updates the index file if its content has changed.
+ * The file is created at {@code META-INF/maven/org.apache.maven.api.di.Inject} and contains
+ * the fully qualified names of classes with the {@link Named} annotation.
+ *
+ * @throws IOException if there is an error reading or writing the file
+ */
private void updateFileIfChanged() throws IOException {
String path = "META-INF/maven/org.apache.maven.api.di.Inject";
Set<String> existingClasses = new TreeSet<>(); // Using TreeSet for natural ordering
@@ -136,10 +167,22 @@ private void updateFileIfChanged() throws IOException {
}
}
+ /**
+ * Logs a message to the annotation processing environment.
+ *
+ * @param kind the kind of diagnostic message
+ * @param message the message to log
+ */
private void logMessage(Diagnostic.Kind kind, String message) {
processingEnv.getMessager().printMessage(kind, message);
}
+ /**
+ * Logs an error message with exception details to the annotation processing environment.
+ *
+ * @param message the error message
+ * @param e the exception that occurred
+ */
private void logError(String message, Exception e) {
StringWriter sw = new StringWriter();
PrintWriter pw = new PrintWriter(sw);
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java b/api/maven-api-di/src/main/java/org/apache/maven/di/tool/package-info.java
similarity index 54%
copy from api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
copy to api/maven-api-di/src/main/java/org/apache/maven/di/tool/package-info.java
index 7cbc0ac525..e7409a078d 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
+++ b/api/maven-api-di/src/main/java/org/apache/maven/di/tool/package-info.java
@@ -16,17 +16,18 @@
* specific language governing permissions and limitations
* under the License.
*/
-package org.apache.maven.api.spi;
-
-import org.apache.maven.api.PathScope;
-import org.apache.maven.api.annotations.Consumer;
-import org.apache.maven.api.annotations.Experimental;
-import org.apache.maven.api.di.Named;
/**
+ * Provides tools for processing Maven dependency injection annotations at compile time.
+ * <p>
+ * This package contains annotation processors that generate metadata files used by
+ * the Maven dependency injection system. The main component is the {@link org.apache.maven.di.tool.DiIndexProcessor},
+ * which processes classes annotated with {@link org.apache.maven.api.di.Named} and creates an index file
+ * that allows for efficient discovery of injectable components at runtime.
+ * <p>
+ * The generated index is stored at {@code META-INF/maven/org.apache.maven.api.di.Inject} and contains
+ * the fully qualified names of all classes annotated with {@code @Named}.
+ *
* @since 4.0.0
*/
-@Experimental
-@Consumer
-@Named
-public interface PathScopeProvider extends ExtensibleEnumProvider<PathScope> {}
+package org.apache.maven.di.tool;
diff --git a/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java b/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java
index b74e0ef3b5..450e326cbc 100644
--- a/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java
+++ b/api/maven-api-model/src/main/java/org/apache/maven/api/model/package-info.java
@@ -19,6 +19,20 @@
/**
* Maven Immutable POM (Project Object Model) classes, generated from <code>maven.mdo</code> model.
- * The root class is {@link org.apache.maven.api.model.Model}.
+ * <p>
+ * This package contains the data model classes that represent the structure of Maven POM files.
+ * These classes are immutable to ensure thread safety and prevent unintended modifications.
+ * The root class is {@link org.apache.maven.api.model.Model}, which represents the entire POM.
+ * <p>
+ * Key components include:
+ * <ul>
+ * <li>{@link org.apache.maven.api.model.Model} - The root element of a POM file</li>
+ * <li>{@link org.apache.maven.api.model.Dependency} - Represents a project dependency</li>
+ * <li>{@link org.apache.maven.api.model.Plugin} - Represents a Maven plugin configuration</li>
+ * <li>{@link org.apache.maven.api.model.Build} - Contains build configuration information</li>
+ * <li>{@link org.apache.maven.api.model.Profile} - Represents a build profile for conditional execution</li>
+ * </ul>
+ *
+ * @since 4.0.0
*/
package org.apache.maven.api.model;
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java
index 7efa416d20..5b27389979 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ExtensibleEnumProvider.java
@@ -26,18 +26,47 @@
import org.apache.maven.api.annotations.Nonnull;
/**
- * An SPI interface to extend Maven with a new enum value.
+ * An SPI interface to extend Maven with new enum values for extensible enumerations.
+ * <p>
+ * Maven uses extensible enumerations to allow plugins and extensions to add new values
+ * to various categories like languages, scopes, and packaging types. This interface is the
+ * base for all providers that register such extensions.
+ * <p>
+ * Implementations of this interface are discovered through the Java ServiceLoader mechanism.
+ * Each implementation must be registered in a {@code META-INF/services/} file corresponding
+ * to the specific provider interface being implemented.
+ * <p>
+ * Example implementation for a custom language provider:
+ * <pre>
+ * public class CustomLanguageProvider implements LanguageProvider {
+ * public Collection<Language> provides() {
+ * return Arrays.asList(
+ * language("kotlin"),
+ * language("scala")
+ * );
+ * }
+ * }
+ * </pre>
*
* @param <T> The type of extensible enum to extend
+ * @since 4.0.0
*/
@Experimental
@Consumer
public interface ExtensibleEnumProvider<T extends ExtensibleEnum> extends SpiService {
/**
- * Registers new values for the T extensible enum.
+ * Provides new values for the extensible enum.
+ * <p>
+ * This method is called by Maven during initialization to collect all custom enum values
+ * that should be registered. The returned collection should contain all the enum values
+ * that this provider wants to contribute.
+ * <p>
+ * The values returned by this method should be created using the appropriate factory methods
+ * for the specific enum type, such as {@code language()}, {@code projectScope()}, or
+ * {@code pathScope()}.
*
- * @return a collection of T instances to register
+ * @return a non-null collection of enum instances to register
*/
@Nonnull
Collection<T> provides();
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java
index 7a302507a2..8b25bbafb5 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LanguageProvider.java
@@ -24,6 +24,24 @@
import org.apache.maven.api.di.Named;
/**
+ * Service provider interface for registering custom {@link Language} implementations.
+ * <p>
+ * This interface allows plugins and extensions to define and register additional programming languages
+ * beyond the standard ones provided by Maven. Implementations of this interface will be discovered
+ * through the Java ServiceLoader mechanism and their provided languages will be available
+ * throughout the Maven build process.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class CustomLanguageProvider implements LanguageProvider {
+ * public Collection<Language> provides() {
+ * return Collections.singleton(language("kotlin"));
+ * }
+ * }
+ * </pre>
+ *
+ * @see org.apache.maven.api.Language
+ * @see org.apache.maven.api.spi.ExtensibleEnumProvider
* @since 4.0.0
*/
@Experimental
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LifecycleProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LifecycleProvider.java
index bef5f72dd6..bfa399b158 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LifecycleProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/LifecycleProvider.java
@@ -23,6 +23,35 @@
import org.apache.maven.api.annotations.Experimental;
import org.apache.maven.api.di.Named;
+/**
+ * Service provider interface for registering custom {@link Lifecycle} implementations.
+ * <p>
+ * This interface allows plugins and extensions to define and register additional build lifecycles
+ * beyond the standard ones provided by Maven (like clean, default, site). Lifecycles define a sequence
+ * of phases that can be executed during a build.
+ * <p>
+ * Implementations of this interface will be discovered through the Java ServiceLoader mechanism
+ * and their provided lifecycles will be available throughout the Maven build process.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class CustomLifecycleProvider implements LifecycleProvider {
+ * public Collection<Lifecycle> provides() {
+ * return Collections.singleton(
+ * lifecycle("deploy-docker", Arrays.asList(
+ * "build-image",
+ * "tag-image",
+ * "push-image"
+ * ))
+ * );
+ * }
+ * }
+ * </pre>
+ *
+ * @see org.apache.maven.api.Lifecycle
+ * @see org.apache.maven.api.spi.ExtensibleEnumProvider
+ * @since 4.0.0
+ */
@Experimental
@Consumer
@Named
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformer.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformer.java
index 525b353c6a..50cc193969 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformer.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformer.java
@@ -25,7 +25,29 @@
import org.apache.maven.api.model.Model;
/**
- * Marker interface for model transformers.
+ * Interface for model transformers that can modify Maven project models at different stages of processing.
+ * <p>
+ * Model transformers allow plugins and extensions to modify the POM model during the build process.
+ * Transformations can be applied at three different stages:
+ * <ol>
+ * <li>File model - The raw model as read directly from the file</li>
+ * <li>Raw model - The model after inheritance has been applied</li>
+ * <li>Effective model - The fully processed model with all interpolation and inheritance applied</li>
+ * </ol>
+ * <p>
+ * Implementations of this interface will be discovered through the Java ServiceLoader mechanism
+ * and will be called in sequence during model building.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class CustomModelTransformer implements ModelTransformer {
+ * public Model transformEffectiveModel(Model model) throws ModelTransformerException {
+ * // Add a custom property to all models
+ * model.getProperties().put("custom.timestamp", System.currentTimeMillis());
+ * return model;
+ * }
+ * }
+ * </pre>
*
* @since 4.0.0
*/
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PackagingProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PackagingProvider.java
index 5b12900000..90ac46d9b4 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PackagingProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PackagingProvider.java
@@ -23,6 +23,30 @@
import org.apache.maven.api.annotations.Experimental;
import org.apache.maven.api.di.Named;
+/**
+ * Service provider interface for registering custom {@link Packaging} implementations.
+ * <p>
+ * This interface allows plugins and extensions to define and register additional packaging types
+ * beyond the standard ones provided by Maven (like jar, war, ear, etc.). Implementations of this
+ * interface will be discovered through the Java ServiceLoader mechanism and their provided
+ * packaging types will be available throughout the Maven build process.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class CustomPackagingProvider implements PackagingProvider {
+ * public Collection<Packaging> provides() {
+ * return Arrays.asList(
+ * packaging("docker-image"),
+ * packaging("flatpak")
+ * );
+ * }
+ * }
+ * </pre>
+ *
+ * @see org.apache.maven.api.Packaging
+ * @see org.apache.maven.api.spi.ExtensibleEnumProvider
+ * @since 4.0.0
+ */
@Experimental
@Consumer
@Named
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
index 7cbc0ac525..9b2c4594c9 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/PathScopeProvider.java
@@ -24,6 +24,27 @@
import org.apache.maven.api.di.Named;
/**
+ * Service provider interface for registering custom {@link PathScope} implementations.
+ * <p>
+ * This interface allows plugins and extensions to define and register additional path scopes
+ * beyond the standard ones provided by Maven. Path scopes define how dependencies are used
+ * in different contexts, such as compilation, testing, or runtime.
+ * <p>
+ * Implementations of this interface will be discovered through the Java ServiceLoader mechanism
+ * and their provided path scopes will be available throughout the Maven build process.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class CustomPathScopeProvider implements PathScopeProvider {
+ * public Collection<PathScope> provides() {
+ * return Collections.singleton(pathScope("integration-test",
+ * ProjectScope.TEST, DependencyScope.TEST));
+ * }
+ * }
+ * </pre>
+ *
+ * @see org.apache.maven.api.PathScope
+ * @see org.apache.maven.api.spi.ExtensibleEnumProvider
* @since 4.0.0
*/
@Experimental
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java
index de3146f2ae..a047cab416 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ProjectScopeProvider.java
@@ -24,6 +24,24 @@
import org.apache.maven.api.di.Named;
/**
+ * Service provider interface for registering custom {@link ProjectScope} implementations.
+ * <p>
+ * This interface allows plugins and extensions to define and register additional project scopes
+ * beyond the standard {@link ProjectScope#MAIN} and {@link ProjectScope#TEST} scopes.
+ * Implementations of this interface will be discovered through the Java ServiceLoader mechanism
+ * and their provided project scopes will be available throughout the Maven build process.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class CustomProjectScopeProvider implements ProjectScopeProvider {
+ * public Collection<ProjectScope> provides() {
+ * return Collections.singleton(projectScope("integration-test"));
+ * }
+ * }
+ * </pre>
+ *
+ * @see org.apache.maven.api.ProjectScope
+ * @see org.apache.maven.api.spi.ExtensibleEnumProvider
* @since 4.0.0
*/
@Experimental
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SpiService.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SpiService.java
index ba5259639b..896cd8a29a 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SpiService.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SpiService.java
@@ -23,6 +23,19 @@
/**
* Marker interface to indicate services that can be provided by plugins and extensions.
+ * <p>
+ * This interface serves as the base for all Service Provider Interface (SPI) components in Maven.
+ * Classes implementing this interface can be discovered and loaded by Maven through the
+ * Java ServiceLoader mechanism, allowing plugins and extensions to contribute functionality
+ * to the Maven build process.
+ * <p>
+ * SPI services are typically registered in {@code META-INF/services/} files corresponding to
+ * the specific service interface being implemented.
+ * <p>
+ * All SPI services should be annotated with {@link Consumer} to indicate they are meant to be
+ * implemented by plugins and extensions rather than used by them.
+ *
+ * @since 4.0.0
*/
@Experimental
@Consumer
diff --git a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java
index 990ba9a038..2b8e5994cc 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java
+++ b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.java
@@ -24,6 +24,29 @@
import org.apache.maven.api.di.Named;
/**
+ * Service provider interface for registering custom {@link Type} implementations.
+ * <p>
+ * This interface allows plugins and extensions to define and register additional artifact types
+ * beyond the standard ones provided by Maven (like jar, war, pom, etc.). Types define how artifacts
+ * are handled, including their default extension, classifier, and language.
+ * <p>
+ * Implementations of this interface will be discovered through the Java ServiceLoader mechanism
+ * and their provided types will be available throughout the Maven build process.
+ * <p>
+ * Example usage:
+ * <pre>
+ * public class CustomTypeProvider implements TypeProvider {
+ * public Collection<Type> provides() {
+ * return Arrays.asList(
+ * type("kotlin-library", "jar", "kotlin"),
+ * type("docker-image", "tar.gz", null)
+ * );
+ * }
+ * }
+ * </pre>
+ *
+ * @see org.apache.maven.api.Type
+ * @see org.apache.maven.api.spi.ExtensibleEnumProvider
* @since 4.0.0
*/
@Experimental
diff --git a/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java b/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java
index 3bd93814b6..54a6c3443b 100644
--- a/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java
+++ b/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java
@@ -341,6 +341,13 @@ static Builder newBuilder() {
return new Builder();
}
+ /**
+ * Builder class for creating XmlNode instances.
+ * <p>
+ * This builder provides a fluent API for setting the various properties of an XML node.
+ * All properties are optional except for the node name, which must be set before calling
+ * {@link #build()}.
+ */
class Builder {
private String name;
private String value;
@@ -350,41 +357,98 @@ class Builder {
private List<XmlNode> children;
private Object inputLocation;
+ /**
+ * Sets the name of the XML node.
+ * <p>
+ * This is the only required property that must be set before calling {@link #build()}.
+ *
+ * @param name the name of the XML node
+ * @return this builder instance
+ * @throws NullPointerException if name is null
+ */
public Builder name(String name) {
this.name = name;
return this;
}
+ /**
+ * Sets the text content of the XML node.
+ *
+ * @param value the text content of the XML node
+ * @return this builder instance
+ */
public Builder value(String value) {
this.value = value;
return this;
}
+ /**
+ * Sets the namespace URI of the XML node.
+ *
+ * @param namespaceUri the namespace URI of the XML node
+ * @return this builder instance
+ */
public Builder namespaceUri(String namespaceUri) {
this.namespaceUri = namespaceUri;
return this;
}
+ /**
+ * Sets the namespace prefix of the XML node.
+ *
+ * @param prefix the namespace prefix of the XML node
+ * @return this builder instance
+ */
public Builder prefix(String prefix) {
this.prefix = prefix;
return this;
}
+ /**
+ * Sets the attributes of the XML node.
+ * <p>
+ * The provided map will be copied to ensure immutability.
+ *
+ * @param attributes the map of attribute names to values
+ * @return this builder instance
+ */
public Builder attributes(Map<String, String> attributes) {
this.attributes = attributes;
return this;
}
+ /**
+ * Sets the child nodes of the XML node.
+ * <p>
+ * The provided list will be copied to ensure immutability.
+ *
+ * @param children the list of child nodes
+ * @return this builder instance
+ */
public Builder children(List<XmlNode> children) {
this.children = children;
return this;
}
+ /**
+ * Sets the input location information for the XML node.
+ * <p>
+ * This is typically used for error reporting and debugging purposes.
+ *
+ * @param inputLocation the input location object
+ * @return this builder instance
+ */
public Builder inputLocation(Object inputLocation) {
this.inputLocation = inputLocation;
return this;
}
+ /**
+ * Builds a new XmlNode instance with the current builder settings.
+ *
+ * @return a new immutable XmlNode instance
+ * @throws NullPointerException if name has not been set
+ */
public XmlNode build() {
return new Impl(prefix, namespaceUri, name, value, attributes, children, inputLocation);
}
diff --git a/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlService.java b/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlService.java
index 0dd1e30dfc..e6735e255f 100644
--- a/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlService.java
+++ b/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlService.java
@@ -176,18 +176,63 @@ public interface InputLocationBuilder {
Object toInputLocation(XMLStreamReader parser);
}
+ /**
+ * Implementation method for reading an XML node from an input stream.
+ *
+ * @param input the input stream to read from
+ * @param locationBuilder optional builder for creating input location objects
+ * @return the parsed XML node
+ * @throws XMLStreamException if there is an error parsing the XML
+ */
protected abstract XmlNode doRead(InputStream input, InputLocationBuilder locationBuilder)
throws XMLStreamException;
+ /**
+ * Implementation method for reading an XML node from a reader.
+ *
+ * @param reader the reader to read from
+ * @param locationBuilder optional builder for creating input location objects
+ * @return the parsed XML node
+ * @throws XMLStreamException if there is an error parsing the XML
+ */
protected abstract XmlNode doRead(Reader reader, InputLocationBuilder locationBuilder) throws XMLStreamException;
+ /**
+ * Implementation method for reading an XML node from an XMLStreamReader.
+ *
+ * @param reader the XML stream reader to read from
+ * @param locationBuilder optional builder for creating input location objects
+ * @return the parsed XML node
+ * @throws XMLStreamException if there is an error parsing the XML
+ */
protected abstract XmlNode doRead(XMLStreamReader reader, InputLocationBuilder locationBuilder)
throws XMLStreamException;
+ /**
+ * Implementation method for writing an XML node to a writer.
+ *
+ * @param node the XML node to write
+ * @param writer the writer to write to
+ * @throws IOException if there is an error writing the XML
+ */
protected abstract void doWrite(XmlNode node, Writer writer) throws IOException;
+ /**
+ * Implementation method for merging two XML nodes.
+ *
+ * @param dominant the dominant (higher priority) XML node
+ * @param recessive the recessive (lower priority) XML node
+ * @param childMergeOverride optional override for the child merge mode
+ * @return the merged XML node, or null if both inputs are null
+ */
protected abstract XmlNode doMerge(XmlNode dominant, XmlNode recessive, Boolean childMergeOverride);
+ /**
+ * Gets the singleton instance of the XmlService.
+ *
+ * @return the XmlService instance
+ * @throws IllegalStateException if no implementation is found
+ */
private static XmlService getService() {
return Holder.INSTANCE;
}