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 81b5ef2acb docs: add missing javadoc to public API classes and methods
(#13501)
81b5ef2acb is described below
commit 81b5ef2acb5ee40f89fcf563af2053192de182ad
Author: Guillaume Nodet <[email protected]>
AuthorDate: Wed Nov 4 15:33:29 2026 +0100
docs: add missing javadoc to public API classes and methods (#13501)
* docs: add missing javadoc to public API classes and methods
Add javadoc comments to all public types and methods across the
api/* modules that were missing documentation.
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
* docs: add descriptions to stub class-level javadoc
15 classes had javadoc blocks containing only @since tags
with no actual description. Add a meaningful summary sentence
to each.
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
* docs: remove duplicated javadoc on deprecated bridge methods in Exclusion
* docs: revert @Deprecated on XmlNode.merge(3-arg) — to be done in follow-up
---------
Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
---
.../maven/api/cli/logging/AccumulatingLogger.java | 2 +
.../java/org/apache/maven/api/DependencyScope.java | 8 +++
.../main/java/org/apache/maven/api/Exclusion.java | 6 ++
.../java/org/apache/maven/api/JavaToolchain.java | 10 +++
.../main/java/org/apache/maven/api/PathScope.java | 10 +++
.../src/main/java/org/apache/maven/api/Plugin.java | 35 +++++++++
.../apache/maven/api/plugin/LifecycleProvider.java | 5 ++
.../main/java/org/apache/maven/api/plugin/Log.java | 52 ++++++++++++++
.../org/apache/maven/api/plugin/MojoException.java | 10 +++
.../api/services/ArtifactCoordinatesFactory.java | 29 ++++++++
.../ArtifactCoordinatesFactoryRequest.java | 45 ++++++++++++
.../api/services/ArtifactDeployerRequest.java | 12 ++++
.../apache/maven/api/services/ArtifactFactory.java | 44 ++++++++++++
.../maven/api/services/ArtifactFactoryRequest.java | 31 +++++++-
.../api/services/ArtifactInstallerException.java | 2 +
.../api/services/ArtifactInstallerRequest.java | 9 +++
.../apache/maven/api/services/ArtifactManager.java | 1 +
.../api/services/ArtifactResolverException.java | 4 +-
.../api/services/ArtifactResolverRequest.java | 17 +++++
.../org/apache/maven/api/services/BaseRequest.java | 2 +
.../ChecksumAlgorithmServiceException.java | 5 ++
.../api/services/DependencyCoordinatesFactory.java | 37 ++++++++++
.../DependencyCoordinatesFactoryRequest.java | 32 +++++++++
.../maven/api/services/DependencyResolver.java | 68 ++++++++++++++++++
.../api/services/DependencyResolverException.java | 5 ++
.../api/services/DependencyResolverRequest.java | 77 ++++++++++++++++++++
.../maven/api/services/ExtensibleEnumRegistry.java | 13 ++++
.../apache/maven/api/services/Interpolator.java | 7 ++
.../maven/api/services/LanguageRegistry.java | 5 ++
.../maven/api/services/LifecycleRegistry.java | 20 ++++++
.../java/org/apache/maven/api/services/Lookup.java | 8 +++
.../apache/maven/api/services/MessageBuilder.java | 21 ++++++
.../apache/maven/api/services/ModelBuilder.java | 30 ++++++++
.../maven/api/services/ModelBuilderRequest.java | 62 ++++++++++++++++
.../maven/api/services/ModelProblemCollector.java | 82 ++++++++++++++++++++++
.../maven/api/services/PackagingRegistry.java | 5 ++
.../maven/api/services/PathScopeRegistry.java | 5 ++
.../apache/maven/api/services/ProjectBuilder.java | 2 +
.../maven/api/services/SettingsBuilderRequest.java | 40 +++++++++++
.../maven/api/services/SettingsBuilderResult.java | 2 +
.../api/services/ToolchainsBuilderRequest.java | 23 ++++++
.../api/services/ToolchainsBuilderResult.java | 2 +
.../api/services/TransportProviderException.java | 2 +
.../maven/api/services/VersionRangeResolver.java | 7 ++
.../services/VersionRangeResolverException.java | 2 +
.../api/services/VersionResolverException.java | 2 +
.../maven/api/services/VersionResolverRequest.java | 26 +++++++
.../maven/api/services/VersionResolverResult.java | 17 +++++
.../apache/maven/api/services/xml/Location.java | 6 ++
.../apache/maven/api/services/xml/XmlFactory.java | 79 +++++++++++++++++++++
.../maven/api/services/xml/XmlReaderException.java | 5 ++
.../maven/api/services/xml/XmlReaderRequest.java | 55 +++++++++++++++
.../maven/api/services/xml/XmlWriterException.java | 5 ++
.../maven/api/services/xml/XmlWriterRequest.java | 32 +++++++++
.../maven/api/services/model/ModelResolver.java | 7 ++
.../maven/api/services/model/RootDetector.java | 6 ++
.../maven/api/services/model/RootLocator.java | 19 +++++
.../apache/maven/api/spi/ModelParserException.java | 16 +++++
.../maven/api/spi/ModelTransformerException.java | 5 ++
.../maven/api/spi/SettingsParserException.java | 10 +++
60 files changed, 1184 insertions(+), 2 deletions(-)
diff --git
a/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
b/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
index 013e73a81a..aa4c1d8f96 100644
---
a/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
+++
b/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/logging/AccumulatingLogger.java
@@ -33,6 +33,7 @@
public class AccumulatingLogger implements Logger {
private final AtomicReference<List<Entry>> entries = new
AtomicReference<>(new CopyOnWriteArrayList<>());
+ /** {@inheritDoc} */
@Override
public void log(Level level, String message, Throwable error) {
requireNonNull(level, "level");
@@ -40,6 +41,7 @@ public void log(Level level, String message, Throwable error)
{
entries.get().add(new Entry(level, message, error));
}
+ /** {@inheritDoc} */
@Override
public List<Entry> drain() {
return entries.getAndSet(new CopyOnWriteArrayList<>());
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
index f9f788e003..311f1ec39e 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java
@@ -129,10 +129,18 @@ public String id() {
return id;
}
+ /**
+ * {@return whether dependencies in this scope are included transitively}.
+ */
public boolean isTransitive() {
return transitive;
}
+ /**
+ * {@return whether this scope's {@linkplain #id() id} equals the given
identifier}.
+ *
+ * @param id the identifier to compare against
+ */
public boolean is(String id) {
return id().equals(id);
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
index 66b8a7f4c4..586d5718c0 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
@@ -29,6 +29,9 @@
*/
@Experimental
public interface Exclusion {
+ /**
+ * {@return the group identifier of the excluded dependency, or {@code
null} for a wildcard}.
+ */
@Nullable
String groupId();
@@ -41,6 +44,9 @@ default String getGroupId() {
return groupId();
}
+ /**
+ * {@return the artifact identifier of the excluded dependency, or {@code
null} for a wildcard}.
+ */
@Nullable
String artifactId();
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java
index 5357af9ac4..a64074ea00 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/JavaToolchain.java
@@ -41,7 +41,17 @@
@Experimental
public interface JavaToolchain extends Toolchain {
+ /**
+ * Returns the path to the Java home directory for this toolchain.
+ *
+ * @return the Java home path
+ */
String getJavaHome();
+ /**
+ * Returns the Java version provided by this toolchain.
+ *
+ * @return the Java version
+ */
Version getJavaVersion();
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java
index bd8a6f1bf5..34c9158cc6 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java
@@ -47,9 +47,19 @@
public interface PathScope extends ExtensibleEnum {
// TODO: what if I simply want all dependencies ?
+ /**
+ * Returns the project scope associated with this path scope.
+ *
+ * @return the project scope, never {@code null}
+ */
@Nonnull
ProjectScope projectScope();
+ /**
+ * Returns the set of dependency scopes included in this path scope.
+ *
+ * @return the dependency scopes, never {@code null}
+ */
@Nonnull
Set<DependencyScope> dependencyScopes();
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java
index 049f7dd48f..356ec1fe18 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Plugin.java
@@ -36,26 +36,61 @@
@Experimental
public interface Plugin {
+ /**
+ * Returns the POM model element for this plugin.
+ *
+ * @return the plugin model, or {@code null} if not available
+ */
@Nullable
org.apache.maven.api.model.Plugin getModel();
+ /**
+ * Returns the plugin descriptor containing metadata about goals and
parameters.
+ *
+ * @return the plugin descriptor, never {@code null}
+ */
@Nonnull
PluginDescriptor getDescriptor();
+ /**
+ * Returns the custom lifecycles defined by this plugin.
+ *
+ * @return the list of lifecycles, never {@code null}
+ */
@Nonnull
List<Lifecycle> getLifecycles();
+ /**
+ * Returns the class loader used to load this plugin's classes.
+ *
+ * @return the class loader, never {@code null}
+ */
@Nonnull
ClassLoader getClassLoader();
+ /**
+ * Returns the artifact for this plugin.
+ *
+ * @return the plugin artifact, or {@code null} if not available
+ */
@Nullable
Artifact getArtifact();
+ /**
+ * Returns the collection of dependencies for this plugin.
+ *
+ * @return the plugin dependencies, never {@code null}
+ */
@Nonnull
default Collection<Dependency> getDependencies() {
return getDependenciesMap().values();
}
+ /**
+ * Returns the dependencies for this plugin, keyed by their string
identifier.
+ *
+ * @return the dependency map, never {@code null}
+ */
@Nonnull
Map<String, Dependency> getDependenciesMap();
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
index 1f0d61b2c4..7b39ffdfb2 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/LifecycleProvider.java
@@ -37,5 +37,10 @@
@Consumer
public interface LifecycleProvider {
+ /**
+ * Returns the custom lifecycle definitions provided by this plugin.
+ *
+ * @return the list of lifecycles, never {@code null}
+ */
List<Lifecycle> getLifecycles();
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
index 23175d07b1..54eeb10b7e 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
@@ -137,8 +137,21 @@ default void trace(Supplier<String> content, Throwable
error) {}
*/
void debug(Throwable error);
+ /**
+ * Sends a lazily-computed message at the <b>debug</b> error level.
+ * The supplier is only evaluated if debug is enabled.
+ *
+ * @param content the message supplier
+ */
void debug(Supplier<String> content);
+ /**
+ * Sends a lazily-computed message (and accompanying exception) at the
<b>debug</b> error level.
+ * The supplier is only evaluated if debug is enabled.
+ *
+ * @param content the message supplier
+ * @param error the error that caused this log
+ */
void debug(Supplier<String> content, Throwable error);
/**
@@ -170,8 +183,21 @@ default void trace(Supplier<String> content, Throwable
error) {}
*/
void info(Throwable error);
+ /**
+ * Sends a lazily-computed message at the <b>info</b> error level.
+ * The supplier is only evaluated if info is enabled.
+ *
+ * @param content the message supplier
+ */
void info(Supplier<String> content);
+ /**
+ * Sends a lazily-computed message (and accompanying exception) at the
<b>info</b> error level.
+ * The supplier is only evaluated if info is enabled.
+ *
+ * @param content the message supplier
+ * @param error the error that caused this log
+ */
void info(Supplier<String> content, Throwable error);
/**
@@ -203,8 +229,21 @@ default void trace(Supplier<String> content, Throwable
error) {}
*/
void warn(Throwable error);
+ /**
+ * Sends a lazily-computed message at the <b>warn</b> error level.
+ * The supplier is only evaluated if warn is enabled.
+ *
+ * @param content the message supplier
+ */
void warn(Supplier<String> content);
+ /**
+ * Sends a lazily-computed message (and accompanying exception) at the
<b>warn</b> error level.
+ * The supplier is only evaluated if warn is enabled.
+ *
+ * @param content the message supplier
+ * @param error the error that caused this log
+ */
void warn(Supplier<String> content, Throwable error);
/**
@@ -236,8 +275,21 @@ default void trace(Supplier<String> content, Throwable
error) {}
*/
void error(Throwable error);
+ /**
+ * Sends a lazily-computed message at the <b>error</b> error level.
+ * The supplier is only evaluated if error is enabled.
+ *
+ * @param content the message supplier
+ */
void error(Supplier<String> content);
+ /**
+ * Sends a lazily-computed message (and accompanying exception) at the
<b>error</b> error level.
+ * The supplier is only evaluated if error is enabled.
+ *
+ * @param content the message supplier
+ * @param error the error that caused this log
+ */
void error(Supplier<String> content, Throwable error);
/**
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
index 2d4b976cee..e43792a457 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/MojoException.java
@@ -68,10 +68,20 @@ public MojoException(Throwable cause) {
super(cause);
}
+ /**
+ * Returns the long message for this exception, providing additional
detail beyond the short message.
+ *
+ * @return the long message, or {@code null} if not set
+ */
public String getLongMessage() {
return longMessage;
}
+ /**
+ * Returns the source of this exception, typically the mojo or component
that caused it.
+ *
+ * @return the source object, or {@code null} if not set
+ */
public Object getSource() {
return source;
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
index 8dce1ed48f..3b8c54131d 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactory.java
@@ -57,12 +57,34 @@ default ArtifactCoordinates create(@Nonnull Session
session, @Nonnull String coo
return create(ArtifactCoordinatesFactoryRequest.build(session,
coordinatesString));
}
+ /**
+ * Creates artifact coordinates from individual components.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param extension the file extension
+ * @return an {@code ArtifactCoordinates}, never {@code null}
+ */
@Nonnull
default ArtifactCoordinates create(
@Nonnull Session session, String groupId, String artifactId,
String version, String extension) {
return create(ArtifactCoordinatesFactoryRequest.build(session,
groupId, artifactId, version, extension));
}
+ /**
+ * Creates artifact coordinates from individual components including
classifier and type.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param classifier the classifier, may be {@code null}
+ * @param extension the file extension, may be {@code null}
+ * @param type the artifact type, may be {@code null}
+ * @return an {@code ArtifactCoordinates}, never {@code null}
+ */
@Nonnull
default ArtifactCoordinates create(
@Nonnull Session session,
@@ -76,6 +98,13 @@ default ArtifactCoordinates create(
session, groupId, artifactId, version, classifier, extension,
type));
}
+ /**
+ * Creates artifact coordinates from an existing artifact.
+ *
+ * @param session the session
+ * @param artifact the artifact to derive coordinates from
+ * @return an {@code ArtifactCoordinates}, never {@code null}
+ */
@Nonnull
default ArtifactCoordinates create(@Nonnull Session session, Artifact
artifact) {
return create(ArtifactCoordinatesFactoryRequest.build(
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
index 0c7ae82767..8b5dc26f7d 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactCoordinatesFactoryRequest.java
@@ -38,20 +38,37 @@
@Immutable
public interface ArtifactCoordinatesFactoryRequest extends Request<Session> {
+ /** @return the group identifier */
String getGroupId();
+ /** @return the artifact identifier */
String getArtifactId();
+ /** @return the version */
String getVersion();
+ /** @return the classifier, may be {@code null} */
String getClassifier();
+ /** @return the file extension, may be {@code null} */
String getExtension();
+ /** @return the artifact type, may be {@code null} */
String getType();
+ /** @return the coordinate string in the format {@code
groupId:artifactId[:extension[:classifier]]:version}, may be {@code null} */
String getCoordinatesString();
+ /**
+ * Builds a request from individual coordinate components.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param extension the file extension
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactCoordinatesFactoryRequest build(
@Nonnull Session session, String groupId, String artifactId,
String version, String extension) {
@@ -64,6 +81,18 @@ static ArtifactCoordinatesFactoryRequest build(
.build();
}
+ /**
+ * Builds a request from individual coordinate components including
classifier and type.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param classifier the classifier
+ * @param extension the file extension
+ * @param type the artifact type
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactCoordinatesFactoryRequest build(
@Nonnull Session session,
@@ -84,6 +113,14 @@ static ArtifactCoordinatesFactoryRequest build(
.build();
}
+ /**
+ * Builds a request from a coordinate string formatted as
+ * {@code <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>}.
+ *
+ * @param session the session
+ * @param coordinateString the coordinate string
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactCoordinatesFactoryRequest build(@Nonnull Session session,
@Nonnull String coordinateString) {
return ArtifactCoordinatesFactoryRequest.builder()
@@ -92,6 +129,13 @@ static ArtifactCoordinatesFactoryRequest build(@Nonnull
Session session, @Nonnul
.build();
}
+ /**
+ * Builds a request from existing artifact coordinates.
+ *
+ * @param session the session
+ * @param coordinates the artifact coordinates
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactCoordinatesFactoryRequest build(@Nonnull Session session,
@Nonnull ArtifactCoordinates coordinates) {
return ArtifactCoordinatesFactoryRequest.builder()
@@ -104,6 +148,7 @@ static ArtifactCoordinatesFactoryRequest build(@Nonnull
Session session, @Nonnul
.build();
}
+ /** @return a new builder instance */
static ArtifactFactoryRequestBuilder builder() {
return new ArtifactFactoryRequestBuilder();
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
index 8d54d882c0..dacb2cf765 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactDeployerRequest.java
@@ -41,19 +41,31 @@
@Immutable
public interface ArtifactDeployerRequest extends Request<Session> {
+ /** @return the remote repository to deploy to, never {@code null} */
@Nonnull
RemoteRepository getRepository();
+ /** @return the artifacts to deploy, never {@code null} */
@Nonnull
Collection<ProducedArtifact> getArtifacts();
+ /** @return the number of times to retry a failed deployment */
int getRetryFailedDeploymentCount();
+ /** @return a new builder instance */
@Nonnull
static ArtifactDeployerRequestBuilder builder() {
return new ArtifactDeployerRequestBuilder();
}
+ /**
+ * Builds a request to deploy artifacts to a remote repository.
+ *
+ * @param session the session
+ * @param repository the target remote repository
+ * @param artifacts the artifacts to deploy
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactDeployerRequest build(
@Nonnull Session session,
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
index da77fc2d52..ae0f127494 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactory.java
@@ -43,12 +43,34 @@ public interface ArtifactFactory extends Service {
@Nonnull
Artifact create(@Nonnull ArtifactFactoryRequest request);
+ /**
+ * Creates an artifact from individual components.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param extension the file extension
+ * @return an {@code Artifact}, never {@code null}
+ */
@Nonnull
default Artifact create(
@Nonnull Session session, String groupId, String artifactId,
String version, String extension) {
return create(ArtifactFactoryRequest.build(session, groupId,
artifactId, version, extension));
}
+ /**
+ * Creates an artifact from individual components including classifier and
type.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param classifier the classifier, may be {@code null}
+ * @param extension the file extension, may be {@code null}
+ * @param type the artifact type, may be {@code null}
+ * @return an {@code Artifact}, never {@code null}
+ */
@Nonnull
default Artifact create(
@Nonnull Session session,
@@ -71,12 +93,34 @@ default Artifact create(
@Nonnull
ProducedArtifact createProduced(@Nonnull ArtifactFactoryRequest request);
+ /**
+ * Creates a produced artifact from individual components.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param extension the file extension
+ * @return a {@code ProducedArtifact}, never {@code null}
+ */
@Nonnull
default ProducedArtifact createProduced(
@Nonnull Session session, String groupId, String artifactId,
String version, String extension) {
return createProduced(ArtifactFactoryRequest.build(session, groupId,
artifactId, version, extension));
}
+ /**
+ * Creates a produced artifact from individual components including
classifier and type.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param classifier the classifier, may be {@code null}
+ * @param extension the file extension, may be {@code null}
+ * @param type the artifact type, may be {@code null}
+ * @return a {@code ProducedArtifact}, never {@code null}
+ */
@Nonnull
default ProducedArtifact createProduced(
@Nonnull Session session,
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
index 0d97922374..1205b0d4d1 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactFactoryRequest.java
@@ -30,7 +30,7 @@
import static java.util.Objects.requireNonNull;
/**
- *
+ * Request for creating an {@link org.apache.maven.api.Artifact} from
individual coordinate components.
*
* @since 4.0.0
*/
@@ -38,18 +38,34 @@
@Immutable
public interface ArtifactFactoryRequest extends Request<Session> {
+ /** @return the group identifier */
String getGroupId();
+ /** @return the artifact identifier */
String getArtifactId();
+ /** @return the version */
String getVersion();
+ /** @return the classifier, may be {@code null} */
String getClassifier();
+ /** @return the file extension, may be {@code null} */
String getExtension();
+ /** @return the artifact type, may be {@code null} */
String getType();
+ /**
+ * Builds a request from individual components.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param extension the file extension
+ * @return a new request
+ */
static ArtifactFactoryRequest build(
Session session, String groupId, String artifactId, String
version, String extension) {
return ArtifactFactoryRequest.builder()
@@ -61,6 +77,18 @@ static ArtifactFactoryRequest build(
.build();
}
+ /**
+ * Builds a request from individual components including classifier and
type.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param classifier the classifier
+ * @param extension the file extension
+ * @param type the artifact type
+ * @return a new request
+ */
static ArtifactFactoryRequest build(
Session session,
String groupId,
@@ -80,6 +108,7 @@ static ArtifactFactoryRequest build(
.build();
}
+ /** @return a new builder instance */
static ArtifactFactoryRequestBuilder builder() {
return new ArtifactFactoryRequestBuilder();
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
index c683928810..d419bf611e 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerException.java
@@ -21,6 +21,8 @@
import org.apache.maven.api.annotations.Experimental;
/**
+ * Exception thrown when installing artifacts into the local repository fails.
+ *
* @since 4.0.0
*/
@Experimental
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
index 6f5a57e0ea..1363ac4978 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstallerRequest.java
@@ -42,14 +42,23 @@
@Immutable
public interface ArtifactInstallerRequest extends Request<Session> {
+ /** @return the artifacts to install, never {@code null} */
@Nonnull
Collection<ProducedArtifact> getArtifacts();
+ /** @return a new builder instance */
@Nonnull
static ArtifactInstallerRequestBuilder builder() {
return new ArtifactInstallerRequestBuilder();
}
+ /**
+ * Builds a request to install artifacts in the local repository.
+ *
+ * @param session the session
+ * @param artifacts the artifacts to install
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactInstallerRequest build(Session session,
Collection<ProducedArtifact> artifacts) {
return builder()
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
index 8eb1739eaf..1e69393e03 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactManager.java
@@ -28,6 +28,7 @@
import org.apache.maven.api.annotations.Nonnull;
/**
+ * Service for associating file system paths with artifacts within the current
session.
*
* @since 4.0.0
*/
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
index 22d5af16f3..7b64b0152a 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverException.java
@@ -21,7 +21,8 @@
import org.apache.maven.api.annotations.Experimental;
/**
- *
+ * Exception thrown when artifact resolution fails, carrying the partial
+ * {@link ArtifactResolverResult} with details about the failure.
*
* @since 4.0.0
*/
@@ -40,6 +41,7 @@ public ArtifactResolverException(String message, Exception e,
ArtifactResolverRe
this.result = result;
}
+ /** @return the resolution result containing detailed information about
the failure */
public ArtifactResolverResult getResult() {
return result;
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
index 7e832a95e4..c99a2ca2fe 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactResolverRequest.java
@@ -42,14 +42,23 @@
@Immutable
public interface ArtifactResolverRequest extends RepositoryAwareRequest {
+ /** @return the coordinates of the artifacts to resolve, never {@code
null} */
@Nonnull
Collection<? extends ArtifactCoordinates> getCoordinates();
+ /** @return a new builder instance */
@Nonnull
static ArtifactResolverRequestBuilder builder() {
return new ArtifactResolverRequestBuilder();
}
+ /**
+ * Builds a request to resolve artifacts from their coordinates.
+ *
+ * @param session the session
+ * @param coordinates the artifact coordinates to resolve
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactResolverRequest build(
@Nonnull Session session, @Nonnull Collection<? extends
ArtifactCoordinates> coordinates) {
@@ -59,6 +68,14 @@ static ArtifactResolverRequest build(
.build();
}
+ /**
+ * Builds a request to resolve artifacts from specific repositories.
+ *
+ * @param session the session
+ * @param coordinates the artifact coordinates to resolve
+ * @param repositories the remote repositories to resolve from
+ * @return a new request, never {@code null}
+ */
@Nonnull
static ArtifactResolverRequest build(
@Nonnull Session session,
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
index b5e338466a..e01b2d5bec 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/BaseRequest.java
@@ -44,12 +44,14 @@ protected BaseRequest(@Nonnull S session, RequestTrace
trace) {
this.trace = trace;
}
+ /** {@inheritDoc} */
@Nonnull
@Override
public S getSession() {
return session;
}
+ /** {@inheritDoc} */
@Override
public RequestTrace getTrace() {
return trace;
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
index 7aaed5632f..3ad15b3f8a 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ChecksumAlgorithmServiceException.java
@@ -20,6 +20,11 @@
import org.apache.maven.api.annotations.Experimental;
+/**
+ * Exception thrown when an error occurs in the checksum algorithm service.
+ *
+ * @since 4.0.0
+ */
@Experimental
public class ChecksumAlgorithmServiceException extends MavenException {
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
index 29b06c45d3..1decb21938 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactory.java
@@ -29,6 +29,8 @@
import org.apache.maven.api.model.ReportPlugin;
/**
+ * Service for creating {@link org.apache.maven.api.DependencyCoordinates}
instances
+ * from requests, model dependencies, plugins, or artifact coordinates.
*
* @since 4.0.0
*/
@@ -47,17 +49,38 @@ public interface DependencyCoordinatesFactory extends
Service {
@Nonnull
DependencyCoordinates create(@Nonnull DependencyCoordinatesFactoryRequest
request);
+ /**
+ * Creates dependency coordinates from artifact coordinates.
+ *
+ * @param session the session
+ * @param coordinates the artifact coordinates
+ * @return a new {@link DependencyCoordinates}, never {@code null}
+ */
@Nonnull
default DependencyCoordinates create(@Nonnull Session session, @Nonnull
ArtifactCoordinates coordinates) {
return create(DependencyCoordinatesFactoryRequest.build(session,
coordinates));
}
+ /**
+ * Creates dependency coordinates from an existing dependency.
+ *
+ * @param session the session
+ * @param dependency the dependency
+ * @return a new {@link DependencyCoordinates}, never {@code null}
+ */
@Nonnull
default DependencyCoordinates create(
@Nonnull Session session, @Nonnull org.apache.maven.api.Dependency
dependency) {
return create(DependencyCoordinatesFactoryRequest.build(session,
dependency));
}
+ /**
+ * Creates dependency coordinates from a model dependency.
+ *
+ * @param session the session
+ * @param dependency the model dependency
+ * @return a new {@link DependencyCoordinates}, never {@code null}
+ */
@Nonnull
default DependencyCoordinates create(@Nonnull Session session, Dependency
dependency) {
return create(DependencyCoordinatesFactoryRequest.build(
@@ -70,6 +93,13 @@ default DependencyCoordinates create(@Nonnull Session
session, Dependency depend
dependency.getType()));
}
+ /**
+ * Creates dependency coordinates from a plugin model.
+ *
+ * @param session the session
+ * @param plugin the plugin
+ * @return a new {@link DependencyCoordinates}, never {@code null}
+ */
@Nonnull
default DependencyCoordinates create(@Nonnull Session session, Plugin
plugin) {
// TODO: hard coded string
@@ -77,6 +107,13 @@ default DependencyCoordinates create(@Nonnull Session
session, Plugin plugin) {
session, plugin.getGroupId(), plugin.getArtifactId(),
plugin.getVersion(), null, null, "maven-plugin"));
}
+ /**
+ * Creates dependency coordinates from a report plugin model.
+ *
+ * @param session the session
+ * @param reportPlugin the report plugin
+ * @return a new {@link DependencyCoordinates}, never {@code null}
+ */
@Nonnull
default DependencyCoordinates create(@Nonnull Session session,
ReportPlugin reportPlugin) {
// TODO: hard coded string
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
index 70d4d02f52..283b5c7272 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyCoordinatesFactoryRequest.java
@@ -36,6 +36,8 @@
import static java.util.Objects.requireNonNull;
/**
+ * Request for creating {@link org.apache.maven.api.DependencyCoordinates},
extending
+ * {@link ArtifactCoordinatesFactoryRequest} with scope, optionality, and
exclusion information.
*
* @since 4.0.0
*/
@@ -43,13 +45,28 @@
@Immutable
public interface DependencyCoordinatesFactoryRequest extends
ArtifactCoordinatesFactoryRequest {
+ /** @return the dependency scope, may be {@code null} */
String getScope();
+ /** @return whether this dependency is optional */
boolean isOptional();
+ /** @return the dependency exclusions, never {@code null} */
@Nonnull
Collection<Exclusion> getExclusions();
+ /**
+ * Builds a request from individual components.
+ *
+ * @param session the session
+ * @param groupId the group identifier
+ * @param artifactId the artifact identifier
+ * @param version the version
+ * @param classifier the classifier
+ * @param extension the file extension
+ * @param type the artifact type
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyCoordinatesFactoryRequest build(
@Nonnull Session session,
@@ -70,6 +87,13 @@ static DependencyCoordinatesFactoryRequest build(
.build();
}
+ /**
+ * Builds a request from existing artifact coordinates.
+ *
+ * @param session the session
+ * @param coordinates the artifact coordinates
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyCoordinatesFactoryRequest build(
@Nonnull Session session, @Nonnull ArtifactCoordinates
coordinates) {
@@ -84,6 +108,13 @@ static DependencyCoordinatesFactoryRequest build(
.build();
}
+ /**
+ * Builds a request from an existing dependency.
+ *
+ * @param session the session
+ * @param dependency the dependency to derive coordinates from
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyCoordinatesFactoryRequest build(@Nonnull Session session,
@Nonnull Dependency dependency) {
return builder()
@@ -99,6 +130,7 @@ static DependencyCoordinatesFactoryRequest build(@Nonnull
Session session, @Nonn
.build();
}
+ /** @return a new builder instance */
@Nonnull
static DependencyCoordinatesFactoryRequestBuilder builder() {
return new DependencyCoordinatesFactoryRequestBuilder();
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
index 0473cce537..24c1c15be5 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolver.java
@@ -133,6 +133,15 @@ default DependencyResolverResult collect(@Nonnull
DependencyResolverRequest requ
List<Node> flatten(@Nonnull Session session, @Nonnull Node node, @Nullable
PathScope scope)
throws DependencyResolverException;
+ /**
+ * Flattens the dependency tree of a project for the given path scope.
+ *
+ * @param session the session
+ * @param project the project
+ * @param scope the path scope
+ * @return the flattened result, never {@code null}
+ * @throws DependencyResolverException if the dependency tree could not be
flattened
+ */
@Nonnull
default DependencyResolverResult flatten(
@Nonnull Session session, @Nonnull Project project, @Nonnull
PathScope scope) {
@@ -140,6 +149,14 @@ default DependencyResolverResult flatten(
session, DependencyResolverRequest.RequestType.FLATTEN,
project, scope));
}
+ /**
+ * Flattens the dependency tree described by the request.
+ *
+ * @param request the dependency resolver request with type {@link
DependencyResolverRequest.RequestType#FLATTEN}
+ * @return the flattened result, never {@code null}
+ * @throws IllegalArgumentException if the request type is not {@code
FLATTEN}
+ * @throws DependencyResolverException if the dependency tree could not be
flattened
+ */
@Nonnull
default DependencyResolverResult flatten(@Nonnull
DependencyResolverRequest request) {
if (request.getRequestType() !=
DependencyResolverRequest.RequestType.FLATTEN) {
@@ -148,12 +165,29 @@ default DependencyResolverResult flatten(@Nonnull
DependencyResolverRequest requ
return resolve(request);
}
+ /**
+ * Resolves the dependencies of a project for the default runtime scope.
+ *
+ * @param session the session
+ * @param project the project
+ * @return the resolution result, never {@code null}
+ * @throws DependencyResolverException if dependency resolution fails
+ */
@Nonnull
default DependencyResolverResult resolve(@Nonnull Session session,
@Nonnull Project project) {
return resolve(
DependencyResolverRequest.build(session,
DependencyResolverRequest.RequestType.RESOLVE, project));
}
+ /**
+ * Resolves the dependencies of a project for the given path scope.
+ *
+ * @param session the session
+ * @param project the project
+ * @param scope the path scope
+ * @return the resolution result, never {@code null}
+ * @throws DependencyResolverException if dependency resolution fails
+ */
@Nonnull
default DependencyResolverResult resolve(
@Nonnull Session session, @Nonnull Project project, @Nonnull
PathScope scope) {
@@ -161,12 +195,29 @@ default DependencyResolverResult resolve(
session, DependencyResolverRequest.RequestType.RESOLVE,
project, scope));
}
+ /**
+ * Resolves a single dependency for the default runtime scope.
+ *
+ * @param session the session
+ * @param dependency the dependency coordinates
+ * @return the resolution result, never {@code null}
+ * @throws DependencyResolverException if dependency resolution fails
+ */
@Nonnull
default DependencyResolverResult resolve(@Nonnull Session session,
@Nonnull DependencyCoordinates dependency) {
return resolve(
DependencyResolverRequest.build(session,
DependencyResolverRequest.RequestType.RESOLVE, dependency));
}
+ /**
+ * Resolves a single dependency for the given path scope.
+ *
+ * @param session the session
+ * @param dependency the dependency coordinates
+ * @param scope the path scope
+ * @return the resolution result, never {@code null}
+ * @throws DependencyResolverException if dependency resolution fails
+ */
@Nonnull
default DependencyResolverResult resolve(
@Nonnull Session session, @Nonnull DependencyCoordinates
dependency, @Nonnull PathScope scope) {
@@ -174,6 +225,14 @@ default DependencyResolverResult resolve(
session, DependencyResolverRequest.RequestType.RESOLVE,
dependency, scope));
}
+ /**
+ * Resolves a list of dependencies for the default runtime scope.
+ *
+ * @param session the session
+ * @param dependencies the dependency coordinates
+ * @return the resolution result, never {@code null}
+ * @throws DependencyResolverException if dependency resolution fails
+ */
@Nonnull
default DependencyResolverResult resolve(
@Nonnull Session session, @Nonnull List<DependencyCoordinates>
dependencies) {
@@ -181,6 +240,15 @@ default DependencyResolverResult resolve(
DependencyResolverRequest.build(session,
DependencyResolverRequest.RequestType.RESOLVE, dependencies));
}
+ /**
+ * Resolves a list of dependencies for the given path scope.
+ *
+ * @param session the session
+ * @param dependencies the dependency coordinates
+ * @param scope the path scope
+ * @return the resolution result, never {@code null}
+ * @throws DependencyResolverException if dependency resolution fails
+ */
@Nonnull
default DependencyResolverResult resolve(
@Nonnull Session session, @Nonnull List<DependencyCoordinates>
dependencies, @Nonnull PathScope scope) {
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
index a26a88c6f7..e6b57056a0 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverException.java
@@ -20,6 +20,11 @@
import org.apache.maven.api.annotations.Experimental;
+/**
+ * Exception thrown when dependency resolution fails.
+ *
+ * @since 4.0.0
+ */
@Experimental
public class DependencyResolverException extends MavenException {
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
index 5be250824d..f84327763b 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/DependencyResolverRequest.java
@@ -63,26 +63,34 @@ enum RequestType {
RESOLVE
}
+ /** @return the type of request (collect, flatten, or resolve) */
@Nonnull
RequestType getRequestType();
+ /** @return the project whose dependencies should be resolved, or empty if
not project-based */
@Nonnull
Optional<Project> getProject();
+ /** @return the root artifact for the dependency graph, or empty */
@Nonnull
Optional<Artifact> getRootArtifact();
+ /** @return the root dependency coordinates, or empty */
@Nonnull
Optional<DependencyCoordinates> getRoot();
+ /** @return the direct dependencies, never {@code null} */
@Nonnull
Collection<DependencyCoordinates> getDependencies();
+ /** @return the managed dependencies for version and scope management,
never {@code null} */
@Nonnull
Collection<DependencyCoordinates> getManagedDependencies();
+ /** @return whether to produce a verbose dependency graph */
boolean getVerbose();
+ /** @return the path scope for dependency resolution */
@Nonnull
PathScope getPathScope();
@@ -119,16 +127,34 @@ enum RequestType {
@Nullable
Version getTargetVersion();
+ /** @return a new builder instance */
@Nonnull
static DependencyResolverRequestBuilder builder() {
return new DependencyResolverRequestBuilder();
}
+ /**
+ * Builds a request for the given artifact using the default runtime scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param rootArtifact the root artifact
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(Session session, RequestType
requestType, Artifact rootArtifact) {
return build(session, requestType, rootArtifact,
PathScope.MAIN_RUNTIME);
}
+ /**
+ * Builds a request for the given artifact and path scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param rootArtifact the root artifact
+ * @param scope the path scope
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(
Session session, RequestType requestType, Artifact rootArtifact,
PathScope scope) {
@@ -140,11 +166,28 @@ static DependencyResolverRequest build(
.build();
}
+ /**
+ * Builds a request for the given project using the default runtime scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param project the project
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(Session session, RequestType
requestType, Project project) {
return build(session, requestType, project, PathScope.MAIN_RUNTIME);
}
+ /**
+ * Builds a request for the given project and path scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param project the project
+ * @param scope the path scope
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(Session session, RequestType
requestType, Project project, PathScope scope) {
return new DependencyResolverRequestBuilder()
@@ -155,11 +198,28 @@ static DependencyResolverRequest build(Session session,
RequestType requestType,
.build();
}
+ /**
+ * Builds a request for the given dependency using the default runtime
scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param dependency the root dependency coordinates
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(Session session, RequestType
requestType, DependencyCoordinates dependency) {
return build(session, requestType, dependency, PathScope.MAIN_RUNTIME);
}
+ /**
+ * Builds a request for the given dependency and path scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param dependency the root dependency coordinates
+ * @param scope the path scope
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(
Session session, RequestType requestType, DependencyCoordinates
dependency, PathScope scope) {
@@ -171,12 +231,29 @@ static DependencyResolverRequest build(
.build();
}
+ /**
+ * Builds a request for the given dependencies using the default runtime
scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param dependencies the dependency coordinates
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(
Session session, RequestType requestType,
List<DependencyCoordinates> dependencies) {
return build(session, requestType, dependencies,
PathScope.MAIN_RUNTIME);
}
+ /**
+ * Builds a request for the given dependencies and path scope.
+ *
+ * @param session the session
+ * @param requestType the request type
+ * @param dependencies the dependency coordinates
+ * @param scope the path scope
+ * @return a new request, never {@code null}
+ */
@Nonnull
static DependencyResolverRequest build(
Session session, RequestType requestType,
List<DependencyCoordinates> dependencies, PathScope scope) {
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 06d9726cac..8588a29a9b 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
@@ -35,9 +35,22 @@
* @since 4.0.0
*/
public interface ExtensibleEnumRegistry<T extends ExtensibleEnum> extends
Service {
+ /**
+ * Looks up an extensible enum value by its identifier.
+ *
+ * @param id the identifier of the enum value to look up
+ * @return an {@code Optional} containing the enum value, or empty if not
found
+ */
@Nonnull
Optional<T> lookup(@Nonnull String id);
+ /**
+ * Looks up an extensible enum value by its identifier, throwing if not
found.
+ *
+ * @param id the identifier of the enum value to look up
+ * @return the enum value
+ * @throws IllegalArgumentException if no value is registered with the
given id
+ */
@Nonnull
default T require(@Nonnull String id) {
return lookup(id).orElseThrow(() -> new
IllegalArgumentException("Unknown extensible enum value '" + id + "'"));
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
index 86e7e74d38..4418d570c2 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Interpolator.java
@@ -159,6 +159,13 @@ static UnaryOperator<String> chain(Collection<? extends
UnaryOperator<String>> f
};
}
+ /**
+ * Creates a composite function from a varargs array of functions.
+ *
+ * @param functions the functions to chain
+ * @return a function that applies each function in order until a non-null
result is found
+ * @see #chain(Collection)
+ */
@SafeVarargs
static UnaryOperator<String> chain(UnaryOperator<String>... functions) {
return chain(List.of(functions));
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
index d2f0f09331..4bd0b7f3f4 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LanguageRegistry.java
@@ -20,4 +20,9 @@
import org.apache.maven.api.Language;
+/**
+ * Registry for {@link Language} extensible enum values.
+ *
+ * @since 4.0.0
+ */
public interface LanguageRegistry extends ExtensibleEnumRegistry<Language> {}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
index 55efc16ebc..881efa891f 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/LifecycleRegistry.java
@@ -24,11 +24,31 @@
import org.apache.maven.api.Lifecycle;
+/**
+ * Registry for {@link Lifecycle} extensible enum values.
+ * <p>
+ * In addition to the standard registry lookup operations, this interface
provides
+ * iteration over all registered lifecycles and computation of the ordered
phase list
+ * for a given lifecycle.
+ *
+ * @since 4.0.0
+ */
public interface LifecycleRegistry extends ExtensibleEnumRegistry<Lifecycle>,
Iterable<Lifecycle> {
+ /**
+ * Returns a sequential stream of all registered lifecycles.
+ *
+ * @return a stream of lifecycles
+ */
default Stream<Lifecycle> stream() {
return StreamSupport.stream(spliterator(), false);
}
+ /**
+ * Computes the ordered list of phase names for the given lifecycle.
+ *
+ * @param lifecycle the lifecycle whose phases should be computed
+ * @return the ordered list of phase names
+ */
List<String> computePhases(Lifecycle lifecycle);
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java
index c80c2ed10e..da3a2395d2 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Lookup.java
@@ -25,6 +25,14 @@
import org.apache.maven.api.Service;
import org.apache.maven.api.annotations.Nonnull;
+/**
+ * Service for looking up components from the dependency injection container.
+ * <p>
+ * Provides methods to retrieve single components, optional components, and
+ * collections of components by their type and optional name qualifier.
+ *
+ * @since 4.0.0
+ */
public interface Lookup extends Service {
/**
* Performs a lookup for given typed component.
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
index ae0d249c33..8884b96e16 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/MessageBuilder.java
@@ -149,27 +149,48 @@ default MessageBuilder project(Object message) {
return style("." + Constants.MAVEN_STYLE_PROJECT_NAME + ":-" +
Constants.MAVEN_STYLE_PROJECT_DEFAULT, message);
}
+ /**
+ * Append message content with the given style applied, then reset the
style.
+ *
+ * @param style the style definition to apply
+ * @param message the message to append
+ * @return the current builder
+ */
@Nonnull
default MessageBuilder style(String style, Object message) {
return style(style).a(message).resetStyle();
}
+ /**
+ * Apply the given style to subsequent appended content.
+ *
+ * @param style the style definition to apply
+ * @return the current builder
+ */
MessageBuilder style(String style);
+ /**
+ * Reset the current style back to the default.
+ *
+ * @return the current builder
+ */
MessageBuilder resetStyle();
//
// message building methods modelled after Ansi methods
//
+ /** {@inheritDoc} */
@Nonnull
@Override
MessageBuilder append(CharSequence cs);
+ /** {@inheritDoc} */
@Nonnull
@Override
MessageBuilder append(CharSequence cs, int start, int end);
+ /** {@inheritDoc} */
@Nonnull
@Override
MessageBuilder append(char c);
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
index c98c5ace62..4e676260af 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilder.java
@@ -23,6 +23,14 @@
import org.apache.maven.api.Service;
import org.apache.maven.api.model.Model;
+/**
+ * Service for building Maven project models from POM files or other sources.
+ * <p>
+ * The model builder processes raw POM files through the full Maven model
building pipeline,
+ * including inheritance assembly, profile activation, interpolation, and
validation.
+ *
+ * @since 4.0.0
+ */
public interface ModelBuilder extends Service {
String MODEL_VERSION_4_0_0 = "4.0.0";
@@ -33,10 +41,25 @@ public interface ModelBuilder extends Service {
List<String> KNOWN_MODEL_VERSIONS = List.of(MODEL_VERSION_4_0_0,
MODEL_VERSION_4_1_0, MODEL_VERSION_4_2_0);
+ /**
+ * Creates a new model builder session for building one or more models.
+ *
+ * @return a new model builder session
+ */
ModelBuilderSession newSession();
+ /**
+ * A session for building models, allowing multiple builds to share state.
+ */
interface ModelBuilderSession {
+ /**
+ * Builds the effective model from the given request.
+ *
+ * @param request the model builder request
+ * @return the model builder result
+ * @throws ModelBuilderException if the model cannot be built
+ */
ModelBuilderResult build(ModelBuilderRequest request) throws
ModelBuilderException;
/**
@@ -67,5 +90,12 @@ default ModelBuilderResult validate(ModelBuilderRequest
request) throws ModelBui
}
}
+ /**
+ * Builds a raw model from the given request without applying inheritance
or interpolation.
+ *
+ * @param request the model builder request
+ * @return the raw model
+ * @throws ModelBuilderException if the raw model cannot be built
+ */
Model buildRawModel(ModelBuilderRequest request) throws
ModelBuilderException;
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
index 496715802c..a0160992db 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderRequest.java
@@ -95,14 +95,34 @@ enum RepositoryMerging {
REQUEST_DOMINANT,
}
+ /**
+ * Gets the source from which the model should be built.
+ *
+ * @return the model source
+ */
@Nonnull
ModelSource getSource();
+ /**
+ * Gets the type of build request.
+ *
+ * @return the request type
+ */
@Nonnull
RequestType getRequestType();
+ /**
+ * Returns whether input location tracking is enabled for the model.
+ *
+ * @return {@code true} if location tracking is enabled
+ */
boolean isLocationTracking();
+ /**
+ * Returns whether the build should recursively process sub-projects.
+ *
+ * @return {@code true} if recursive processing is enabled
+ */
boolean isRecursive();
/**
@@ -137,12 +157,29 @@ enum RepositoryMerging {
@Nonnull
Map<String, String> getUserProperties();
+ /**
+ * Gets the strategy for merging repositories from the POM with those from
the request.
+ *
+ * @return the repository merging strategy
+ */
@Nonnull
RepositoryMerging getRepositoryMerging();
+ /**
+ * Gets the model transformer used to inject lifecycle bindings.
+ *
+ * @return the lifecycle bindings injector, or {@code null} if none
+ */
@Nullable
ModelTransformer getLifecycleBindingsInjector();
+ /**
+ * Creates a new request by copying an existing request and replacing the
source.
+ *
+ * @param request the original request to copy
+ * @param source the new model source
+ * @return the new request
+ */
@Nonnull
static ModelBuilderRequest build(@Nonnull ModelBuilderRequest request,
@Nonnull ModelSource source) {
return builder(requireNonNull(request, "request cannot be null"))
@@ -150,6 +187,13 @@ static ModelBuilderRequest build(@Nonnull
ModelBuilderRequest request, @Nonnull
.build();
}
+ /**
+ * Creates a new request for the given session and source.
+ *
+ * @param session the session
+ * @param source the model source
+ * @return the new request
+ */
@Nonnull
static ModelBuilderRequest build(@Nonnull Session session, @Nonnull
ModelSource source) {
return builder()
@@ -158,6 +202,13 @@ static ModelBuilderRequest build(@Nonnull Session session,
@Nonnull ModelSource
.build();
}
+ /**
+ * Creates a new request for the given session and POM path.
+ *
+ * @param session the session
+ * @param path the path to the POM file
+ * @return the new request
+ */
@Nonnull
static ModelBuilderRequest build(@Nonnull Session session, @Nonnull Path
path) {
return builder()
@@ -166,11 +217,22 @@ static ModelBuilderRequest build(@Nonnull Session
session, @Nonnull Path path) {
.build();
}
+ /**
+ * Creates a new builder for constructing a {@code ModelBuilderRequest}.
+ *
+ * @return a new builder
+ */
@Nonnull
static ModelBuilderRequestBuilder builder() {
return new ModelBuilderRequestBuilder();
}
+ /**
+ * Creates a new builder initialized from the given request.
+ *
+ * @param request the request to copy values from
+ * @return a new builder pre-populated with the request's values
+ */
@Nonnull
static ModelBuilderRequestBuilder builder(ModelBuilderRequest request) {
return new ModelBuilderRequestBuilder(request);
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
index 66c1fcc31e..fc8cf04edf 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblemCollector.java
@@ -31,30 +31,77 @@
*/
public interface ModelProblemCollector {
+ /**
+ * Returns the underlying problem collector.
+ *
+ * @return the problem collector
+ */
ProblemCollector<ModelProblem> getProblemCollector();
+ /**
+ * Returns {@code true} if any problems with {@link
BuilderProblem.Severity#ERROR} or higher have been collected.
+ *
+ * @return {@code true} if errors exist
+ */
default boolean hasErrors() {
return getProblemCollector().hasErrorProblems();
}
+ /**
+ * Returns {@code true} if any problems with {@link
BuilderProblem.Severity#FATAL} have been collected.
+ *
+ * @return {@code true} if fatal errors exist
+ */
default boolean hasFatalErrors() {
return getProblemCollector().hasFatalProblems();
}
+ /**
+ * Adds a problem with the given severity, version, and message.
+ *
+ * @param severity the problem severity
+ * @param version the model version
+ * @param message the problem message
+ */
default void add(BuilderProblem.Severity severity, ModelProblem.Version
version, String message) {
add(severity, version, message, null, null);
}
+ /**
+ * Adds a problem with the given severity, version, message, and location.
+ *
+ * @param severity the problem severity
+ * @param version the model version
+ * @param message the problem message
+ * @param location the input location where the problem occurred
+ */
default void add(
BuilderProblem.Severity severity, ModelProblem.Version version,
String message, InputLocation location) {
add(severity, version, message, location, null);
}
+ /**
+ * Adds a problem with the given severity, version, message, and exception.
+ *
+ * @param severity the problem severity
+ * @param version the model version
+ * @param message the problem message
+ * @param exception the exception that caused the problem
+ */
default void add(
BuilderProblem.Severity severity, ModelProblem.Version version,
String message, Exception exception) {
add(severity, version, message, null, exception);
}
+ /**
+ * Adds a problem with the given severity, version, message, location, and
exception.
+ *
+ * @param severity the problem severity
+ * @param version the model version
+ * @param message the problem message
+ * @param location the input location where the problem occurred, or
{@code null}
+ * @param exception the exception that caused the problem, or {@code null}
+ */
void add(
BuilderProblem.Severity severity,
ModelProblem.Version version,
@@ -62,19 +109,54 @@ void add(
InputLocation location,
Exception exception);
+ /**
+ * Adds a pre-constructed model problem directly.
+ *
+ * @param problem the model problem to add
+ */
default void add(ModelProblem problem) {
getProblemCollector().reportProblem(problem);
}
+ /**
+ * Creates a {@link ModelBuilderException} from the collected problems.
+ *
+ * @return a new exception summarizing the collected problems
+ */
ModelBuilderException newModelBuilderException();
+ /**
+ * Sets the source hint used to provide context for subsequently collected
problems.
+ *
+ * @param location the source location string
+ */
void setSource(String location);
+ /**
+ * Sets the source hint from a model's coordinates.
+ *
+ * @param model the model to derive the source hint from
+ */
void setSource(Model model);
+ /**
+ * Gets the current source hint.
+ *
+ * @return the source hint string
+ */
String getSource();
+ /**
+ * Sets the root model being built.
+ *
+ * @param model the root model
+ */
void setRootModel(Model model);
+ /**
+ * Gets the root model being built.
+ *
+ * @return the root model, or {@code null} if not yet set
+ */
Model getRootModel();
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
index e114e26640..d26d732ff0 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PackagingRegistry.java
@@ -20,4 +20,9 @@
import org.apache.maven.api.Packaging;
+/**
+ * Registry for {@link Packaging} extensible enum values.
+ *
+ * @since 4.0.0
+ */
public interface PackagingRegistry extends ExtensibleEnumRegistry<Packaging> {}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
index 06b5d59647..b196036b98 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathScopeRegistry.java
@@ -20,4 +20,9 @@
import org.apache.maven.api.PathScope;
+/**
+ * Registry for {@link PathScope} extensible enum values.
+ *
+ * @since 4.0.0
+ */
public interface PathScopeRegistry extends ExtensibleEnumRegistry<PathScope> {}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
index 518033b601..d8d06524a4 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilder.java
@@ -26,6 +26,8 @@
import org.apache.maven.api.annotations.Nonnull;
/**
+ * Service for building {@link org.apache.maven.api.Project} instances from
POM files or other sources.
+ *
* @since 4.0.0
*/
@Experimental
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
index 1ab8a9a15b..2c0946282e 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderRequest.java
@@ -72,6 +72,14 @@ public interface SettingsBuilderRequest extends
Request<ProtoSession> {
@Nonnull
Optional<UnaryOperator<String>> getInterpolationSource();
+ /**
+ * Creates a request from installation and user settings sources.
+ *
+ * @param session the session
+ * @param installationSettingsSource the installation settings source
+ * @param userSettingsSource the user settings source
+ * @return the new request
+ */
@Nonnull
static SettingsBuilderRequest build(
@Nonnull ProtoSession session,
@@ -80,12 +88,29 @@ static SettingsBuilderRequest build(
return build(session, installationSettingsSource, null,
userSettingsSource);
}
+ /**
+ * Creates a request from installation and user settings paths.
+ *
+ * @param session the session
+ * @param installationSettingsPath the installation settings path
+ * @param userSettingsPath the user settings path
+ * @return the new request
+ */
@Nonnull
static SettingsBuilderRequest build(
@Nonnull ProtoSession session, @Nonnull Path
installationSettingsPath, @Nonnull Path userSettingsPath) {
return build(session, Sources.fromPath(installationSettingsPath),
null, Sources.fromPath(userSettingsPath));
}
+ /**
+ * Creates a request from installation, project, and user settings sources.
+ *
+ * @param session the session
+ * @param installationSettingsSource the installation settings source, or
{@code null}
+ * @param projectSettingsSource the project settings source, or {@code
null}
+ * @param userSettingsSource the user settings source, or {@code null}
+ * @return the new request
+ */
@Nonnull
static SettingsBuilderRequest build(
@Nonnull ProtoSession session,
@@ -100,6 +125,16 @@ static SettingsBuilderRequest build(
.build();
}
+ /**
+ * Creates a request from installation, project, and user settings paths.
+ * Paths that do not exist are treated as absent.
+ *
+ * @param session the session
+ * @param installationSettingsPath the installation settings path, or
{@code null}
+ * @param projectSettingsPath the project settings path, or {@code null}
+ * @param userSettingsPath the user settings path, or {@code null}
+ * @return the new request
+ */
@Nonnull
static SettingsBuilderRequest build(
@Nonnull ProtoSession session,
@@ -123,6 +158,11 @@ static SettingsBuilderRequest build(
.build();
}
+ /**
+ * Creates a new builder for constructing a {@code SettingsBuilderRequest}.
+ *
+ * @return a new builder
+ */
@Nonnull
static SettingsBuilderRequestBuilder builder() {
return new SettingsBuilderRequestBuilder();
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
index 37b6213da2..881f5ed662 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderResult.java
@@ -23,6 +23,8 @@
import org.apache.maven.api.settings.Settings;
/**
+ * Result of building the effective Maven settings, providing access to the
assembled
+ * {@link org.apache.maven.api.settings.Settings} and any problems encountered
during the build.
*
* @since 4.0.0
*/
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
index 0257ae6760..31c90d5044 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderRequest.java
@@ -32,6 +32,7 @@
import static java.util.Objects.requireNonNull;
/**
+ * Request for building the effective toolchains from installation and
user-level toolchain sources.
*
* @since 4.0.0
*/
@@ -54,6 +55,14 @@ public interface ToolchainsBuilderRequest extends
Request<ProtoSession> {
@Nonnull
Optional<Source> getUserToolchainsSource();
+ /**
+ * Creates a request from installation and user toolchains sources.
+ *
+ * @param session the session
+ * @param installationToolchainsFile the installation toolchains source,
or {@code null}
+ * @param userToolchainsSource the user toolchains source, or {@code null}
+ * @return the new request
+ */
@Nonnull
static ToolchainsBuilderRequest build(
@Nonnull ProtoSession session,
@@ -66,6 +75,15 @@ static ToolchainsBuilderRequest build(
.build();
}
+ /**
+ * Creates a request from installation and user toolchains paths.
+ * Paths that do not exist are treated as absent.
+ *
+ * @param session the session
+ * @param installationToolchainsFile the installation toolchains path, or
{@code null}
+ * @param userToolchainsPath the user toolchains path, or {@code null}
+ * @return the new request
+ */
@Nonnull
static ToolchainsBuilderRequest build(
@Nonnull ProtoSession session,
@@ -84,6 +102,11 @@ static ToolchainsBuilderRequest build(
.build();
}
+ /**
+ * Creates a new builder for constructing a {@code
ToolchainsBuilderRequest}.
+ *
+ * @return a new builder
+ */
@Nonnull
static ToolchainsBuilderRequestBuilder builder() {
return new ToolchainsBuilderRequestBuilder();
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
index 3cf06a7397..b4d24592a9 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ToolchainsBuilderResult.java
@@ -23,6 +23,8 @@
import org.apache.maven.api.toolchain.PersistedToolchains;
/**
+ * Result of building the effective toolchains, providing access to the
assembled
+ * {@link org.apache.maven.api.toolchain.PersistedToolchains} and any problems
encountered.
*
* @since 4.0.0
*/
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
index c78fa37e24..c8226074ea 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/TransportProviderException.java
@@ -22,6 +22,8 @@
import org.apache.maven.api.annotations.Experimental;
/**
+ * Exception thrown when a transport provider encounters an error during
remote repository access.
+ *
* @since 4.0.0
*/
@Experimental
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
index aec999dd28..81f2147d10 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolver.java
@@ -81,6 +81,13 @@ default VersionRangeResolverResult resolve(
return resolve(VersionRangeResolverRequest.build(session,
artifactCoordinates, repositories));
}
+ /**
+ * Expands a version range to a list of matching versions using the given
request.
+ *
+ * @param request the version range resolver request
+ * @return the version range resolution result
+ * @throws VersionRangeResolverException if the version range could not be
resolved
+ */
@Nonnull
VersionRangeResolverResult resolve(@Nonnull VersionRangeResolverRequest
request)
throws VersionRangeResolverException;
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
index dd0746844f..1f6c19b7e3 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverException.java
@@ -22,6 +22,8 @@
import org.apache.maven.api.annotations.Experimental;
/**
+ * Exception thrown when resolving a version range against available
repositories fails.
+ *
* @since 4.0.0
*/
@Experimental
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
index 6eb5b0989c..73add57ed0 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverException.java
@@ -22,6 +22,8 @@
import org.apache.maven.api.annotations.Experimental;
/**
+ * Exception thrown when resolving a meta-version (such as {@code LATEST} or
{@code RELEASE}) fails.
+ *
* @since 4.0.0
*/
@Experimental
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
index b510dcc2de..1ae301c710 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverRequest.java
@@ -32,15 +32,28 @@
import static java.util.Objects.requireNonNull;
/**
+ * Request for resolving a meta-version of an artifact to a concrete version.
*
* @since 4.0.0
*/
@Experimental
public interface VersionResolverRequest extends RepositoryAwareRequest {
+ /**
+ * Gets the artifact coordinates whose version should be resolved.
+ *
+ * @return the artifact coordinates
+ */
@Nonnull
ArtifactCoordinates getArtifactCoordinates();
+ /**
+ * Creates a request for the given session and artifact coordinates.
+ *
+ * @param session the session
+ * @param artifactCoordinates the artifact coordinates
+ * @return the new request
+ */
@Nonnull
static VersionResolverRequest build(@Nonnull Session session, @Nonnull
ArtifactCoordinates artifactCoordinates) {
return builder()
@@ -49,6 +62,14 @@ static VersionResolverRequest build(@Nonnull Session
session, @Nonnull ArtifactC
.build();
}
+ /**
+ * Creates a request for the given session, artifact coordinates, and
repositories.
+ *
+ * @param session the session
+ * @param artifactCoordinates the artifact coordinates
+ * @param repositories the repositories to use, or {@code null} to use the
session's repositories
+ * @return the new request
+ */
@Nonnull
static VersionResolverRequest build(
@Nonnull Session session,
@@ -61,6 +82,11 @@ static VersionResolverRequest build(
.build();
}
+ /**
+ * Creates a new builder for constructing a {@code VersionResolverRequest}.
+ *
+ * @return a new builder
+ */
@Nonnull
static VersionResolverRequestBuilder builder() {
return new VersionResolverRequestBuilder();
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
index 5b9e61b40d..d1adda355e 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionResolverResult.java
@@ -27,18 +27,35 @@
import org.apache.maven.api.annotations.Nonnull;
/**
+ * Result of resolving a meta-version, providing the concrete resolved version
+ * and the repository it was resolved from.
*
* @since 4.0.0
*/
@Experimental
public interface VersionResolverResult extends Result<VersionResolverRequest> {
+ /**
+ * Gets the exceptions that occurred during version resolution.
+ *
+ * @return the list of exceptions, never {@code null}
+ */
@Nonnull
List<Exception> getExceptions();
+ /**
+ * Gets the resolved version.
+ *
+ * @return the resolved version
+ */
@Nonnull
Version getVersion();
+ /**
+ * Gets the repository from which the version was resolved.
+ *
+ * @return an optional containing the repository, or empty if unknown
+ */
@Nonnull
Optional<Repository> getRepository();
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
index a79d9fcb8d..2dadc303d2 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/Location.java
@@ -18,6 +18,12 @@
*/
package org.apache.maven.api.services.xml;
+/**
+ * Represents a location in an XML document, providing line number, column
number,
+ * and character offset information for diagnostics and error reporting.
+ *
+ * @since 4.0.0
+ */
public interface Location {
/**
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
index 733e70b282..363852198d 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
@@ -39,43 +39,109 @@
@Experimental
public interface XmlFactory<T> extends Service {
+ /**
+ * Reads an object from the specified path using strict parsing.
+ *
+ * @param path the path to read from
+ * @return the parsed object
+ * @throws XmlReaderException if an error occurs during parsing
+ */
@Nonnull
default T read(@Nonnull Path path) throws XmlReaderException {
return read(path, true);
}
+ /**
+ * Reads an object from the specified path.
+ *
+ * @param path the path to read from
+ * @param strict whether to enforce strict parsing
+ * @return the parsed object
+ * @throws XmlReaderException if an error occurs during parsing
+ */
@Nonnull
default T read(@Nonnull Path path, boolean strict) throws
XmlReaderException {
return
read(XmlReaderRequest.builder().path(path).strict(strict).build());
}
+ /**
+ * Reads an object from the specified input stream using strict parsing.
+ *
+ * @param input the input stream to read from
+ * @return the parsed object
+ * @throws XmlReaderException if an error occurs during parsing
+ */
@Nonnull
default T read(@Nonnull InputStream input) throws XmlReaderException {
return read(input, true);
}
+ /**
+ * Reads an object from the specified input stream.
+ *
+ * @param input the input stream to read from
+ * @param strict whether to enforce strict parsing
+ * @return the parsed object
+ * @throws XmlReaderException if an error occurs during parsing
+ */
@Nonnull
default T read(@Nonnull InputStream input, boolean strict) throws
XmlReaderException {
return
read(XmlReaderRequest.builder().inputStream(input).strict(strict).build());
}
+ /**
+ * Reads an object from the specified reader using strict parsing.
+ *
+ * @param reader the reader to read from
+ * @return the parsed object
+ * @throws XmlReaderException if an error occurs during parsing
+ */
@Nonnull
default T read(@Nonnull Reader reader) throws XmlReaderException {
return read(reader, true);
}
+ /**
+ * Reads an object from the specified reader.
+ *
+ * @param reader the reader to read from
+ * @param strict whether to enforce strict parsing
+ * @return the parsed object
+ * @throws XmlReaderException if an error occurs during parsing
+ */
@Nonnull
default T read(@Nonnull Reader reader, boolean strict) throws
XmlReaderException {
return
read(XmlReaderRequest.builder().reader(reader).strict(strict).build());
}
+ /**
+ * Reads an object using the specified request.
+ *
+ * @param request the reader request containing the input source and
options
+ * @return the parsed object
+ * @throws XmlReaderException if an error occurs during parsing
+ */
@Nonnull
T read(@Nonnull XmlReaderRequest request) throws XmlReaderException;
+ /**
+ * Writes the given content to the specified path.
+ *
+ * @param content the object to write
+ * @param path the path to write to
+ * @throws XmlWriterException if an error occurs during writing
+ */
default void write(@Nonnull T content, @Nonnull Path path) throws
XmlWriterException {
write(XmlWriterRequest.<T>builder().content(content).path(path).build());
}
+ /**
+ * Writes the given content to the specified output stream.
+ *
+ * @param content the object to write
+ * @param outputStream the output stream to write to
+ * @throws XmlWriterException if an error occurs during writing
+ */
default void write(@Nonnull T content, @Nonnull OutputStream outputStream)
throws XmlWriterException {
write(XmlWriterRequest.<T>builder()
.content(content)
@@ -83,10 +149,23 @@ default void write(@Nonnull T content, @Nonnull
OutputStream outputStream) throw
.build());
}
+ /**
+ * Writes the given content to the specified writer.
+ *
+ * @param content the object to write
+ * @param writer the writer to write to
+ * @throws XmlWriterException if an error occurs during writing
+ */
default void write(@Nonnull T content, @Nonnull Writer writer) throws
XmlWriterException {
write(XmlWriterRequest.<T>builder().content(content).writer(writer).build());
}
+ /**
+ * Writes an object using the specified request.
+ *
+ * @param request the writer request containing the output target and
content
+ * @throws XmlWriterException if an error occurs during writing
+ */
void write(@Nonnull XmlWriterRequest<T> request) throws XmlWriterException;
/**
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
index f631752159..5c0471d52d 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderException.java
@@ -40,6 +40,11 @@ public XmlReaderException(String message, Location location,
Exception e) {
this.location = location;
}
+ /**
+ * Returns the location in the XML document where the error occurred.
+ *
+ * @return the error location, or {@code null} if not available
+ */
public Location getLocation() {
return location;
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
index 07fd999b9f..14896a3f0e 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
@@ -38,32 +38,82 @@
@Immutable
public interface XmlReaderRequest {
+ /**
+ * Returns the path to the XML file to read, or {@code null} if another
input source is used.
+ *
+ * @return the file path, or {@code null}
+ */
@Nullable
Path getPath();
+ /**
+ * Returns the root directory for resolving relative paths, or {@code
null} if not set.
+ *
+ * @return the root directory, or {@code null}
+ */
@Nullable
Path getRootDirectory();
+ /**
+ * Returns the URL to read the XML from, or {@code null} if another input
source is used.
+ *
+ * @return the URL, or {@code null}
+ */
@Nullable
URL getURL();
+ /**
+ * Returns the input stream to read the XML from, or {@code null} if
another input source is used.
+ *
+ * @return the input stream, or {@code null}
+ */
@Nullable
InputStream getInputStream();
+ /**
+ * Returns the reader to read the XML from, or {@code null} if another
input source is used.
+ *
+ * @return the reader, or {@code null}
+ */
@Nullable
Reader getReader();
+ /**
+ * Returns the transformer to apply during parsing, or {@code null} if
none is set.
+ *
+ * @return the transformer, or {@code null}
+ */
@Nullable
Transformer getTransformer();
+ /**
+ * Returns whether strict parsing should be enforced.
+ *
+ * @return {@code true} if strict parsing is enabled
+ */
boolean isStrict();
+ /**
+ * Returns the identifier of the model being parsed, used for error
reporting.
+ *
+ * @return the model identifier, or {@code null}
+ */
@Nullable
String getModelId();
+ /**
+ * Returns the location description used for error reporting.
+ *
+ * @return the location string, or {@code null}
+ */
@Nullable
String getLocation();
+ /**
+ * Returns whether default XML entities should be added during parsing.
+ *
+ * @return {@code true} if default entities should be added
+ */
boolean isAddDefaultEntities();
/**
@@ -92,6 +142,11 @@ interface Transformer {
String transform(String source, String fieldName);
}
+ /**
+ * Creates a new builder for constructing {@code XmlReaderRequest}
instances.
+ *
+ * @return a new builder
+ */
@Nonnull
static XmlReaderRequestBuilder builder() {
return new XmlReaderRequestBuilder();
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
index 69852d375f..0ea0ad349f 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterException.java
@@ -40,6 +40,11 @@ public XmlWriterException(String message, Location location,
Exception e) {
this.location = location;
}
+ /**
+ * Returns the location in the XML document where the error occurred.
+ *
+ * @return the error location, or {@code null} if not available
+ */
public Location getLocation() {
return location;
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
index 46ee89c8cf..f0bca5a128 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
@@ -36,21 +36,53 @@
@Experimental
public interface XmlWriterRequest<T> {
+ /**
+ * Returns the path to write to, or {@code null} if another output target
is used.
+ *
+ * @return the file path, or {@code null}
+ */
@Nullable
Path getPath();
+ /**
+ * Returns the output stream to write to, or {@code null} if another
output target is used.
+ *
+ * @return the output stream, or {@code null}
+ */
@Nullable
OutputStream getOutputStream();
+ /**
+ * Returns the writer to write to, or {@code null} if another output
target is used.
+ *
+ * @return the writer, or {@code null}
+ */
@Nullable
Writer getWriter();
+ /**
+ * Returns the content object to be written as XML.
+ *
+ * @return the content to write
+ */
@Nonnull
T getContent();
+ /**
+ * Returns the formatter for rendering input location information in the
output,
+ * or {@code null} if location information should not be included.
+ *
+ * @return the input location formatter, or {@code null}
+ */
@Nullable
Function<Object, String> getInputLocationFormatter();
+ /**
+ * Creates a new builder for constructing {@code XmlWriterRequest}
instances.
+ *
+ * @param <T> the content type
+ * @return a new builder
+ */
static <T> XmlWriterRequestBuilder<T> builder() {
return new XmlWriterRequestBuilder<>();
}
diff --git
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
index 58cd0aef0f..bab8c4d787 100644
---
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
+++
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/ModelResolver.java
@@ -77,6 +77,13 @@ ModelSource resolveModel(
@Nonnull AtomicReference<Dependency> modified)
throws ModelResolverException;
+ /**
+ * Resolves a POM for the specified coordinates.
+ *
+ * @param request the resolution request containing group, artifact, and
version coordinates
+ * @return the resolution result containing the model source and resolved
version
+ * @throws ModelResolverException if the POM could not be resolved
+ */
@Nonnull
ModelResolverResult resolveModel(@Nonnull ModelResolverRequest request)
throws ModelResolverException;
diff --git
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
index 2c341d2709..7033eca3c4 100644
---
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
+++
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootDetector.java
@@ -28,5 +28,11 @@
* @since 4.0.0
*/
public interface RootDetector extends Service {
+ /**
+ * Checks whether the given directory is a project root directory.
+ *
+ * @param dir the directory to check
+ * @return {@code true} if the directory is a root directory, {@code
false} otherwise
+ */
boolean isRootDirectory(Path dir);
}
diff --git
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
index 739c279db8..d47e23748b 100644
---
a/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
+++
b/api/maven-api-spi/src/main/java/org/apache/maven/api/services/model/RootLocator.java
@@ -43,12 +43,31 @@ public interface RootLocator extends Service {
+ "Create a .mvn directory in the root directory or add the
root=\"true\""
+ " attribute on the root project's model to identify it.";
+ /**
+ * Finds the root directory by searching from the given base directory
upwards.
+ *
+ * @param basedir the starting directory for the search
+ * @return the root directory path, or {@code null} if none was found
+ */
@Nullable
Path findRoot(@Nonnull Path basedir);
+ /**
+ * Finds the root directory by searching from the given base directory
upwards,
+ * throwing an exception if no root can be found.
+ *
+ * @param basedir the starting directory for the search
+ * @return the root directory path, never {@code null}
+ * @throws IllegalStateException if no root directory can be found
+ */
@Nonnull
Path findMandatoryRoot(@Nonnull Path basedir);
+ /**
+ * Returns the error message to use when no root directory can be found.
+ *
+ * @return the error message, never {@code null}
+ */
@Nonnull
default String getNoRootMessage() {
return UNABLE_TO_FIND_ROOT_PROJECT_MESSAGE;
diff --git
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
index 4520f0650b..db16f7d4b1 100644
---
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
+++
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParserException.java
@@ -21,6 +21,12 @@
import org.apache.maven.api.annotations.Experimental;
import org.apache.maven.api.services.MavenException;
+/**
+ * Exception thrown when a model parser encounters an error while reading a
POM or other model source.
+ * Carries optional line and column number information to help locate the
error.
+ *
+ * @since 4.0.0
+ */
@Experimental
public class ModelParserException extends MavenException {
@@ -56,10 +62,20 @@ public ModelParserException(Throwable cause) {
this(null, cause);
}
+ /**
+ * Returns the one-based line number where the error occurred, or {@code
-1} if unknown.
+ *
+ * @return the line number
+ */
public int getLineNumber() {
return lineNumber;
}
+ /**
+ * Returns the one-based column number where the error occurred, or {@code
-1} if unknown.
+ *
+ * @return the column number
+ */
public int getColumnNumber() {
return columnNumber;
}
diff --git
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
index d2f8443826..a06acac628 100644
---
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
+++
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelTransformerException.java
@@ -21,6 +21,11 @@
import org.apache.maven.api.annotations.Experimental;
import org.apache.maven.api.services.MavenException;
+/**
+ * Exception thrown when a model transformation fails.
+ *
+ * @since 4.0.0
+ */
@Experimental
public class ModelTransformerException extends MavenException {
diff --git
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
index 4981fa5ba6..fc2daebd2c 100644
---
a/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
+++
b/api/maven-api-spi/src/main/java/org/apache/maven/api/spi/SettingsParserException.java
@@ -74,10 +74,20 @@ private static String messageOrDefault(String message,
Throwable cause) {
return "Unknown settings parsing error";
}
+ /**
+ * Returns the one-based line number where the error occurred, or {@code
-1} if unknown.
+ *
+ * @return the line number
+ */
public int getLineNumber() {
return lineNumber;
}
+ /**
+ * Returns the one-based column number where the error occurred, or {@code
-1} if unknown.
+ *
+ * @return the column number
+ */
public int getColumnNumber() {
return columnNumber;
}