Home

docker-java-api wiki

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

• polimorphism:

  • 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 all containers, 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.delete();//delete the image 
    created.history();//get the history of this image.

Swarm

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

... more to follow