Improve o.a.m.api.services.Source interface (#1236)

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();
 }

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

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

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