com.spotify.docker.client

Interface DockerClient

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

DefaultDockerClient

public interface DockerClient
extends Closeable

A client for interacting with dockerd. Note: All methods throw DockerException on unexpected docker response status codes.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	DockerClient.AttachParameter Parameters for attachContainer(String, AttachParameter...)
static class	DockerClient.BuildParameter Flags which can be passed to the build method.
static class	DockerClient.ExecParameter Supported parameters for execCreate(java.lang.String, java.lang.String[], com.spotify.docker.client.DockerClient.ExecParameter...)
static class	DockerClient.ExecStartParameter Supported parameters for execStart(java.lang.String, com.spotify.docker.client.DockerClient.ExecStartParameter...)
static class	DockerClient.ListContainersParam Parameters for listContainers(ListContainersParam...)
static class	DockerClient.ListImagesFilterParam Filter parameter for listImages(ListImagesParam...).
static class	DockerClient.ListImagesParam Parameters for listImages(ListImagesParam...)
static class	DockerClient.LogsParameter Parameters for logs(String, LogsParameter...)

Method Summary

Methods

Modifier and Type	Method and Description
LogStream	attachContainer(String containerId, DockerClient.AttachParameter... params) Attach to the container id
int	auth(AuthConfig authConfig) Check auth configuration.
String	build(Path directory, DockerClient.BuildParameter... params) Build a docker image.
String	build(Path directory, ProgressHandler handler, DockerClient.BuildParameter... params) Build a docker image.
String	build(Path directory, String name, DockerClient.BuildParameter... params) Build a docker image.
String	build(Path directory, String name, ProgressHandler handler, DockerClient.BuildParameter... params) Build a docker image.
void	close() Closes any and all underlying connections to docker, and release resources.
ContainerCreation	commitContainer(String containerId, String repo, String tag, ContainerConfig config, String comment, String author) Create a new image from a container's changes.
InputStream	copyContainer(String containerId, String path) Copies some files out of a container.
ContainerCreation	createContainer(ContainerConfig config) Create a docker container.
ContainerCreation	createContainer(ContainerConfig config, String name) Create a docker container.
String	execCreate(String containerId, String[] cmd, DockerClient.ExecParameter... params) Sets up an exec instance in a running container id.
LogStream	execStart(String execId, DockerClient.ExecStartParameter... params) Starts a previously set up exec instance id.
InputStream	exportContainer(String containerId) Export a docker container as a tar archive.
Info	info() Get docker instance information.
ContainerInfo	inspectContainer(String containerId) Inspect a docker container.
ImageInfo	inspectImage(String image) Inspect a docker container image.
void	killContainer(String containerId) Kill a docker container.
List<Container>	listContainers(DockerClient.ListContainersParam... params) List docker containers.
List<Image>	listImages(DockerClient.ListImagesParam... params)
LogStream	logs(String containerId, DockerClient.LogsParameter... params) Get docker container logs.
void	pauseContainer(String containerId) Pause a docker container.
String	ping() Ping the docker daemon.
void	pull(String image) Pull a docker container image.
void	pull(String image, AuthConfig authConfig) Pull a private docker container image.
void	pull(String image, AuthConfig authConfig, ProgressHandler handler) Pull a private docker container image, using a custom ProgressMessageHandler.
void	pull(String image, ProgressHandler handler) Pull a docker container image, using a custom ProgressMessageHandler
void	push(String image) Push a docker container image.
void	push(String image, ProgressHandler handler) Push a docker container image, using a custom ProgressHandler
void	removeContainer(String containerId) Remove a docker container.
void	removeContainer(String containerId, boolean removeVolumes) Remove a docker container.
List<RemovedImage>	removeImage(String image) Remove a docker image.
List<RemovedImage>	removeImage(String image, boolean force, boolean noPrune) Remove a docker image.
void	restartContainer(String containerId) Restart a docker container.
void	restartContainer(String containerId, int secondsToWaitBeforeRestart) Restart a docker container.
void	startContainer(String containerId) Start a docker container.
void	startContainer(String containerId, HostConfig hostConfig) Start a docker container.
void	stopContainer(String containerId, int secondsToWaitBeforeKilling) Stop a docker container by sending a SIGTERM, and following up with a SIGKILL if the container doesn't exit gracefully and in a timely manner.
void	tag(String image, String name) Tag a docker image.
void	unpauseContainer(String containerId) Unpause a docker container.
Version	version() Get the docker version.
ContainerExit	waitContainer(String containerId) Wait for a docker container to exit.

