Home

docker-java-api wiki

What it is:

It is a Java library for the Docker Engine API. It is the equivalent of the docker command-line client, for Java applications.

Unlike other docker clients for Java, this one aims to be as lightweight as possible, with as few transitive dependencies as possible and it should cause absolutely no runtime conflicts with other frameworks or platforms like Java EE.

One other target is that this library should be a true API, not an SDK. Read this blog post for more details.

Principles:

• encapsulation (everything is hidden behind interfaces)

• no getters/setters

• immutability

• fluency

• no null references

• fail-fast:

  • If it receives any HTTP response that does not have the expected status code, it throws UnexpectedResponseException (runtime exception)
  • Other exceptional case represents IOException and this should indicate that there is a real networking problem, not a business problem with the API

• polymorphism:

  • All the API resources (Container, Image etc) represent their entities' operations (as seen bellow) and are also implementing JsonObject. They hold the Json representation returned by the API at the moment of the object's creation (see examples and comments bellow).

Usage:

You are supposed to use this client to comunicate with either a local Docker daemon, or a remote one:

//LocalDocker and RemoteDocker are the only entry points of the API.

final Docker docker = new LocalDocker(
    new File("/var/run/docker.sock")
);
//or
final Docker docker = new RemoteDocker(/*tbd in future versions*/);

boolean available = docker.ping();

A default version of the API is used (latest at the moment of the release), but you can also specify the desired API version in the above ctors.

Once instantiated, the Docker instance is quite intuitive:

Containers

    final Containers containers = docker.containers();//Containers API.
    
    for(final Container ctn : containers) {//iterate over the running containers, with the default filters.
        System.out.printlng(ctn);//Container implements JsonObject and contains the Json returned by List-Containers operation
    }

    for(final Container ctn : containers.all()) {//iterate over all the containers (not only the running ones), with the default filters.
        System.out.printlng(ctn);//Container implements JsonObject and contains the Json returned by List-Containers operation
    }

    final Container created = containers.create("hello-world");//overloaded, so you can also pass the name and/or JsonObject config 
    System.out.println(created);//created JsonObject contains just the ``Id`` and ``Warnings`` JsonObject config for the created container.

    final JsonObject details = created.inspect();
    created.start();
    created.stop();
    created.restart();
    created.rename("newname");
    created.kill();
    created.remove(...);
    created.containerId();

Images

    final Images images = docker.images();//Images API.
    for(final Image img : images) {
        //iterate over all images, with the default filters.
    }
    images.prune();//delete unused images
    final Image created = images.create(...);
    final JsonObject details = created.inspect();
    created.tag("repo", "name");
    created.history();//get the history of this image.
    created.delete();//delete the image 

Swarm

    final Swarm swarm = docker.swarm();//Swarm API.

... more to follow