Rationalize DefaultDockerClient and Builder responsibities (fixes #161,

#91) - Force use of Builder to create a Docker Client - Explicitly pull JAXRS API dependency - Pull out inner DockerClient builder to JerseyDockerClientBuilder - Setup builder inheritance so that a custom JAXRS client can be plugged - Switch Jersey dependencies to optional - Remove testing of notimeout methods
dmandalidis · Apr 18, 2020 · 7fd438f · 7fd438f
1 parent 6346685
commit 7fd438f
Show file tree

Hide file tree

Showing 18 changed files with 895 additions and 783 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -43,7 +43,7 @@ after_failure:
 branches:
   only:
   - master
-  - /^v\d+\.\d+\.\d+$/
+  - /^v\d+\.\d+\.\d+(-.+)?$/
 cache:
   directories:
     - $HOME/.m2
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,60 @@
 `Reservations`. The reasoning behind this change is that the `Resources` type cannot
 hold the necessary data for supporting swarm generic resources.
 
+* Support for providing any JAX-RS 2.1 client implementation has been added to avoid 
+conflicts in flat classpath environments where another JAX-RS implementations (e.g. RESTeasy)
+are unavoidably present or where an externally-managed `Client` needs to be shared. This led
+all Jersey dependencies to become optional and clients projects must define them explicitly
+if they need to use the bundled `JerseyDockerClientBuilder`. More specifically, client 
+projects are affected in the following ways:
+    * They must include the necessary Jersey dependencies in their `pom.xml` as follows
+    ```xml
+        <dependency>
+            <groupId>org.glassfish.jersey.core</groupId>
+            <artifactId>jersey-client</artifactId>
+            <version>2.30.1</version>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jersey.inject</groupId>
+            <artifactId>jersey-hk2</artifactId>
+            <version>2.30.1</version>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jersey.connectors</groupId>
+            <artifactId>jersey-apache-connector</artifactId>
+            <version>2.30.1</version>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jersey.media</groupId>
+            <artifactId>jersey-media-json-jackson</artifactId>
+            <version>2.30.1</version>
+        </dependency>
+    ```
+    * Public constructors of `DefaultDockerClient` have been dropped in favour of clear 
+    responsibilities between the builder and the client itself:
+        * If you were using `DefaultDockerClient#DefaultDockerClient(URI)` use `new JerseyDockerClientBuilder().uri(uri).build()` instead
+        * If you were using `DefaultDockerClient#DefaultDockerClient(String)` use `new JerseyDockerClientBuilder().uri(uri).build()` instead
+        * If you were using `DefaultDockerClient#DefaultDockerClient(URI, DockerCertificatesStore)` use `new JerseyDockerClientBuilder().uri(uri).dockerCertificates(dockerCertificatesStore).build()` instead
+    * `DefaultDockerClient#fromEnv` has been moved to `JerseyDockerClientBuilder`
+        * If you were using `DefaultDockerClient#fromEnv` use `new JerseyDockerClientBuilder().fromEnv` instead
+
+    * `DefaultDockerClient#builder` has been removed
+        * If you were using `DefaultDockerClient#builder` use `new JerseyDockerClientBuilder()` instead
+
+    * `DockerClient#events` no longer throws a `DockerException` wrapping an `IOException`
+
+    * Builder `requestEntityProcessing` has changed to use a new enum shipped by the DockerClient and renamed to `entityProcessing`
+
+    * Selective per-request unlimited read timeout has been dropped. The reason for this is that there's no standard way to 
+    do it and we didn't want to create a new `Client` in such methods
+
+    * `InterruptedIOException` is now always wrapped to `DockerTimeoutException`
+
+* Shading support has been dropped as a side-effect of providing API consistency between
+different client builders.
+
+### Changes
+
 * Swarm support for generic resources (fixes #155)
 
 ## 3.2.1

diff --git a/README.md b/README.md
@@ -37,22 +37,43 @@ uploaded to maven central.
 
 ## Download
 
-Download the latest JAR or grab [via Maven][maven-search].
+Download the latest JAR or grab [via Maven][maven-search] and accompany it 
+with the necessary Jersey dependencies if you plan to use the provided 
+`JerseyDockerClientBuilder`
 
 ```xml
 <dependency>
   <groupId>org.mandas</groupId>
   <artifactId>docker-client</artifactId>
   <version>LATEST-VERSION</version>
 </dependency>
+<dependency>
+  <groupId>org.glassfish.jersey.core</groupId>
+  <artifactId>jersey-client</artifactId>
+  <version>2.30.1</version>
+</dependency>
+<dependency>
+  <groupId>org.glassfish.jersey.inject</groupId>
+  <artifactId>jersey-hk2</artifactId>
+  <version>2.30.1</version>
+</dependency>
+<dependency>
+  <groupId>org.glassfish.jersey.connectors</groupId>
+  <artifactId>jersey-apache-connector</artifactId>
+  <version>2.30.1</version>
+</dependency>
+<dependency>
+  <groupId>org.glassfish.jersey.media</groupId>
+  <artifactId>jersey-media-json-jackson</artifactId>
+  <version>2.30.1</version>
+</dependency>
 ```
 
-
 ## Usage Example
 
 ```java
 // Create a client based on DOCKER_HOST and DOCKER_CERT_PATH env vars
-final DockerClient docker = DefaultDockerClient.fromEnv().build();
+final DockerClient docker = new JerseyDockerClientBuilder().fromEnv().build();
 
 // Pull an image
 docker.pull("busybox");
@@ -147,35 +168,6 @@ you can also build and release locally by running the below.
 mvn clean [-DskipTests -Darguments=-DskipTests] -Dgpg.keyname=<key ID used for signing artifacts> release:prepare release:perform
 ```
 
-## A note on shading
-
-Please note that there is also a shaded variant.
-
-Standard:
-
-```xml
-<dependency>
-  <groupId>org.mandas</groupId>
-  <artifactId>docker-client</artifactId>
-  <version>1.0.0</version>
-</dependency>
-```
-
-Shaded:
-
-```xml
-<dependency>
-  <groupId>org.mandas</groupId>
-  <artifactId>docker-client</artifactId>
-  <classifier>shaded</classifier>
-  <version>1.0.0</version>
-</dependency>
-```
-
-**This is particularly important if you use Jersey 1.x in your project. To avoid conflicts with
-docker-client and Jersey 2.x, you will need to explicitly specify the shaded version above.**
-
-
   [1]: https://travis-ci.org/dmandalidis/docker-client
   [2]: docs/user_manual.md
   [3]: https://docs.docker.com/develop/sdk/

diff --git a/docs/user_manual.md b/docs/user_manual.md
@@ -63,15 +63,15 @@ This user manual is made to correspond to Docker's [API docs][1] (e.g. [API 1.18
 
 ```java
 // Create a client based on DOCKER_HOST and DOCKER_CERT_PATH env vars
-final DockerClient docker = DefaultDockerClient.fromEnv().build();
+final DockerClient docker = new JerseyDockerClientBuilder().fromEnv().build();
 
 // or use the builder
-final DockerClient docker = DefaultDockerClient.builder()
+final DockerClient docker = new JerseyDockerClientBuilder
   // Set various options
   .build();
 ```
 
-Both `DefaultDockerClient.builder()` and `DefaultDockerClient.fromEnv()` return a
+Both `new JerseyDockerClientBuilder` and `new JerseyDockerClientBuilder().fromEnv()` return a
 `DefaultDockerClient.Builder`. The builder can be used to configure and build clients with custom
 timeouts, connection pool sizes, and other parameters.
 
@@ -80,7 +80,7 @@ timeouts, connection pool sizes, and other parameters.
 Unix socket support is available on Linux since v2.5.0:
 
 ```java
-final DockerClient docker = new DefaultDockerClient("unix:///var/run/docker.sock");
+final DockerClient docker = new JerseyDockerClientBuilder().uri("unix:///var/run/docker.sock");
 ```
 
 ### HTTPS support
@@ -90,7 +90,7 @@ with client-server authentication. The semantics are similar to using [the `DOCK
 environment variable](https://docs.docker.com/articles/https/#client-modes):
 
 ```java
-final DockerClient docker = DefaultDockerClient.builder()
+final DockerClient docker = new JerseyDockerClientBuilder
     .uri(URI.create("https://boot2docker:2376"))
     .dockerCertificates(new DockerCertificates(Paths.get("/Users/rohan/.docker/boot2docker-vm/")))
     .build();
@@ -106,7 +106,7 @@ If you plan on waiting on more than 100 containers at a time (`DockerClient.wait
 otherwise need a higher number of concurrent requests, you can modify the connection pool size:
 
 ```java
-final DockerClient docker = DefaultDockerClient.fromEnv()
+final DockerClient docker = new JerseyDockerClientBuilder().fromEnv()
     .connectionPoolSize(SOME_LARGE_NUMBER)
     .build()
 ```

diff --git a/findbugs-exclude.xml b/findbugs-exclude.xml
@@ -24,4 +24,8 @@
   </Match>
   <!-- -->
 
+  <Match>
+  	<Bug pattern="UWF_FIELD_NOT_INITIALIZED_IN_CONSTRUCTOR" />
+  </Match>
+
 </FindBugsFilter>