Images.pull, import and Image.history

Author: amihaiemil

src/main/java/com/amihaiemil/docker/Image.java

@@ -49,10 +49,10 @@ public interface Image extends JsonObject {
 
     /**
      * Return parent layers of this Image.
-     * @return Images parent Images.
+     * @return An Iterable containing the parents of this Image.
      * @see <a href="https://docs.docker.com/engine/api/v1.35/#operation/ImageHistory">Image History</a>
      */
-    Images history();
+    Iterable<Image> history();
 
     /**
      * Remove an image, along with any untagged parent images that were

src/main/java/com/amihaiemil/docker/Images.java

@@ -40,19 +40,31 @@
 public interface Images extends Iterable<Image> {
 
     /**
-     * Creates an image by pulling it from a registry.
+     * Pull an Image from the Docker registry.
      * @param name Name of the image to pull.
-     * @param source The URL from which the image can be retrieved.
-     * @param repo Repository name for the image when it is pulled.
      * @param tag Tag or digest for the image.
-     * @return This {@link Images}.
+     * @return The created {@link Image}.
      * @throws IOException If an I/O error occurs.
      * @throws UnexpectedResponseException If the API responds with an 
      *  unexpected status.
      * @checkstyle ParameterNumber (4 lines)
      */
-    Images create(
-        final String name, final URL source, final String repo, final String tag
+    Image pull(
+        final String name, final String tag
+    ) throws IOException, UnexpectedResponseException;
+
+    /**
+     * Import an Image.
+     * @param source The URL from which the image can be retrieved.
+     * @param repo Repository name given to an image when it is imported.
+     *   The repo may include a tag.
+     * @return The imported Image.
+     * @throws IOException If an I/O error occurs.
+     * @throws UnexpectedResponseException If the API responds with an
+     *  undexpected status.
+     */
+    Image importImage(
+        final URL source, final String repo
     ) throws IOException, UnexpectedResponseException;
 
     /**

src/main/java/com/amihaiemil/docker/RtImage.java

@@ -31,6 +31,7 @@
 import org.apache.http.HttpStatus;
 import org.apache.http.client.HttpClient;
 import org.apache.http.client.methods.HttpDelete;
+import org.apache.http.client.methods.HttpGet;
 import org.apache.http.client.methods.HttpPost;
 
 /**
@@ -69,9 +70,17 @@ public JsonObject inspect()
     }
 
     @Override
-    public Images history() {
-        return new RtImages(
-            this.client, URI.create(this.baseUri.toString() + "/history")
+    public Iterable<Image> history() {
+        return () -> new ResourcesIterator<>(
+            this.client,
+            new HttpGet(this.baseUri.toString().concat("/history")),
+            json -> new RtImage(
+                json,
+                 this.client,
+                URI.create(
+                    this.baseUri.toString() + "/" + json.getString("Id")
+                )
+            )
         );
     }
 

src/main/java/com/amihaiemil/docker/RtImages.java

@@ -34,6 +34,8 @@
 import org.apache.http.client.methods.HttpGet;
 import org.apache.http.client.methods.HttpPost;
 
+import javax.json.Json;
+
 /**
  * Runtime {@link Images}.
  * @author George Aristy (george.aristy@gmail.com)
@@ -61,16 +63,13 @@ final class RtImages implements Images {
         this.baseUri = uri;
     }
 
-    // @checkstyle ParameterNumber (4 lines)
     @Override
-    public Images create(
-        final String name, final URL source, final String repo, final String tag
+    public Image pull(
+        final String name, final String tag
     ) throws IOException, UnexpectedResponseException {
         final HttpPost create  = new HttpPost(
             new UncheckedUriBuilder(this.baseUri.toString().concat("/create"))
                 .addParameter("fromImage", name)
-                .addParameter("fromSrc", source.toString())
-                .addParameter("repo", repo)
                 .addParameter("tag", tag)
                 .build()
         );
@@ -79,12 +78,28 @@ public Images create(
                 create,
                 new MatchStatus(create.getURI(), HttpStatus.SC_OK)
             );
-            return this;
+            return new RtImage(
+                Json.createObjectBuilder().add("Name", name).build(),
+                this.client,
+                URI.create(
+                    this.baseUri.toString() + "/" + name
+                )
+            );
         } finally {
             create.releaseConnection();
         }
     }
 
+    @Override
+    public Image importImage(
+        final URL source, final String repo
+    ) throws IOException, UnexpectedResponseException {
+        throw new UnsupportedOperationException(
+            "Not yet implemented. If you can contribute please,"
+            + " do it here: https://www.github.com/amihaiemil/docker-java-api"
+        );
+    }
+
     @Override
     public void prune() throws IOException, UnexpectedResponseException {
         final HttpPost prune = new HttpPost(

src/test/java/com/amihaiemil/docker/RtImageTestCase.java

@@ -109,7 +109,7 @@ public void returnsHistory() {
             ).history(),
             Matchers.allOf(
                 Matchers.notNullValue(),
-                Matchers.instanceOf(Images.class)
+                Matchers.instanceOf(Iterable.class)
             )
         );
     }

src/test/java/com/amihaiemil/docker/RtImagesTestCase.java

@@ -29,7 +29,6 @@
 import com.amihaiemil.docker.mock.Condition;
 import com.amihaiemil.docker.mock.Response;
 import java.net.URI;
-import java.net.URL;
 import java.util.concurrent.atomic.AtomicInteger;
 import javax.json.Json;
 import org.apache.http.HttpStatus;
@@ -48,10 +47,9 @@ public final class RtImagesTestCase {
     /**
      * Must return the same number of images as there are elements in the
      * json array returned by the service.
-     * @throws Exception If an error occurs.
      */
     @Test
-    public void iteratesImages() throws Exception {
+    public void iteratesImages() {
         final AtomicInteger count = new AtomicInteger();
         new RtImages(
             new AssertRequest(
@@ -110,7 +108,7 @@ public void iterateFailsIfResponseIs500() throws Exception {
     }
 
     /**
-     * {@link RtImages#create(String, URL, String, String)} must construct the
+     * {@link RtImages#pull(String, String)} must construct the
      * URL with parameters correctly.
      * <p>
      * Notice the escaped characters for the 'fromSrc' parameter's value.
@@ -128,17 +126,13 @@ public void createSetsGivenParameters() throws Exception {
                         System.out.println(req.getRequestLine().getUri());
                         return req.getRequestLine().getUri().endsWith(
                             // @checkstyle LineLength (1 line)
-                            "/create?fromImage=testImage&fromSrc=http%3A%2F%2Fdocker.registry.com&repo=testRepo&tag=1.23"
+                            "/create?fromImage=testImage&tag=1.23"
                         );
                     }
                 )
             ),
             URI.create("http://localhost")
-        )
-            .create(
-                "testImage", new URL("http://docker.registry.com"),
-                "testRepo", "1.23"
-        );
+        ).pull("testImage", "1.23");
     }
 
     /**
@@ -153,7 +147,7 @@ public void createErrorOnStatus404() throws Exception {
                 new Response(HttpStatus.SC_NOT_FOUND)
             ),
             URI.create("http://localhost")
-        ).create("", new URL("http://registry.docker.com"), "", "");
+        ).pull("", "");
     }
 
     /**
@@ -168,7 +162,7 @@ public void createErrorOnStatus500() throws Exception {
                 new Response(HttpStatus.SC_INTERNAL_SERVER_ERROR)
             ),
             URI.create("http://localhost")
-        ).create("", new URL("http://registry.docker.com"), "", "");
+        ).pull("", "");
     }
 
     /**