docker-java · eddumelendez · Aug 19, 2025 · Aug 4, 2025 · Aug 19, 2025
@@ -2,9 +2,11 @@
 
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 
 import com.github.dockerjava.api.async.ResultCallback;
 import com.github.dockerjava.api.exception.NotFoundException;
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import com.github.dockerjava.api.model.WaitResponse;
 
 /**
@@ -20,8 +22,20 @@ public interface WaitContainerCmd extends AsyncDockerCmd<WaitContainerCmd, WaitR
     WaitContainerCmd withContainerId(@Nonnull String containerId);
 
     /**
-     * @throws NotFoundException
-     *             container not found
+     * Defaults to {@link WaitContainerCondition#NOT_RUNNING} if omitted or empty.
+     *
+     * @since {@link RemoteApiVersion#VERSION_1_30}
+     */
+    @Nullable
+    WaitContainerCondition getCondition();
+
+    /**
+     * @since {@link RemoteApiVersion#VERSION_1_30}
+     */
+    WaitContainerCmd withCondition(@Nullable WaitContainerCondition condition);
+
+    /**
+     * @throws NotFoundException container not found
      */
     @Override
     <T extends ResultCallback<WaitResponse>> T exec(T resultCallback);

@@ -0,0 +1,26 @@
+package com.github.dockerjava.api.model;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Docker Engine API <em>wait</em> conditions (added in v1.30).
+ *
+ * @since {@link RemoteApiVersion#VERSION_1_30}
+ */
+public enum WaitContainerCondition {
+    NOT_RUNNING("not-running"),
+    NEXT_EXIT("next-exit"),
+    REMOVED("removed");
+
+    @Nonnull
+    private final String value;
+
+    WaitContainerCondition(@Nonnull String value) {
+        this.value = value;
+    }
+
+    @Nonnull
+    public String getValue() {
+        return value;
+    }
+}
@@ -2,7 +2,10 @@
 
 import java.util.Objects;
 
+import javax.annotation.Nullable;
+
 import com.github.dockerjava.api.command.WaitContainerCmd;
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import com.github.dockerjava.api.model.WaitResponse;
 
 /**
@@ -15,6 +18,8 @@ public class WaitContainerCmdImpl extends AbstrAsyncDockerCmd<WaitContainerCmd,
 
     private String containerId;
 
+    private WaitContainerCondition condition;
+
     public WaitContainerCmdImpl(WaitContainerCmd.Exec exec, String containerId) {
         super(exec);
         withContainerId(containerId);
@@ -31,4 +36,16 @@ public WaitContainerCmd withContainerId(String containerId) {
         return this;
     }
 
+    @Nullable
+    @Override
+    public WaitContainerCondition getCondition() {
+        return condition;
+    }
+
+    @Override
+    public WaitContainerCmd withCondition(@Nullable WaitContainerCondition condition) {
+        this.condition = condition;
+        return this;
+    }
+
 }
@@ -1,5 +1,6 @@
 package com.github.dockerjava.core.exec;
 
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -25,6 +26,11 @@ protected Void execute0(WaitContainerCmd command, ResultCallback<WaitResponse> r
         WebTarget webTarget = getBaseResource().path("/containers/{id}/wait").resolveTemplate("id",
                 command.getContainerId());
 
+        WaitContainerCondition condition = command.getCondition();
+        if (condition != null) {
+            webTarget = webTarget.queryParam("condition", condition.getValue());
+        }
+
         LOGGER.trace("POST: {}", webTarget);
 
         webTarget.request().accept(MediaType.APPLICATION_JSON).post((Object) null, new TypeReference<WaitResponse>() {

@@ -8,18 +8,25 @@
 import com.github.dockerjava.api.exception.DockerClientException;
 import com.github.dockerjava.api.exception.DockerException;
 import com.github.dockerjava.api.exception.NotFoundException;
+import com.github.dockerjava.api.model.WaitContainerCondition;
 import com.github.dockerjava.api.model.WaitResponse;
+import org.junit.Assert;
 import org.junit.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.util.concurrent.TimeUnit;
 
+import static com.github.dockerjava.api.model.HostConfig.newHostConfig;
+import static com.github.dockerjava.core.RemoteApiVersion.VERSION_1_25;
+import static com.github.dockerjava.core.RemoteApiVersion.VERSION_1_30;
+import static com.github.dockerjava.junit.DockerMatchers.isGreaterOrEqual;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.emptyString;
 import static org.hamcrest.Matchers.not;
+import static org.junit.Assume.assumeThat;
 
 public class WaitContainerCmdIT extends CmdIT {
     public static final Logger LOG = LoggerFactory.getLogger(BuildImageCmd.class);
@@ -102,4 +109,77 @@ public void testWaitContainerTimeout() {
             LOG.info(e.getMessage());
         }
     }
+
+    @Test
+    public void testWaitNotStartedContainer() {
+        assumeThat("API version should be > 1.25", dockerRule, isGreaterOrEqual(VERSION_1_25));
+
+        CreateContainerResponse container = dockerRule.getClient().createContainerCmd("busybox")
+            .withHostConfig(newHostConfig().withAutoRemove(true))
+            .exec();
+
+        LOG.info("Created container: {}", container.toString());
+        assertThat(container.getId(), not(is(emptyString())));
+
+        WaitContainerResultCallback callback = dockerRule.getClient().waitContainerCmd(container.getId()).exec(new WaitContainerResultCallback());
+
+        Integer statusCode = callback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
+        Assert.assertEquals(0, statusCode.intValue());
+    }
+
+    @Test
+    public void testWaitContainerWithAutoRemoval() {
+        assumeThat("API version should be > 1.30", dockerRule, isGreaterOrEqual(VERSION_1_30));
+
+        CreateContainerResponse container = dockerRule.getClient().createContainerCmd("busybox")
+            .withCmd("false")
+            .withHostConfig(newHostConfig().withAutoRemove(true))
+            .exec();
+
+        LOG.info("Created container: {}", container.toString());
+        assertThat(container.getId(), not(is(emptyString())));
+
+        WaitContainerResultCallback removedCondition = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.REMOVED)
+            .exec(new WaitContainerResultCallback());
+
+        WaitContainerResultCallback nextExitCondition = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.NEXT_EXIT)
+            .exec(new WaitContainerResultCallback());
+
+        dockerRule.getClient().startContainerCmd(container.getId()).exec();
+
+        Assert.assertEquals(1, removedCondition.awaitStatusCode(100, TimeUnit.MILLISECONDS).intValue());
+        Assert.assertEquals(1, nextExitCondition.awaitStatusCode(100, TimeUnit.MILLISECONDS).intValue());
+    }
+
+    @Test
+    public void testWaitRestartedContainer() {
+        assumeThat("API version should be > 1.30", dockerRule, isGreaterOrEqual(VERSION_1_30));
+
+        CreateContainerResponse container = dockerRule.getClient().createContainerCmd("busybox")
+            .withCmd("sh", "-c", "[ -f \"$HOME/.first_run_marker\" ] && exit 2 || { touch \"$HOME/.first_run_marker\"; exit 1; }")
+            .exec();
+
+        LOG.info("Created container: {}", container.toString());
+        assertThat(container.getId(), not(is(emptyString())));
+
+        WaitContainerResultCallback firstExitCallback = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.NEXT_EXIT)
+            .exec(new WaitContainerResultCallback());
+
+        dockerRule.getClient().startContainerCmd(container.getId()).exec();
+
+        Integer firstStatusCode = firstExitCallback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
+        Assert.assertEquals(1, firstStatusCode.intValue());
+
+        WaitContainerResultCallback callback = dockerRule.getClient().waitContainerCmd(container.getId())
+            .withCondition(WaitContainerCondition.NEXT_EXIT)
+            .exec(new WaitContainerResultCallback());
+
+        dockerRule.getClient().startContainerCmd(container.getId()).exec();
+
+        Integer statusCode = callback.awaitStatusCode(100, TimeUnit.MILLISECONDS);
+        Assert.assertEquals(2, statusCode.intValue());
+    }
 }