Method Detail

ping

String ping()
            throws DockerException,
                   InterruptedException

Ping the docker daemon. Returns "OK" if all is well, though that it simply returns a 200 status is probably sufficient information.

Throws:

DockerException

InterruptedException

version

Version version()
                throws DockerException,
                       InterruptedException

Get the docker version.

Throws:

DockerException

InterruptedException

auth

int auth(AuthConfig authConfig)
         throws DockerException,
                InterruptedException

Check auth configuration.

Throws:

DockerException

InterruptedException

info

Info info()
          throws DockerException,
                 InterruptedException

Get docker instance information.

Throws:

DockerException

InterruptedException

listContainers

List<Container> listContainers(DockerClient.ListContainersParam... params)
                               throws DockerException,
                                      InterruptedException

List docker containers.

Parameters:

params - Container listing and filtering options.

Returns:

A list of containers.

Throws:

DockerException

InterruptedException

listImages

List<Image> listImages(DockerClient.ListImagesParam... params)
                       throws DockerException,
                              InterruptedException

Throws:

DockerException

InterruptedException

inspectContainer

ContainerInfo inspectContainer(String containerId)
                               throws DockerException,
                                      InterruptedException

Inspect a docker container.

Parameters:

containerId - The id of the container to inspect.

Returns:

Info about the container.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

commitContainer

ContainerCreation commitContainer(String containerId,
                                String repo,
                                String tag,
                                ContainerConfig config,
                                String comment,
                                String author)
                                  throws DockerException,
                                         InterruptedException

Create a new image from a container's changes.

Parameters:

containerId - The id of the container to commit.

comment - commit message.

author - image author.

tag - image tag.

repo - repository to commit to.

config - ContainerConfig to commit.

Throws:

DockerException

InterruptedException

inspectImage

ImageInfo inspectImage(String image)
                       throws DockerException,
                              InterruptedException

Inspect a docker container image.

Parameters:

image - The image to inspect.

Returns:

Info about the image.

Throws:

ImageNotFoundException - if the image was not found (404).

DockerException

InterruptedException

removeImage

List<RemovedImage> removeImage(String image)
                               throws DockerException,
                                      InterruptedException

Remove a docker image.

Parameters:

image - The image to remove.

Returns:

A list describing each image which was removed.

Throws:

ImageNotFoundException - if the image was not found (404).

DockerException

InterruptedException

removeImage

List<RemovedImage> removeImage(String image,
                             boolean force,
                             boolean noPrune)
                               throws DockerException,
                                      InterruptedException

Remove a docker image.

Parameters:

image - The image to remove.

force - Force image removal.

noPrune - Do not delete untagged parents.

Returns:

A list describing each image which was removed.

Throws:

ImageNotFoundException - if the image was not found (404).

DockerException

InterruptedException

pull

void pull(String image)
          throws DockerException,
                 InterruptedException

Pull a docker container image.

Parameters:

image - The image to pull.

Throws:

DockerException

InterruptedException

pull

void pull(String image,
        ProgressHandler handler)
          throws DockerException,
                 InterruptedException

Pull a docker container image, using a custom ProgressMessageHandler

Parameters:

image - The image to pull.

handler - The handler to use for processing each progress message received from Docker.

Throws:

DockerException

InterruptedException

pull

void pull(String image,
        AuthConfig authConfig)
          throws DockerException,
                 InterruptedException

Pull a private docker container image.

Parameters:

image - The image to pull.

authConfig - The authentication config needed to pull the image.

Throws:

DockerException

InterruptedException

pull

void pull(String image,
        AuthConfig authConfig,
        ProgressHandler handler)
          throws DockerException,
                 InterruptedException

Pull a private docker container image, using a custom ProgressMessageHandler.

Parameters:

image - The image to pull.

authConfig - The authentication config needed to pull the image.

