Package org.jenkinsci.plugins.docker.commons.fingerprint

Class DockerFingerprints

java.lang.Object

org.jenkinsci.plugins.docker.commons.fingerprint.DockerFingerprints

public class DockerFingerprints
extends Object

Entry point into fingerprint related functionalities in Docker. This class provide basic methods for both images and containers

Method Summary

Modifier and Type	Method	Description
static void	addFromFacet(String ancestorImageId, String descendantImageId, Run<?,?> run)	Creates a new DockerAncestorFingerprintFacet and DockerDescendantFingerprintFacet and adds a run.
static void	addRunFacet(ContainerRecord record, Run<?,?> run)	Adds a new ContainerRecord for the specified image, creating necessary intermediate objects as it goes.
static Fingerprint	forContainer(Run<?,?> run, String id)	Deprecated. Use forContainer(hudson.model.Run, java.lang.String, java.lang.String)
static Fingerprint	forContainer(Run<?,?> run, String id, String name)	Get or create a Fingerprint for the container.
static Fingerprint	forImage(Run<?,?> run, String id)	Deprecated. Use forImage(hudson.model.Run, java.lang.String, java.lang.String)
static Fingerprint	forImage(Run<?,?> run, String id, String name)	Get or create a Fingerprint for the image.
static <TFacet extends FingerprintFacet> TFacet	getFacet(Fingerprint fingerprint, Class<TFacet> facetClass)	Retrieves a facet from the Fingerprint.
static <TFacet extends FingerprintFacet> TFacet	getFacet(String id, Class<TFacet> facetClass)	Retrieves a facet from the Fingerprint.
static <TFacet extends FingerprintFacet> Collection<TFacet>	getFacets(Fingerprint fingerprint, Class<TFacet> facetClass)	Retrieves facets from the Fingerprint.
static <TFacet extends FingerprintFacet> Collection<TFacet>	getFacets(String id, Class<TFacet> facetClass)	Retrieves a facet from the Fingerprint.
static String	getFingerprintHash(String id)	Gets a fingerprint hash for Docker ID (image or container).
static Fingerprint	of(String id)	Gets Fingerprint for a given docker ID.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

getFingerprintHash

@NonNull
public static String getFingerprintHash(@NonNull
 String id)

Gets a fingerprint hash for Docker ID (image or container). This method calculates image hash without retrieving a fingerprint by of(java.lang.String), which may be a high-cost call.

Parameters:

id - Docker ID (image or container). Only 64-char full IDs are supported.

Returns:

32-char fingerprint hash

Throws:

IllegalArgumentException - Invalid ID

of

@CheckForNull
public static Fingerprint of(@NonNull
 String id)
                      throws IOException

Gets Fingerprint for a given docker ID.

Parameters:

id - Docker ID (image or container). Only 64-char full IDs are supported.

Returns:

Created fingerprint or null if it is not found

Throws:

IOException - Fingerprint loading error

forImage

@NonNull
public static Fingerprint forImage(@CheckForNull
 Run<?,?> run,
 @NonNull
 String id)
                            throws IOException

Deprecated.

Use forImage(hudson.model.Run, java.lang.String, java.lang.String)

Throws:

IOException

forImage

@NonNull
public static Fingerprint forImage(@CheckForNull
 Run<?,?> run,
 @NonNull
 String id,
 @CheckForNull
 String name)
                            throws IOException

Get or create a Fingerprint for the image.

Parameters:

run - Origin of the fingerprint (if available)

id - Image ID. Only 64-char full IDs are supported.

name - Optional name of the image. If null, the image name will be constructed using the specified ID.

Returns:

Fingerprint for the specified ID

Throws:

IOException - Fingerprint load/save error

Since:

TODO

forContainer

@Deprecated
@NonNull
public static Fingerprint forContainer(@CheckForNull
 Run<?,?> run,
 @NonNull
 String id)
                                throws IOException

Deprecated.

Use forContainer(hudson.model.Run, java.lang.String, java.lang.String)

Throws:

IOException

forContainer

@NonNull
public static Fingerprint forContainer(@CheckForNull
 Run<?,?> run,
 @NonNull
 String id,
 @CheckForNull
 String name)
                                throws IOException

Get or create a Fingerprint for the container.

Parameters:

run - Origin of the fingerprint (if available)

id - Container ID. Only 64-char full IDs are supported.

name - Optional name of the container. If null, the container name will be constructed using the specified ID.

Returns:

Fingerprint for the specified ID

Throws:

IOException - Fingerprint load/save error

Since:

TODO

getFacet

@CheckForNull
public static <TFacet extends FingerprintFacet>
TFacet getFacet(@NonNull
 String id,
 @NonNull
 Class<TFacet> facetClass)

Retrieves a facet from the Fingerprint. The method suppresses IOException if a fingerprint loading fails.

Type Parameters:

TFacet - Facet type to be retrieved

Parameters:

id - Docker item ID. Only 64-char full IDs are supported

facetClass - Class to be retrieved

Returns:

First matching facet. Null may be returned if there is no facet or if the loading fails

getFacets

@NonNull
public static <TFacet extends FingerprintFacet>
Collection<TFacet> getFacets(@NonNull
 String id,
 @NonNull
 Class<TFacet> facetClass)

Retrieves a facet from the Fingerprint. The method suppresses IOException if a fingerprint loading fails.

Type Parameters:

TFacet - Facet type to be retrieved

Parameters:

id - Docker item ID. Only 64-char full IDs are supported

facetClass - Class to be retrieved

Returns:

First matching facet. Null may be returned if the loading fails

getFacet

@CheckForNull
public static <TFacet extends FingerprintFacet>
TFacet getFacet(@NonNull
 Fingerprint fingerprint,
 @NonNull
 Class<TFacet> facetClass)

Retrieves a facet from the Fingerprint.

Type Parameters:

TFacet - Facet type to be retrieved

Parameters:

fingerprint - Fingerprint, which stores facets

facetClass - Class to be retrieved

Returns:

First matching facet.

getFacets

@NonNull
public static <TFacet extends FingerprintFacet>
Collection<TFacet> getFacets(@NonNull
 Fingerprint fingerprint,
 @NonNull
 Class<TFacet> facetClass)

Retrieves facets from the Fingerprint.

Type Parameters:

TFacet - Facet type to be retrieved

Parameters:

fingerprint - Fingerprint, which stores facets

facetClass - Facet class to be retrieved

Returns:

All found facets

addRunFacet

public static void addRunFacet(@NonNull
 ContainerRecord record,
 @NonNull
 Run<?,?> run)
                        throws IOException

Adds a new ContainerRecord for the specified image, creating necessary intermediate objects as it goes.

Throws:

IOException

addFromFacet

public static void addFromFacet(@CheckForNull
 String ancestorImageId,
 @NonNull
 String descendantImageId,
 @NonNull
 Run<?,?> run)
                         throws IOException

Creates a new DockerAncestorFingerprintFacet and DockerDescendantFingerprintFacet and adds a run. Or adds to existing facets.

Parameters:

ancestorImageId - the ID of the image specified in a FROM instruction, or null in case of scratch (i.e., the descendant is a base image)

descendantImageId - the ID of the image which was built

run - the build in which the image building occurred

Throws:

IOException