What It Is

What is it?

It is a Java 8 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).

• JDK Integration

  • Wherever possible, the APIs are integrated with the JDK. For instance Containers, Images etc are all Iterable of their respective entities. This means, for example, you can iterate over all the running Containers in Docker as simply as:

      for(final Container ctn : containers)  {
          //running containers 
      } 

Implementation

The library is implemented using the following:

• Apache HttpClient (current version in use: 4.5.5)

• jns-unixsocket -- for Unix Sockets in Java. You can exclude this dependency if you are not using UnixDocker

• JSON-P (JSR 374) for JSON Processing. You need to add an implementation of JSON-P to your classpath, otherwise the library won't work. It does not come transitively because most developers are already using Java EE APIs so, chances are it is already in their classpath. If you have no idea what this means, just add the following dependency to your pom.xml:

    <dependency>
      <groupId>org.glassfish</groupId>
      <artifactId>javax.json</artifactId>
      <version>1.0.4</version>
    </dependency>