From 341558275b3952baaa5fc777032f9ddb86df159b Mon Sep 17 00:00:00 2001
From: Harald Albers <github@albersweb.de>
Date: Fri, 12 Dec 2014 13:17:57 +0100
Subject: [PATCH] Test for serialization of an unconfigured StartContainerCmd,
 documentation

---
 .../com/github/dockerjava/api/DockerClient.java    | 14 ++++++++++++++
 .../core/command/StartContainerCmdImplTest.java    | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/src/main/java/com/github/dockerjava/api/DockerClient.java b/src/main/java/com/github/dockerjava/api/DockerClient.java
index 52323942f..4052e87b9 100644
--- a/src/main/java/com/github/dockerjava/api/DockerClient.java
+++ b/src/main/java/com/github/dockerjava/api/DockerClient.java
@@ -79,6 +79,20 @@ public CreateImageCmd createImageCmd(String repository,
 
 	public CreateContainerCmd createContainerCmd(String image);
 
+	/**
+	 * Creates a new {@link StartContainerCmd} for the container with the
+	 * given ID.
+	 * The command can then be further customized by using builder
+	 * methods on it like {@link StartContainerCmd#withDns(String...)}.
+	 * <p>
+	 * <b>If you customize the command, any existing configuration of the
+	 * target container will get reset to its default before applying the
+	 * new configuration. To preserve the existing configuration, use an 
+	 * unconfigured {@link StartContainerCmd}.</b> 
+	 * <p>
+	 * This command corresponds to the <code>/containers/{id}/start</code>
+	 * endpoint of the Docker Remote API.
+	 */
 	public StartContainerCmd startContainerCmd(String containerId);
 
 	public InspectContainerCmd inspectContainerCmd(String containerId);
diff --git a/src/test/java/com/github/dockerjava/core/command/StartContainerCmdImplTest.java b/src/test/java/com/github/dockerjava/core/command/StartContainerCmdImplTest.java
index 98704fd33..486f03b31 100644
--- a/src/test/java/com/github/dockerjava/core/command/StartContainerCmdImplTest.java
+++ b/src/test/java/com/github/dockerjava/core/command/StartContainerCmdImplTest.java
@@ -15,10 +15,12 @@
 import java.lang.reflect.Method;
 import java.util.*;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
 import com.github.dockerjava.api.DockerException;
 import com.github.dockerjava.api.NotFoundException;
 import com.github.dockerjava.api.command.CreateContainerResponse;
 import com.github.dockerjava.api.command.InspectContainerResponse;
+import com.github.dockerjava.api.command.StartContainerCmd;
 import com.github.dockerjava.api.model.*;
 
 import org.testng.ITestResult;
@@ -416,6 +418,11 @@ public void existingHostConfigIsPreservedByBlankStartCmd() throws DockerExceptio
 
 	@Test
 	public void existingHostConfigIsResetByConfiguredStartCmd() throws DockerException {
+		// As of version 1.3.2, Docker assumes that you either configure a container
+		// when creating it or when starting it, but not mixing both. 
+		// See https://github.com/docker-java/docker-java/pull/111
+		// If this test starts to fail, this behavior changed and a review of implementation
+		// and documentation might be needed.
 	
 		String dnsServer = "8.8.8.8";
 	
@@ -438,4 +445,11 @@ public void existingHostConfigIsResetByConfiguredStartCmd() throws DockerExcepti
 		// although start did not modify DNS Settings, they were reset to their default.
 		assertThat(inspectContainerResponse.getHostConfig().getDns(), is(nullValue(String[].class)));
 	}
+
+	@Test
+	public void anUnconfiguredCommandSerializesToEmptyJson() throws Exception {
+		ObjectMapper objectMapper = new ObjectMapper();
+		StartContainerCmd command = dockerClient.startContainerCmd("");
+		assertThat(objectMapper.writeValueAsString(command), is("{}"));
+	}
 }