handler - The handler to use for processing each progress message received from Docker.

Throws:

DockerException

InterruptedException

push

void push(String image)
          throws DockerException,
                 InterruptedException

Push a docker container image.

Parameters:

image - The image to push.

Throws:

DockerException

InterruptedException

push

void push(String image,
        ProgressHandler handler)
          throws DockerException,
                 InterruptedException

Push a docker container image, using a custom ProgressHandler

Parameters:

image - The image to push.

handler - The handler to use for processing each progress message received from Docker.

Throws:

DockerException

InterruptedException

tag

void tag(String image,
       String name)
         throws DockerException,
                InterruptedException

Tag a docker image.

Parameters:

image - The image to tag.

name - The new name that will be applied to the image.

Throws:

DockerException

InterruptedException

build

String build(Path directory,
           DockerClient.BuildParameter... params)
             throws DockerException,
                    InterruptedException,
                    IOException

Build a docker image.

Parameters:

directory - The directory containing the dockerfile.

params - Additional flags to use during build.

Returns:

The id of the built image if successful, otherwise null.

Throws:

DockerException

InterruptedException

IOException

build

String build(Path directory,
           String name,
           DockerClient.BuildParameter... params)
             throws DockerException,
                    InterruptedException,
                    IOException

Build a docker image.

Parameters:

directory - The directory containing the dockerfile.

name - The repository name and optional tag to apply to the built image.

params - Additional flags to use during build.

Returns:

The id of the built image if successful, otherwise null.

Throws:

DockerException

InterruptedException

IOException

build

String build(Path directory,
           ProgressHandler handler,
           DockerClient.BuildParameter... params)
             throws DockerException,
                    InterruptedException,
                    IOException

Build a docker image.

Parameters:

directory - The directory containing the dockerfile.

handler - The handler to use for processing each progress message received from Docker.

params - Additional flags to use during build.

Returns:

The id of the built image if successful, otherwise null.

Throws:

DockerException

InterruptedException

IOException

build

String build(Path directory,
           String name,
           ProgressHandler handler,
           DockerClient.BuildParameter... params)
             throws DockerException,
                    InterruptedException,
                    IOException

Build a docker image.

Parameters:

directory - The directory containing the dockerfile.

name - The repository name and optional tag to apply to the built image.

handler - The handler to use for processing each progress message received from Docker.

params - Additional flags to use during build.

Returns:

The id of the built image if successful, otherwise null.

Throws:

DockerException

InterruptedException

IOException

createContainer

ContainerCreation createContainer(ContainerConfig config)
                                  throws DockerException,
                                         InterruptedException

Create a docker container.

Parameters:

config - The container configuration.

Returns:

Container creation result with container id and eventual warnings from docker.

Throws:

ImageNotFoundException - if the image was not found (404).

DockerException

InterruptedException

createContainer

ContainerCreation createContainer(ContainerConfig config,
                                String name)
                                  throws DockerException,
                                         InterruptedException

Create a docker container.

Parameters:

config - The container configuration.

name - The container name.

Returns:

Container creation result with container id and eventual warnings from docker.

Throws:

ImageNotFoundException - if the image was not found (404).

DockerException

InterruptedException

startContainer

void startContainer(String containerId)
                    throws DockerException,
                           InterruptedException

Start a docker container.

Parameters:

containerId - The id of the container to start.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

startContainer

void startContainer(String containerId,
                  HostConfig hostConfig)
                    throws DockerException,
                           InterruptedException

Start a docker container.

Parameters:

containerId - The id of the container to start.

hostConfig - The docker host configuration to use when starting the container.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

stopContainer

void stopContainer(String containerId,
                 int secondsToWaitBeforeKilling)
                   throws DockerException,
                          InterruptedException

Stop a docker container by sending a SIGTERM, and following up with a SIGKILL if the container doesn't exit gracefully and in a timely manner.

Parameters:

containerId - The id of the container to stop.

secondsToWaitBeforeKilling - Time to wait after SIGTERM before sending SIGKILL.

Throws:

DockerException

InterruptedException

pauseContainer

void pauseContainer(String containerId)
                    throws DockerException,
                           InterruptedException

Pause a docker container.

Parameters:

containerId - The id of the container to pause.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

