API Improvements

Author: gnodet

api/maven-api-core/src/main/java/org/apache/maven/api/services/PathSource.java

@@ -42,7 +42,7 @@ public Path getPath() {
 
     @Nonnull
     @Override
-    public InputStream getInputStream() throws IOException {
+    public InputStream openStream() throws IOException {
         return Files.newInputStream(path);
     }
 

api/maven-api-core/src/main/java/org/apache/maven/api/services/Source.java

@@ -48,26 +48,28 @@ public interface Source {
     /**
      * 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.
+     * @return the underlying {@code Path}, or {@code null} if this source is not backed by a file
      */
     @Nullable
     Path getPath();
 
     /**
-     * Gets a byte stream to the source contents. Closing the returned stream is the responsibility of the caller.
+     * 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}.
+     * @return a byte stream to the source contents, never {@code null}
      * @throws IOException in case of IO issue
      */
     @Nonnull
-    InputStream getInputStream() throws IOException;
+    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.
+     * 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}.
+     * @return a user-friendly hint about the location of the source, never {@code null}
      */
-    @Nullable
+    @Nonnull
     String getLocation();
 }

api/maven-api-spi/src/main/java/org/apache/maven/api/spi/ModelParser.java

@@ -39,13 +39,14 @@ public interface ModelParser {
      * Locates the pom in the given directory.
      *
      * @param dir the directory to locate the pom for, never {@code null}
-     * @return the located pom or <code>null</code> if none was found by this parser
+     * @return a {@code Source} pointing to the located pom or an empty {@code Optional} if none was found by this parser
      */
     @Nonnull
     Optional<Source> locate(@Nonnull Path dir);
 
     /**
-     * Parse the model.
+     * Parse the model obtained previously by a previous call to {@link #locate(Path)}.
+     *
      *
      * @param source the source to parse, never {@code null}
      * @param options possible parsing options, may be {@code null}

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

maven-model-builder/src/main/java/org/apache/maven/model/building/FileSource.java

@@ -36,7 +36,7 @@ public Path getPath() {
     }
 
     @Override
-    public InputStream getInputStream() throws IOException {
+    public InputStream openStream() throws IOException {
         return Files.newInputStream(pom);
     }