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.LogsParam Parameters for logs(String, LogsParam...)

Method Summary

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.
String	build(Path directory, String name, String dockerfile, 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.
ExecState	execInspect(String execId) Inspects a running or previously run exec instance 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.
String	getHost() Get the Docker host address
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) List docker images.
LogStream	logs(String containerId, DockerClient.LogsParam... 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.
List<ImageSearchResult>	searchImages(String term) Search for images on Docker Hub
void	startContainer(String containerId) Start a docker container.
ContainerStats	stats(String containerId) Retrieves one-time stats (stream=0) for the container with the specified id.
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	tag(String image, String name, boolean force) 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.

Returns:

String "OK"

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

version

Version version()
         throws DockerException,
                InterruptedException

Get the docker version.

Returns:

docker version

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

auth

int auth(AuthConfig authConfig)
  throws DockerException,
         InterruptedException

Check auth configuration.

Parameters:

authConfig - The authentication config needed to pull the image.

Returns:

status code of auth request

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

info

Info info()
   throws DockerException,
          InterruptedException

Get docker instance information.

Returns:

docker info

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

listImages

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

List docker images.

Parameters:

params - Image listing and filtering options.

Returns:

A list of images.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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.

Returns:

ContainerCreation reply.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

searchImages

List<ImageSearchResult> searchImages(String term)
                              throws DockerException,
                                     InterruptedException

Search for images on Docker Hub

Parameters:

term - the search term

Returns:

a list of matches for the given search term

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

pull

void pull(String image)
   throws DockerException,
          InterruptedException

Pull a docker container image.

Parameters:

image - The image to pull.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

push

void push(String image)
   throws DockerException,
          InterruptedException

Push a docker container image.

Parameters:

image - The image to push.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

tag

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

Tag a docker image.

Parameters:

image - The image to tag.

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

force - Whether to force the tagging even if the tag is already assigned to another image.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

IOException - If some IO shit happened.

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

IOException - If some IO shit happened.

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

IOException - If some IO shit happened.

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

IOException - If some IO shit happened.

build

String build(Path directory,
             String name,
             String dockerfile,
             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.

dockerfile - The path within the build context to 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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

IOException - If some IO shit happened.

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

startContainer

void startContainer(String containerId)
             throws DockerException,
                    InterruptedException

Start a docker container.

Parameters:

containerId - The id of the container to start.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

pauseContainer

void pauseContainer(String containerId)
             throws DockerException,
                    InterruptedException

Pause a docker container.

Parameters:

containerId - The id of the container to pause.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

unpauseContainer

void unpauseContainer(String containerId)
               throws DockerException,
                      InterruptedException

Unpause a docker container.

Parameters:

containerId - The id of the container to pause.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

killContainer

void killContainer(String containerId)
            throws DockerException,
                   InterruptedException

Kill a docker container.

Parameters:

containerId - The id of the container to kill.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

removeContainer

void removeContainer(String containerId)
              throws DockerException,
                     InterruptedException

Remove a docker container.

Parameters:

containerId - The id of the container to remove.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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 - if a server error occurred (500)

InterruptedException - If the thread is interrupted

logs

LogStream logs(String containerId,
               DockerClient.LogsParam... 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:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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

params - Exec params

Returns:

exec id

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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

params - Exec start params

Returns:

exec output

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

execInspect

ExecState execInspect(String execId)
               throws DockerException,
                      InterruptedException

Inspects a running or previously run exec instance id.

Parameters:

execId - exec id

Returns:

state of this exec instance.

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

stats

ContainerStats stats(String containerId)
              throws DockerException,
                     InterruptedException

Retrieves one-time stats (stream=0) for the container with the specified id.

Parameters:

containerId - The id of the container to retrieve stats for.

Returns:

The container stats

Throws:

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

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).

DockerException - if a server error occurred (500)

InterruptedException - If the thread is interrupted

getHost

String getHost()

Get the Docker host address

Returns:

the docker host name or IP