From e71d2d71674719b8b1fb3aac02299f5bbe041f6a Mon Sep 17 00:00:00 2001
From: Guillaume Nodet <gnodet@gmail.com>
Date: Mon, 11 Sep 2023 18:14:36 +0200
Subject: [PATCH] Improve o.a.m.api.services.Source interface (#1236)

---
 .../org/apache/maven/api/services/Source.java | 43 ++++++++++++++++++-
 .../internal/impl/DefaultProjectBuilder.java  |  2 +-
 .../internal/impl/DefaultSettingsBuilder.java |  2 +-
 .../impl/DefaultToolchainsBuilder.java        |  2 +-
 4 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Source.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Source.java
index d10c186898..308adde257 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Source.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Source.java
@@ -20,17 +20,56 @@
 
 import java.io.IOException;
 import java.io.InputStream;
+import java.nio.file.Path;
 
+import org.apache.maven.api.Session;
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Nullable;
 
 /**
- * The source for a project's XML model.
+ * Provides access to the contents of a source independently of the
+ * backing store (e.g. file system, database, memory).
+ * <p>
+ * This is mainly used to parse files into objects such as
+ * {@link org.apache.maven.api.Project},
+ * {@link org.apache.maven.api.model.Model},
+ * {@link org.apache.maven.api.settings.Settings}, or
+ * {@link org.apache.maven.api.toolchain.PersistedToolchains}.
  *
  * @since 4.0.0
+ * @see org.apache.maven.api.services.ProjectBuilder#build(Session, Source)
+ * @see org.apache.maven.api.services.SettingsBuilder#build(Session, Source, Source, Source)
+ * @see org.apache.maven.api.services.ToolchainsBuilder#build(Session, Source, Source)
  */
 @Experimental
 public interface Source {
-    InputStream getInputStream() throws IOException;
 
+    /**
+     * Provides access the file to be parsed, if this source is backed by a file.
+     *
+     * @return the underlying {@code Path}, or {@code null} if this source is not backed by a file
+     */
+    @Nullable
+    Path getPath();
+
+    /**
+     * Creates a new byte stream to the source contents.
+     * Closing the returned stream is the responsibility of the caller.
+     *
+     * @return a byte stream to the source contents, never {@code null}
+     * @throws IOException in case of IO issue
+     */
+    @Nonnull
+    InputStream openStream() throws IOException;
+
+    /**
+     * Provides a user-friendly hint about the location of the source.
+     * This could be a local file path, a URI or just an empty string.
+     * The intention is to assist users during error reporting.
+     *
+     * @return a user-friendly hint about the location of the source, never {@code null}
+     */
+    @Nonnull
     String getLocation();
 }
diff --git a/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultProjectBuilder.java b/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultProjectBuilder.java
index d006144e27..30520920be 100644
--- a/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultProjectBuilder.java
+++ b/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultProjectBuilder.java
@@ -85,7 +85,7 @@ public ProjectBuilderResult build(ProjectBuilderRequest request)
                 ModelSource modelSource = new ModelSource() {
                     @Override
                     public InputStream getInputStream() throws IOException {
-                        return source.getInputStream();
+                        return source.openStream();
                     }
 
                     @Override
diff --git a/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultSettingsBuilder.java b/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultSettingsBuilder.java
index ae3c0d0d36..a21c5b0ea5 100644
--- a/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultSettingsBuilder.java
+++ b/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultSettingsBuilder.java
@@ -108,7 +108,7 @@ private static class MappedSettingsSource implements SettingsSource {
 
         @Override
         public InputStream getInputStream() throws IOException {
-            return source.getInputStream();
+            return source.openStream();
         }
 
         @Override
diff --git a/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultToolchainsBuilder.java b/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultToolchainsBuilder.java
index 37ad856e0e..cff334d788 100644
--- a/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultToolchainsBuilder.java
+++ b/maven-core/src/main/java/org/apache/maven/internal/impl/DefaultToolchainsBuilder.java
@@ -95,7 +95,7 @@ private static class MappedToolchainsSource implements org.apache.maven.building
 
         @Override
         public InputStream getInputStream() throws IOException {
-            return source.getInputStream();
+            return source.openStream();
         }
 
         @Override