ImageApi Class — spring-boot Architecture

Source Code

buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/DockerApi.java lines 208–400

	public class ImageApi {

		ImageApi() {
		}

		/**
		 * Pull an image from a registry.
		 * @param reference the image reference to pull
		 * @param platform the platform (os/architecture/variant) of the image to pull
		 * @param listener a pull listener to receive update events
		 * @return the {@link ImageApi pulled image} instance
		 * @throws IOException on IO error
		 */
		public Image pull(ImageReference reference, @Nullable ImagePlatform platform,
				UpdateListener<PullImageUpdateEvent> listener) throws IOException {
			return pull(reference, platform, listener, null);
		}

		/**
		 * Pull an image from a registry.
		 * @param reference the image reference to pull
		 * @param platform the platform (os/architecture/variant) of the image to pull
		 * @param listener a pull listener to receive update events
		 * @param registryAuth registry authentication credentials
		 * @return the {@link ImageApi pulled image} instance
		 * @throws IOException on IO error
		 */
		public Image pull(ImageReference reference, @Nullable ImagePlatform platform,
				UpdateListener<PullImageUpdateEvent> listener, @Nullable String registryAuth) throws IOException {
			Assert.notNull(reference, "'reference' must not be null");
			Assert.notNull(listener, "'listener' must not be null");
			URI createUri = (platform != null) ? buildUrl(Feature.PLATFORM_IMAGE_PULL, "/images/create", "fromImage",
					reference, "platform", platform) : buildUrl("/images/create", "fromImage", reference);
			DigestCaptureUpdateListener digestCapture = new DigestCaptureUpdateListener();
			listener.onStart();
			try {
				try (Response response = http().post(createUri, registryAuth)) {
					jsonStream().get(response.getContent(), PullImageUpdateEvent.class, (event) -> {
						digestCapture.onUpdate(event);
						listener.onUpdate(event);
					});
				}
				return inspect(reference, platform);
			}
			finally {
				listener.onFinish();
			}
		}

		/**
		 * Push an image to a registry.
		 * @param reference the image reference to push
		 * @param listener a push listener to receive update events
		 * @param registryAuth registry authentication credentials
		 * @throws IOException on IO error
		 */
		public void push(ImageReference reference, UpdateListener<PushImageUpdateEvent> listener,
				@Nullable String registryAuth) throws IOException {
			Assert.notNull(reference, "'reference' must not be null");
			Assert.notNull(listener, "'listener' must not be null");
			URI pushUri = buildUrl("/images/" + reference + "/push");
			ErrorCaptureUpdateListener errorListener = new ErrorCaptureUpdateListener();
			listener.onStart();
			try {
				try (Response response = http().post(pushUri, registryAuth)) {
					jsonStream().get(response.getContent(), PushImageUpdateEvent.class, (event) -> {
						errorListener.onUpdate(event);
						listener.onUpdate(event);
					});
				}
			}
			finally {
				listener.onFinish();
			}
		}

		/**
		 * Load an {@link ImageArchive} into Docker.
		 * @param archive the archive to load
		 * @param listener a pull listener to receive update events
		 * @throws IOException on IO error
		 */
		public void load(ImageArchive archive, UpdateListener<LoadImageUpdateEvent> listener) throws IOException {
			Assert.notNull(archive, "'archive' must not be null");
			Assert.notNull(listener, "'listener' must not be null");
			URI loadUri = buildUrl("/images/load");
			LoadImageUpdateListener streamListener = new LoadImageUpdateListener(archive);
			listener.onStart();
			try {
				try (Response response = http().post(loadUri, "application/x-tar", archive::writeTo)) {
					InputStream content = response.getContent();
					if (content != null) {
						jsonStream().get(content, LoadImageUpdateEvent.class, (event) -> {
							streamListener.onUpdate(event);
							listener.onUpdate(event);
						});
					}
				}
				streamListener.assertValidResponseReceived();
			}
			finally {
				listener.onFinish();
			}
		}

		/**
		 * Export the layers of an image as {@link TarArchive TarArchives}.
		 * @param reference the reference to export
		 * @param exports a consumer to receive the layers (contents can only be accessed
		 * during the callback)
		 * @throws IOException on IO error
		 */
		public void exportLayers(ImageReference reference, IOBiConsumer<String, TarArchive> exports)
				throws IOException {
			exportLayers(reference, null, exports);
		}

		/**
		 * Export the layers of an image as {@link TarArchive TarArchives}.
		 * @param reference the reference to export
		 * @param platform the platform (os/architecture/variant) of the image to export.
		 * Ignored on older versions of Docker.
		 * @param exports a consumer to receive the layers (contents can only be accessed
		 * during the callback)
		 * @throws IOException on IO error
		 * @since 3.4.12
		 */
		public void exportLayers(ImageReference reference, @Nullable ImagePlatform platform,
				IOBiConsumer<String, TarArchive> exports) throws IOException {
			Assert.notNull(reference, "'reference' must not be null");
			Assert.notNull(exports, "'exports' must not be null");
			URI uri = buildPlatformJsonUrl(Feature.PLATFORM_IMAGE_EXPORT, platform, "/images/" + reference + "/get");
			try (Response response = http().get(uri)) {
				try (ExportedImageTar exportedImageTar = new ExportedImageTar(reference, response.getContent())) {
					exportedImageTar.exportLayers(exports);
				}
			}
		}

		/**
		 * Remove a specific image.
		 * @param reference the reference the remove
		 * @param force if removal should be forced
		 * @throws IOException on IO error
		 */
		public void remove(ImageReference reference, boolean force) throws IOException {
			Assert.notNull(reference, "'reference' must not be null");
			Collection<String> params = force ? FORCE_PARAMS : Collections.emptySet();
			URI uri = buildUrl("/images/" + reference, params);
			http().delete(uri).close();
		}

		/**
		 * Inspect an image.
		 * @param reference the image reference
		 * @return the image from the local repository
		 * @throws IOException on IO error
		 */
		public Image inspect(ImageReference reference) throws IOException {
			return inspect(reference, null);
		}

		/**
		 * Inspect an image.
		 * @param reference the image reference
		 * @param platform the platform (os/architecture/variant) of the image to inspect.
		 * Ignored on older versions of Docker.
		 * @return the image from the local repository
		 * @throws IOException on IO error
		 * @since 3.4.12
		 */
		public Image inspect(ImageReference reference, @Nullable ImagePlatform platform) throws IOException {
			// The Docker documentation is incomplete but platform parameters
			// are supported since 1.49 (see https://github.com/moby/moby/pull/49586)
			Assert.notNull(reference, "'reference' must not be null");
			URI inspectUrl = buildPlatformJsonUrl(Feature.PLATFORM_IMAGE_INSPECT, platform,
					"/images/" + reference + "/json");
			try (Response response = http().get(inspectUrl)) {
				return Image.of(response.getContent());
			}
		}

		public void tag(ImageReference sourceReference, ImageReference targetReference) throws IOException {
			Assert.notNull(sourceReference, "'sourceReference' must not be null");
			Assert.notNull(targetReference, "'targetReference' must not be null");
			String tag = targetReference.getTag();
			String path = "/images/" + sourceReference + "/tag";
			URI uri = (tag != null) ? buildUrl(path, "repo", targetReference.inTaglessForm(), "tag", tag)
					: buildUrl(path, "repo", targetReference);
			http().post(uri).close();
		}

	}