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 Detail

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