This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new 1614e535ad Improve Javadoc across Maven API modules (#2218)
1614e535ad is described below
commit 1614e535adea8435fabdef897d28f1d72a106eb3
Author: Guillaume Nodet <gno...@gmail.com>
AuthorDate: Thu Apr 3 15:33:59 2025 +0200
Improve Javadoc across Maven API modules (#2218)
- Add missing class-level and method-level Javadoc to various classes in
api/ subprojects
- Add missing type parameter Javadoc to parameterized classes
- Fix Javadoc errors by escaping angle brackets in code examples
- Fix Javadoc reference errors in TypeRegistry
- Remove cross-module references in TypeRegistry Javadoc
- Enhance javadoc for Config.Source enum to clarify when properties are
evaluated
- 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 | 53 +++++++++-
.../java/org/apache/maven/api/ExtensibleEnums.java | 77 ++++++++++++++
.../main/java/org/apache/maven/api/Lifecycle.java | 83 ++++++++++++++-
.../maven/api/services/ExtensibleEnumRegistry.java | 10 ++
.../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 +++++++++++++++++++++
.../apache/maven/api/services/TypeRegistry.java | 3 +
.../org/apache/maven/di/tool/DiIndexProcessor.java | 43 ++++++++
.../org/apache/maven/di/tool/package-info.java} | 21 ++--
.../org/apache/maven/api/model/InputLocation.java | 8 +-
.../org/apache/maven/api/model/InputSource.java | 8 +-
.../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 +++++++++
25 files changed, 809 insertions(+), 28 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..493b6ceebf 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,34 +24,79 @@
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, which determines
when and where the property
+ * will be read from or set for consumption in the Maven build lifecycle.
+ *
+ * The source indicates whether the property is:
+ * - Set by Maven itself at startup (SYSTEM_PROPERTIES)
+ * - Configured by users through external means like CLI options
(USER_PROPERTIES)
+ * - Defined in the project's POM file (MODEL)
+ *
+ * @return the source of the configuration property, defaults to
USER_PROPERTIES
+ * @see Source for detailed information about each source type and when
it's used
+ */
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;
/**
- * Property source.
+ * Property source, which determines when and where the property will be
read from or set for consumption.
+ * The source indicates the timing of property evaluation in the Maven
build lifecycle and the location
+ * where the property value is defined.
*/
enum Source {
/**
- * Maven system properties.
+ * Maven system properties. These properties are evaluated very early
during the boot process,
+ * typically set by Maven itself and flagged as readOnly=true. System
properties are initialized
+ * before the build starts and are available throughout the entire
Maven execution. They are used
+ * for core Maven functionality that needs to be established at
startup.
*/
SYSTEM_PROPERTIES,
/**
- * Maven user properties.
+ * Maven user properties. These are properties that users configure
through various means such as
+ * maven.properties files, maven.config files, command line parameters
(-D flags), settings.xml,
+ * or environment variables. They are evaluated during the build
process and represent the primary
+ * way for users to customize Maven's behavior at runtime.
*/
USER_PROPERTIES,
/**
- * Project properties.
+ * Project model properties. These properties are defined in the
project's POM file (pom.xml) and
+ * are read from the project model during the build. They represent
build-time configuration that
+ * is specific to the project and is stored with the project
definition itself rather than in
+ * external configuration.
*/
MODEL
}
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/Lifecycle.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Lifecycle.java
index b1d3a4db32..6f4d019839 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Lifecycle.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Lifecycle.java
@@ -65,7 +65,9 @@ public interface Lifecycle extends ExtensibleEnum {
String id();
/**
- * Collection of main phases for this lifecycle
+ * Collection of main phases for this lifecycle.
+ *
+ * @return the collection of top-level phases in this lifecycle
*/
Collection<Phase> phases();
@@ -73,6 +75,8 @@ public interface Lifecycle extends ExtensibleEnum {
* Collection of main phases for this lifecycle used with the Maven 3
builders.
* Those builders does not operate on a graph, but on the list and expect
a slightly
* different ordering (mainly unit test being executed before packaging).
+ *
+ * @return the collection of phases in Maven 3 compatible ordering
*/
default Collection<Phase> v3phases() {
return phases();
@@ -80,13 +84,18 @@ default Collection<Phase> v3phases() {
/**
* Stream of phases containing all child phases recursively.
+ *
+ * @return a stream of all phases in this lifecycle, including nested
phases
*/
default Stream<Phase> allPhases() {
return phases().stream().flatMap(Phase::allPhases);
}
/**
- * Collection of aliases.
+ * Collection of aliases for this lifecycle.
+ * Aliases map Maven 3 phase names to their Maven 4 equivalents.
+ *
+ * @return the collection of phase aliases
*/
Collection<Alias> aliases();
@@ -122,12 +131,27 @@ interface Phase {
String DEPLOY = "deploy";
String CLEAN = "clean";
+ /**
+ * Returns the name of this phase.
+ *
+ * @return the phase name
+ */
@Nonnull
String name();
+ /**
+ * Returns the list of plugins bound to this phase.
+ *
+ * @return the list of plugins
+ */
@Nonnull
List<Plugin> plugins();
+ /**
+ * Returns the collection of links from this phase to other phases.
+ *
+ * @return the collection of links
+ */
@Nonnull
Collection<Link> links();
@@ -137,6 +161,11 @@ interface Phase {
@Nonnull
List<Phase> phases();
+ /**
+ * Returns a stream of all phases, including this phase and all nested
phases.
+ *
+ * @return a stream of all phases
+ */
@Nonnull
Stream<Phase> allPhases();
}
@@ -146,8 +175,18 @@ interface Phase {
* to dynamic phases in Maven 4.
*/
interface Alias {
+ /**
+ * Returns the Maven 3 phase name.
+ *
+ * @return the Maven 3 phase name
+ */
String v3Phase();
+ /**
+ * Returns the Maven 4 phase name.
+ *
+ * @return the Maven 4 phase name
+ */
String v4Phase();
}
@@ -162,8 +201,18 @@ enum Kind {
AFTER
}
+ /**
+ * Returns the kind of link (BEFORE or AFTER).
+ *
+ * @return the link kind
+ */
Kind kind();
+ /**
+ * Returns the pointer to the target phase.
+ *
+ * @return the phase pointer
+ */
Pointer pointer();
}
@@ -174,26 +223,56 @@ enum Type {
CHILDREN
}
+ /**
+ * Returns the name of the target phase.
+ *
+ * @return the phase name
+ */
String phase();
+ /**
+ * Returns the type of pointer (PROJECT, DEPENDENCIES, or CHILDREN).
+ *
+ * @return the pointer type
+ */
Type type();
}
interface PhasePointer extends Pointer {
+ /**
+ * Returns the type of pointer, which is always PROJECT for a
PhasePointer.
+ *
+ * @return the PROJECT pointer type
+ */
default Type type() {
return Type.PROJECT;
}
}
interface DependenciesPointer extends Pointer {
+ /**
+ * Returns the dependency scope this pointer applies to.
+ *
+ * @return the dependency scope, or "all" if not specified
+ */
String scope(); // default: all
+ /**
+ * Returns the type of pointer, which is always DEPENDENCIES for a
DependenciesPointer.
+ *
+ * @return the DEPENDENCIES pointer type
+ */
default Type type() {
return Type.DEPENDENCIES;
}
}
interface ChildrenPointer extends Pointer {
+ /**
+ * Returns the type of pointer, which is always CHILDREN for a
ChildrenPointer.
+ *
+ * @return the CHILDREN pointer type
+ */
default Type type() {
return Type.CHILDREN;
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
index 5d391e513f..06d9726cac 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ExtensibleEnumRegistry.java
@@ -24,6 +24,16 @@
import org.apache.maven.api.Service;
import org.apache.maven.api.annotations.Nonnull;
+/**
+ * Registry for extensible enum values that allows looking up enum instances
by their identifiers.
+ * <p>
+ * This service provides access to all registered instances of a specific
extensible enum type.
+ * It's used internally by Maven and can also be used by plugins and
extensions to access
+ * custom enum values that have been registered through SPI providers.
+ *
+ * @param <T> the specific type of extensible enum managed by this registry
+ * @since 4.0.0
+ */
public interface ExtensibleEnumRegistry<T extends ExtensibleEnum> extends
Service {
@Nonnull
Optional<T> lookup(@Nonnull String 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-core/src/main/java/org/apache/maven/api/services/TypeRegistry.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/TypeRegistry.java
index 8c2c872a17..a8820de485 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/TypeRegistry.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/TypeRegistry.java
@@ -24,6 +24,9 @@
/**
* Access to {@link Type} registry.
+ * <p>
+ * This registry provides access to all registered artifact types, both
standard types
+ * provided by Maven and custom types registered through SPI provider
implementations.
*
* @since 4.0.0
*/
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/TypeProvider.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/TypeProvider.java
copy to
api/maven-api-di/src/main/java/org/apache/maven/di/tool/package-info.java
index 990ba9a038..e7409a078d 100644
--- a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/TypeProvider.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.Type;
-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 TypeProvider extends ExtensibleEnumProvider<Type> {}
+package org.apache.maven.di.tool;
diff --git
a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java
b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java
index e4e2acf237..60f50addbe 100644
---
a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java
+++
b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputLocation.java
@@ -25,7 +25,13 @@
import java.util.Map;
/**
- * Class InputLocation.
+ * Represents the location of an element within a model source file.
+ * <p>
+ * This class tracks the line and column numbers of elements in source files
like POM files.
+ * It's used for error reporting and debugging to help identify where specific
model elements
+ * are defined in the source files.
+ *
+ * @since 4.0.0
*/
public class InputLocation implements Serializable, InputLocationTracker {
private final int lineNumber;
diff --git
a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java
b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java
index 1d1998c6b4..f4d5e7fc67 100644
---
a/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java
+++
b/api/maven-api-model/src/main/java/org/apache/maven/api/model/InputSource.java
@@ -26,7 +26,13 @@
import java.util.stream.Stream;
/**
- * Class InputSource.
+ * Represents the source of a model input, such as a POM file.
+ * <p>
+ * This class tracks the origin of model elements, including their location in
source files
+ * and relationships between imported models. It's used for error reporting
and debugging
+ * to help identify where specific model elements came from.
+ *
+ * @since 4.0.0
*/
public class InputSource implements Serializable {
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..46cb8881c8 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..7a2f77068f 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..d37a327e52 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..2e2af56e82 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..7d618ae110 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..bcd071e9be 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..1aa5bf78d8 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;
}