unpauseContainer

void unpauseContainer(String containerId)
                      throws DockerException,
                             InterruptedException

Unpause a docker container.

Parameters:

containerId - The id of the container to pause.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

restartContainer

void restartContainer(String containerId)
                      throws DockerException,
                             InterruptedException

Restart a docker container. with a 10 second default wait

Parameters:

containerId - The id of the container to restart.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

restartContainer

void restartContainer(String containerId,
                    int secondsToWaitBeforeRestart)
                      throws DockerException,
                             InterruptedException

Restart a docker container.

Parameters:

containerId - The id of the container to restart.

secondsToWaitBeforeRestart - number of seconds to wait before killing the container.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

waitContainer

ContainerExit waitContainer(String containerId)
                            throws DockerException,
                                   InterruptedException

Wait for a docker container to exit.

Parameters:

containerId - The id of the container to wait for.

Returns:

Exit response with status code.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

killContainer

void killContainer(String containerId)
                   throws DockerException,
                          InterruptedException

Kill a docker container.

Parameters:

containerId - The id of the container to kill.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

removeContainer

void removeContainer(String containerId)
                     throws DockerException,
                            InterruptedException

Remove a docker container.

Parameters:

containerId - The id of the container to remove.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

removeContainer

void removeContainer(String containerId,
                   boolean removeVolumes)
                     throws DockerException,
                            InterruptedException

Remove a docker container.

Parameters:

containerId - The id of the container to remove.

removeVolumes - Whether to remove volumes as well.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

exportContainer

InputStream exportContainer(String containerId)
                            throws DockerException,
                                   InterruptedException

Export a docker container as a tar archive.

Parameters:

containerId - The id of the container to export.

Returns:

A stream in tar format that contains the contents of the container file system.

Throws:

DockerException

InterruptedException

copyContainer

InputStream copyContainer(String containerId,
                        String path)
                          throws DockerException,
                                 InterruptedException

Copies some files out of a container.

Parameters:

containerId - The id of the container to copy files from.

path - The path inside of the container to copy. If this is a directory, it will be copied recursively. If this is a file, only that file will be copied.

Returns:

A stream in tar format that contains the copied files. If a directory was copied, the directory will be at the root of the tar archive (so copy(..., "/usr/share") will result in a directory called share in the tar archive). The directory name is completely resolved, so copying "/usr/share/././." will still create a directory called "share" in the tar archive. If a single file was copied, that file will be the sole entry in the tar archive. Copying "." or equivalently "/" will result in the tar archive containing a single folder named after the container ID.

Throws:

DockerException

InterruptedException

logs

LogStream logs(String containerId,
             DockerClient.LogsParameter... params)
               throws DockerException,
                      InterruptedException

Get docker container logs.

Parameters:

containerId - The id of the container to get logs for.

params - Params for controlling what streams to get and whether to tail or not.

Returns:

A log message stream.

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

execCreate

String execCreate(String containerId,
                String[] cmd,
                DockerClient.ExecParameter... params)
                  throws DockerException,
                         InterruptedException

Sets up an exec instance in a running container id.

Parameters:

containerId - The id of the container

cmd - shell command

Returns:

exec id

Throws:

ContainerNotFoundException - if the container was not found (404).

DockerException

InterruptedException

execStart

LogStream execStart(String execId,
                  DockerClient.ExecStartParameter... params)
                    throws DockerException,
                           InterruptedException

Starts a previously set up exec instance id. If detach is true, this API returns after starting the exec command. Otherwise, this API sets up an interactive session with the exec command.

Parameters:

execId - exec id

Returns:

exec output

Throws:

ExecNotFoundException - if the exec was not found (404).

DockerException

InterruptedException

close

void close()

Closes any and all underlying connections to docker, and release resources.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

attachContainer

LogStream attachContainer(String containerId,
                        DockerClient.AttachParameter... params)
                          throws DockerException,
                                 InterruptedException

Attach to the container id

Parameters:

containerId - The id of the container to get logs for.

params - Params for controlling what streams to get and whether to tail or not.

Returns:

A log message stream.

Throws:

ContainerNotFoundException - if the container was not found (404).

InterruptedException

DockerException