[MNG-8233] Client should handle modelIds as "opaque" (#1701)
Javadoc states wrong things (about format of modelId, they are
paths in reality), but also these all are "implementation details".
Crafting modelIds to "walk" lineage is wrong, there is a dedicated
method that provide "opaque" key Strings in defined order to
do that. And client should not care (nor assume) anything
about format of the key String.
---
https://issues.apache.org/jira/browse/MNG-8233
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderResult.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderResult.java
index fcaf26b..4033aa2 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderResult.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelBuilderResult.java
@@ -36,9 +36,9 @@ public interface ModelBuilderResult {
/**
* Gets the sequence of model identifiers that denote the lineage of models from which the effective model was
- * constructed. Model identifiers have the form {@code <groupId>:<artifactId>:<version>}. The first identifier from
- * the list denotes the model on which the model builder was originally invoked. The last identifier will always be
- * an empty string that by definition denotes the super POM.
+ * constructed. Model identifiers should be handled as "opaque strings" and this method should be used as source
+ * if navigating the linage. The first identifier from the list denotes the model on which the model builder
+ * was originally invoked. The last identifier will always be the super POM.
*
* @return The model identifiers from the lineage of models, never {@code null}.
*/
@@ -80,9 +80,9 @@ public interface ModelBuilderResult {
/**
* Gets the specified raw model as it was read from a model source. Apart from basic validation, a raw model has not
* undergone any updates by the model builder, e.g. reflects neither inheritance nor interpolation. The model
- * identifier should be from the collection obtained by {@link #getModelIds()}. As a special case, an empty string
- * can be used as the identifier for the super POM.
+ * identifier should be from the collection obtained by {@link #getModelIds()}.
*
+ * @see #getModelIds()
* @param modelId The identifier of the desired raw model, must not be {@code null}.
* @return The raw model or {@code null} if the specified model id does not refer to a known model.
*/
@@ -91,9 +91,9 @@ public interface ModelBuilderResult {
/**
* Gets the profiles from the specified model that were active during model building. The model identifier should be
- * from the collection obtained by {@link #getModelIds()}. As a special case, an empty string can be used as the
- * identifier for the super POM.
+ * from the collection obtained by {@link #getModelIds()}.
*
+ * @see #getModelIds()
* @param modelId The identifier of the model whose active profiles should be retrieved, must not be {@code null}.
* @return The active profiles of the model or an empty list if the specified model id does
* not refer to a known model or has no active profiles.
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java
index f15fe0d..eda871c 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ModelProblem.java
@@ -40,11 +40,11 @@ enum Version {
}
/**
- * Gets the identifier of the model from which the problem originated. While the general form of this identifier is
- * <code>groupId:artifactId:version</code> the returned identifier need not be complete. The identifier is derived
- * from the information that is available at the point the problem occurs and as such merely serves as a best effort
+ * Gets the identifier of the model from which the problem originated. The identifier is derived from the
+ * information that is available at the point the problem occurs and as such merely serves as best effort
* to provide information to the user to track the problem back to its origin.
*
+ * @see ModelBuilderResult#getModelIds()
* @return The identifier of the model from which the problem originated or an empty string if unknown, never
* {@code null}.
*/
diff --git a/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelBuildingResult.java b/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelBuildingResult.java
index d4238e8..3c98795 100644
--- a/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelBuildingResult.java
+++ b/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelBuildingResult.java
@@ -31,9 +31,9 @@ public interface ModelBuildingResult {
/**
* Gets the sequence of model identifiers that denote the lineage of models from which the effective model was
- * constructed. Model identifiers have the form {@code <groupId>:<artifactId>:<version>}. The first identifier from
- * the list denotes the model on which the model builder was originally invoked. The last identifier will always be
- * an empty string that by definition denotes the super POM.
+ * constructed. Model identifiers should be handled as "opaque strings" and this method should be used as source
+ * if navigating the linage. The first identifier from the list denotes the model on which the model builder
+ * was originally invoked. The last identifier will always be the super POM.
*
* @return The model identifiers from the lineage of models, never {@code null}.
*/
@@ -64,9 +64,9 @@ public interface ModelBuildingResult {
/**
* Gets the specified raw model as it was read from a model source. Apart from basic validation, a raw model has not
* undergone any updates by the model builder, e.g. reflects neither inheritance nor interpolation. The model
- * identifier should be from the collection obtained by {@link #getModelIds()}. As a special case, an empty string
- * can be used as the identifier for the super POM.
+ * identifier should be from the collection obtained by {@link #getModelIds()}.
*
+ * @see #getModelIds()
* @param modelId The identifier of the desired raw model, must not be {@code null}.
* @return The raw model or {@code null} if the specified model id does not refer to a known model.
*/
@@ -74,9 +74,9 @@ public interface ModelBuildingResult {
/**
* Gets the profiles from the specified model that were active during model building. The model identifier should be
- * from the collection obtained by {@link #getModelIds()}. As a special case, an empty string can be used as the
- * identifier for the super POM.
+ * from the collection obtained by {@link #getModelIds()}.
*
+ * @see #getModelIds()
* @param modelId The identifier of the model whose active profiles should be retrieved, must not be {@code null}.
* @return The active profiles of the model or an empty list if none or {@code null} if the specified model id does
* not refer to a known model.
diff --git a/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelProblem.java b/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelProblem.java
index 16ca418..9c0cc10 100644
--- a/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelProblem.java
+++ b/maven-model-builder/src/main/java/org/apache/maven/model/building/ModelProblem.java
@@ -18,6 +18,8 @@
*/
package org.apache.maven.model.building;
+import org.apache.maven.api.services.ModelBuilderResult;
+
/**
* Describes a problem that was encountered during model building. A problem can either be an exception that was thrown
* or a simple string message. In addition, a problem carries a hint about its source, e.g. the POM file that exhibits
@@ -49,11 +51,11 @@ enum Version {
}
/**
- * Gets the hint about the source of the problem. While the syntax of this hint is unspecified and depends on the
- * creator of the problem, the general expectation is that the hint provides sufficient information to the user to
- * track the problem back to its origin. A concrete example for such a source hint can be the file path or URL from
- * which a POM was read.
+ * Gets the identifier of the model from which the problem originated. The identifier is derived from the
+ * information that is available at the point the problem occurs and as such merely serves as best effort
+ * to provide information to the user to track the problem back to its origin.
*
+ * @see ModelBuilderResult#getModelIds()
* @return The hint about the source of the problem or an empty string if unknown, never {@code null}.
*/
String getSource();
