org.eclipse.jkube.kit.build.service.docker.access.hc

Class DockerAccessWithHcClient

java.lang.Object

org.eclipse.jkube.kit.build.service.docker.access.hc.DockerAccessWithHcClient

All Implemented Interfaces:

DockerAccess

public class DockerAccessWithHcClient
extends Object
implements DockerAccess

Implementation using Apache HttpComponents for remotely accessing the docker host.

The design goal here is to provide only the functionality required for this plugin in order to make it as robust as possible against docker API changes (which happen quite frequently). That's also the reason, why no framework like JAX-RS or docker-java is used so that the dependencies are kept low.

Of course, it's a bit more manual work, but it's worth the effort (as long as the Docker API functionality required is not too much).

Since:

26.03.14

Author:

roland

Field Summary

Fields

Modifier and Type	Field and Description
static String	API_VERSION

Constructor Summary

Constructors

Constructor and Description
DockerAccessWithHcClient(String baseUrl, String certPath, int maxConnections, org.eclipse.jkube.kit.common.KitLogger log) Create a new access for the given URL

Method Summary

Modifier and Type	Method and Description
void	buildImage(String image, File dockerArchive, BuildOptions options) Create an docker image from a given archive
void	copyArchive(String containerId, File archive, String targetPath) Copy an archive (must be a tar) into a running container Get all containers matching a certain label.
String	createContainer(ContainerCreateConfig containerConfig, String containerName) Create a container from the given image.
String	createExecContainer(String containerId, org.eclipse.jkube.kit.common.Arguments arguments) Sets up an exec instance for a running container id
String	createNetwork(NetworkCreateConfig networkConfig) Create a custom network from the given configuration.
String	createVolume(VolumeCreateConfig containerConfig) Create a volume
String	fetchApiVersionFromServer(String baseUrl, ApacheHttpClientDelegate delegate)
ContainerDetails	getContainer(String containerIdOrName) Get a container
List<Container>	getContainersForImage(String image, boolean all) Get all containers which are build from an image.
ExecDetails	getExecContainer(String containerIdOrName) Get an exec container which is the result of executing a command in a running container.
String	getImageId(String name) Get the image id of a given name or null if no such image exists
LogGetHandle	getLogAsync(String containerId, LogCallback callback) Get logs asynchronously.
void	getLogSync(String containerId, LogCallback callback) Get logs for a container up to now synchronously.
String	getServerApiVersion() Get the API version of the running server
boolean	hasImage(String name) Check whether the given name exists as image at the docker daemon
List<Network>	listNetworks() List all networks
void	loadImage(String image, File tarArchive) Load an image from an archive.
void	pullImage(String image, AuthConfig authConfig, String registry, CreateImageOptions options) Pull an image from a remote registry and store it locally.
void	pushImage(String image, AuthConfig authConfig, String registry, int retries) Push an image to a registry.
void	removeContainer(String containerId, boolean removeVolumes) Remove a container with the given id
boolean	removeImage(String image, boolean... forceOpt) Remove an image from this docker installation
boolean	removeNetwork(String networkId) Remove a custom network
void	removeVolume(String name) Removes a volume.
void	saveImage(String image, String filename, org.eclipse.jkube.kit.common.archive.ArchiveCompression compression) Save an image to a tar file
void	shutdown() Lifecycle method which must be called when this object is not needed anymore.
void	start() Lifecycle method for this access class which must be called before any other method is called.
void	startContainer(String containerId) Start a container.
void	startExecContainer(String containerId, LogOutputSpec outputSpec) Starts a previously set up exec instance (via DockerAccess.createExecContainer(String, Arguments) container this API sets up a session with the exec command.
void	stopContainer(String containerId, int killWait) Stop a container.
void	tag(String sourceImage, String targetImage, boolean force) Alias an image in the repository with a complete new name.

Methods inherited from class java.lang.Object

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

Field Detail

API_VERSION

public static final String API_VERSION

See Also:

Constant Field Values

Constructor Detail

DockerAccessWithHcClient

public DockerAccessWithHcClient(String baseUrl,
                                String certPath,
                                int maxConnections,
                                org.eclipse.jkube.kit.common.KitLogger log)
                         throws IOException

Create a new access for the given URL

Parameters:

baseUrl - base URL for accessing the docker Daemon

certPath - used to build up a keystore with the given keys and certificates found in this directory

maxConnections - maximum parallel connections allowed to docker daemon (if a pool is used)

log - a log handler for printing out logging information

Throws:

IOException - in case of I/O exception

Method Detail

getServerApiVersion

public String getServerApiVersion()
                           throws DockerAccessException

Get the API version of the running server

Specified by:

getServerApiVersion in interface DockerAccess

Returns:

api version in the form "1.24"

Throws:

DockerAccessException - if the api version could not be obtained

startExecContainer

public void startExecContainer(String containerId,
                               LogOutputSpec outputSpec)
                        throws DockerAccessException

Description copied from interface: DockerAccess

Starts a previously set up exec instance (via DockerAccess.createExecContainer(String, Arguments) container this API sets up a session with the exec command. Output is streamed to the log. This methods returns only when the exec command has finished (i.e this method calls the command in a non-detached mode).

Specified by:

startExecContainer in interface DockerAccess

Parameters:

containerId - id of the exec container

outputSpec - how to print out the output of the command

Throws:

DockerAccessException - if the container could not be created.

createExecContainer

public String createExecContainer(String containerId,
                                  org.eclipse.jkube.kit.common.Arguments arguments)
                           throws DockerAccessException

Description copied from interface: DockerAccess

Sets up an exec instance for a running container id

Specified by:

createExecContainer in interface DockerAccess

Parameters:

containerId - id of the running container which the exec container will be created for

arguments - container exec commands to run

Returns:

container created

Throws:

DockerAccessException - if the container could not be created.

createContainer

public String createContainer(ContainerCreateConfig containerConfig,
                              String containerName)
                       throws DockerAccessException

Description copied from interface: DockerAccess

Create a container from the given image.

The container id will be set on the container upon successful creation.

Specified by:

createContainer in interface DockerAccess

Parameters:

containerConfig - container configuration

containerName - name container should be created with or null for a docker provided name

Returns:

created container

Throws:

DockerAccessException - if the container could not be created.

startContainer

public void startContainer(String containerId)
                    throws DockerAccessException

Description copied from interface: DockerAccess

Start a container.

Specified by:

startContainer in interface DockerAccess

Parameters:

containerId - id of the container to start

Throws:

DockerAccessException - if the container could not be started.

stopContainer

public void stopContainer(String containerId,
                          int killWait)
                   throws DockerAccessException

Description copied from interface: DockerAccess

Stop a container.

Specified by:

stopContainer in interface DockerAccess

Parameters:

containerId - the container id

killWait - the time to wait between stop and kill (in seconds)

Throws:

DockerAccessException - if the container could not be stopped.

buildImage

public void buildImage(String image,
                       File dockerArchive,
                       BuildOptions options)
                throws DockerAccessException

Description copied from interface: DockerAccess

Create an docker image from a given archive

Specified by:

buildImage in interface DockerAccess

Parameters:

image - name of the image to build or null if none should be used

dockerArchive - from which the docker image should be build

options - additional query arguments to add when building the image. Can be null.

Throws:

DockerAccessException - if docker host reports an error during building of an image

copyArchive

public void copyArchive(String containerId,
                        File archive,
                        String targetPath)
                 throws DockerAccessException

Description copied from interface: DockerAccess

Copy an archive (must be a tar) into a running container Get all containers matching a certain label. This might not be a cheap operation especially if many containers are running. Use with care.

Specified by:

copyArchive in interface DockerAccess

Parameters:

containerId - container to copy into

archive - local archive to copy into

targetPath - target path to use

Throws:

DockerAccessException - if the archive could not be copied

getLogSync

public void getLogSync(String containerId,
                       LogCallback callback)

Description copied from interface: DockerAccess

Get logs for a container up to now synchronously.

Specified by:

getLogSync in interface DockerAccess

Parameters:

containerId - container id

callback - which is called for each line received

getLogAsync

public LogGetHandle getLogAsync(String containerId,
                                LogCallback callback)

Description copied from interface: DockerAccess

Get logs asynchronously. This call will start a thread in the background for doing the request. It returns a handle which can be used to abort the request on demand.

Specified by:

getLogAsync in interface DockerAccess

Parameters:

containerId - id of the container for which to fetch the logs

callback - to call when log data arrives

Returns:

handle for managing the lifecycle of the thread

getContainersForImage

public List<Container> getContainersForImage(String image,
                                             boolean all)
                                      throws DockerAccessException

Description copied from interface: DockerAccess

Get all containers which are build from an image. By default only the last containers are considered but this can be tuned with a global parameters.

Specified by:

getContainersForImage in interface DockerAccess

Parameters:

image - for which its container are looked up

all - whether to fetch also stopped containers. If false only running containers are returned

Returns:

list of Container objects or an empty list if none is found

Throws:

DockerAccessException - if the request fails

getContainer

public ContainerDetails getContainer(String containerIdOrName)
                              throws DockerAccessException

Description copied from interface: DockerAccess

Get a container

Specified by:

getContainer in interface DockerAccess

Parameters:

containerIdOrName - container id or name

Returns:

ContainerDetails representing the container or null if none could be found

Throws:

DockerAccessException - if the container could not be inspected

getExecContainer

public ExecDetails getExecContainer(String containerIdOrName)
                             throws DockerAccessException

Description copied from interface: DockerAccess

Get an exec container which is the result of executing a command in a running container.

Specified by:

getExecContainer in interface DockerAccess

Parameters:

containerIdOrName - exec container id or name

Returns:

ExecDetails representing the container or null if none could be found

Throws:

DockerAccessException - if the container could not be inspected

hasImage

public boolean hasImage(String name)
                 throws DockerAccessException

Description copied from interface: DockerAccess

Check whether the given name exists as image at the docker daemon

Specified by:

hasImage in interface DockerAccess

Parameters:

name - image name to check

Returns:

true if the image exists

Throws:

DockerAccessException - docker access exception

getImageId

public String getImageId(String name)
                  throws DockerAccessException

Description copied from interface: DockerAccess

Get the image id of a given name or null if no such image exists

Specified by:

getImageId in interface DockerAccess

Parameters:

name - name to lookup

Returns:

the image id or null

Throws:

DockerAccessException - docker access exception

removeContainer

public void removeContainer(String containerId,
                            boolean removeVolumes)
                     throws DockerAccessException

Description copied from interface: DockerAccess

Remove a container with the given id

Specified by:

removeContainer in interface DockerAccess

Parameters:

containerId - container id for the container to remove

removeVolumes - if true, will remove any volumes associated to container

Throws:

DockerAccessException - if the container couldn't be removed.

loadImage

public void loadImage(String image,
                      File tarArchive)
               throws DockerAccessException

Description copied from interface: DockerAccess

Load an image from an archive.

Specified by:

loadImage in interface DockerAccess

Parameters:

image - the image to pull.

tarArchive - archive file

Throws:

DockerAccessException - if the image couldn't be loaded.

pullImage

public void pullImage(String image,
                      AuthConfig authConfig,
                      String registry,
                      CreateImageOptions options)
               throws DockerAccessException

Description copied from interface: DockerAccess

Pull an image from a remote registry and store it locally.

Specified by:

pullImage in interface DockerAccess

Parameters:

image - the image to pull.

authConfig - authentication configuration used when pulling an image

registry - an optional registry from where to pull the image. Can be null.

options - additional query arguments to add when creating the image. Can be null.

Throws:

DockerAccessException - if the image couldn't be pulled.

pushImage

public void pushImage(String image,
                      AuthConfig authConfig,
                      String registry,
                      int retries)
               throws DockerAccessException

Description copied from interface: DockerAccess

Push an image to a registry. An registry can be specified which is used as target if the image name the image does not contain a registry. If an optional registry is used, the image is also tagged with the full name containing the registry as part (if not already existent)

Specified by:

pushImage in interface DockerAccess

Parameters:

image - image name to push

authConfig - authentication configuration

registry - optional registry to which the image should be pushed.

retries - optional number of times the push should be retried on a 500 error

Throws:

DockerAccessException - in case pushing fails

saveImage

public void saveImage(String image,
                      String filename,
                      org.eclipse.jkube.kit.common.archive.ArchiveCompression compression)
               throws DockerAccessException

Description copied from interface: DockerAccess

Save an image to a tar file

Specified by:

saveImage in interface DockerAccess

Parameters:

image - image to save

filename - target filename

compression - compression to use for the archive

Throws:

DockerAccessException - if an image cannot be removed

tag

public void tag(String sourceImage,
                String targetImage,
                boolean force)
         throws DockerAccessException

Description copied from interface: DockerAccess

Alias an image in the repository with a complete new name. (Note that this maps to a Docker Remote API 'tag' operation, which IMO is badly named since it also can generate a complete alias to a given image)

Specified by:

tag in interface DockerAccess

Parameters:

sourceImage - full name (including tag) of the image to alias

targetImage - the alias name

force - forced tagging

Throws:

DockerAccessException - if the original image doesn't exist or another error occurs somehow.

removeImage

public boolean removeImage(String image,
                           boolean... forceOpt)
                    throws DockerAccessException

Description copied from interface: DockerAccess

Remove an image from this docker installation

Specified by:

removeImage in interface DockerAccess

Parameters:

image - image to remove

forceOpt - if set to true remove containers as well (only the first vararg is evaluated)

Returns:

true if an image was removed, false if none was removed

Throws:

DockerAccessException - if an image cannot be removed

listNetworks

public List<Network> listNetworks()
                           throws DockerAccessException

Description copied from interface: DockerAccess

List all networks

Specified by:

listNetworks in interface DockerAccess

Returns:

list of Network objects

Throws:

DockerAccessException - if the networks could not be listed

createNetwork

public String createNetwork(NetworkCreateConfig networkConfig)
                     throws DockerAccessException

Description copied from interface: DockerAccess

Create a custom network from the given configuration.

Specified by:

createNetwork in interface DockerAccess

Parameters:

networkConfig - network configuration

Returns:

created network

Throws:

DockerAccessException - if the container could not be created.

removeNetwork

public boolean removeNetwork(String networkId)
                      throws DockerAccessException

Description copied from interface: DockerAccess

Remove a custom network

Specified by:

removeNetwork in interface DockerAccess

Parameters:

networkId - network to remove

Returns:

true if an network was removed, false if none was removed

Throws:

DockerAccessException - if an image cannot be removed

createVolume

public String createVolume(VolumeCreateConfig containerConfig)
                    throws DockerAccessException

Description copied from interface: DockerAccess

Create a volume

Specified by:

createVolume in interface DockerAccess

Parameters:

containerConfig - volume configuration

Returns:

the name of the Volume

Throws:

DockerAccessException - if the volume could not be created.

removeVolume

public void removeVolume(String name)
                  throws DockerAccessException

Description copied from interface: DockerAccess

Removes a volume. It is a no-op if the volume does not exist.

Specified by:

removeVolume in interface DockerAccess

Parameters:

name - volume name to remove

Throws:

DockerAccessException - if the volume could not be removed

start

public void start()

Description copied from interface: DockerAccess

Lifecycle method for this access class which must be called before any other method is called.

Specified by:

start in interface DockerAccess

shutdown

public void shutdown()

Description copied from interface: DockerAccess

Lifecycle method which must be called when this object is not needed anymore. This hook might be used for cleaning up things.

Specified by:

shutdown in interface DockerAccess

fetchApiVersionFromServer

public String fetchApiVersionFromServer(String baseUrl,
                                        ApacheHttpClientDelegate delegate)
                                 throws IOException

Throws:

IOException