docker-java · marcuslinke · Nov 5, 2014 · Oct 27, 2014 · Oct 31, 2014 · Oct 31, 2014
diff --git a/src/main/java/com/github/dockerjava/api/command/StartContainerCmd.java b/src/main/java/com/github/dockerjava/api/command/StartContainerCmd.java
@@ -6,6 +6,7 @@
 import com.github.dockerjava.api.model.Device;
 import com.github.dockerjava.api.model.Link;
 import com.github.dockerjava.api.model.LxcConf;
+import com.github.dockerjava.api.model.PortBinding;
 import com.github.dockerjava.api.model.Ports;
 import com.github.dockerjava.api.model.RestartPolicy;
 
@@ -53,8 +54,21 @@ public interface StartContainerCmd extends DockerCmd<Void> {
 
 	public StartContainerCmd withLxcConf(LxcConf... lxcConf);
 
+	/**
+	 * Add the port bindings that are contained in the given {@link Ports}
+	 * object.
+	 * 
+	 * @see #withPortBindings(PortBinding...)
+	 */
 	public StartContainerCmd withPortBindings(Ports portBindings);
 
+	/**
+	 * Add one or more {@link PortBinding}s.
+	 * This corresponds to the <code>--publish</code> (<code>-p</code>)
+	 * option of the <code>docker run</code> CLI command.
+	 */
+	public StartContainerCmd withPortBindings(PortBinding... portBindings);
+
 	public StartContainerCmd withPrivileged(boolean privileged);
 
 	public StartContainerCmd withPublishAllPorts(boolean publishAllPorts);

diff --git a/src/main/java/com/github/dockerjava/api/model/ExposedPort.java b/src/main/java/com/github/dockerjava/api/model/ExposedPort.java
@@ -48,6 +48,16 @@ public ExposedPort(int port, InternetProtocol protocol) {
 		this.protocol = protocol;
 	}
 
+	/**
+	 * Creates an {@link ExposedPort} for the given 
+	 * {@link #getPort() port number} and {@link InternetProtocol#DEFAULT}.
+	 * 
+	 * @param port the {@link #getPort() port number}
+	 */
+	public ExposedPort(int port) {
+		this(port, InternetProtocol.DEFAULT);
+	}
+
 	/**
 	 * Creates an {@link ExposedPort} for the given parameters.
 	 * 
@@ -61,7 +71,8 @@ public ExposedPort(String scheme, int port) {
 		this(port, InternetProtocol.valueOf(scheme));
 	}
 
-	/** @return the {@link InternetProtocol} */
+	/** @return the {@link InternetProtocol} of the {@link #getPort() port}
+	 *          that the container exposes */
 	public InternetProtocol getProtocol() {
 		return protocol;
 	}
@@ -75,7 +86,7 @@ public String getScheme() {
 		return protocol.toString();
 	}
 
-	/** @return the port number */
+	/** @return the port number that the container exposes */
 	public int getPort() {
 		return port;
 	}
@@ -107,7 +118,14 @@ public static ExposedPort udp(int port) {
 	public static ExposedPort parse(String serialized) throws IllegalArgumentException {
 		try {
 			String[] parts = serialized.split("/");
-			return new ExposedPort(Integer.valueOf(parts[0]), InternetProtocol.parse(parts[1]));
+			switch (parts.length) {
+			case 1:
+				return new ExposedPort(Integer.valueOf(parts[0]));
+			case 2:
+				return new ExposedPort(Integer.valueOf(parts[0]), InternetProtocol.parse(parts[1]));
+			default:
+				throw new IllegalArgumentException();
+			}
 		} catch (Exception e) {
 			throw new IllegalArgumentException("Error parsing ExposedPort '" + serialized + "'");
 		}

diff --git a/src/main/java/com/github/dockerjava/api/model/PortBinding.java b/src/main/java/com/github/dockerjava/api/model/PortBinding.java
@@ -0,0 +1,83 @@
+package com.github.dockerjava.api.model;
+
+import org.apache.commons.lang.StringUtils;
+import org.apache.commons.lang.builder.EqualsBuilder;
+import org.apache.commons.lang.builder.HashCodeBuilder;
+
+import com.github.dockerjava.api.command.InspectContainerResponse.HostConfig;
+import com.github.dockerjava.api.command.InspectContainerResponse.NetworkSettings;
+import com.github.dockerjava.api.model.Ports.Binding;
+
+/**
+ * In a {@link PortBinding}, a network socket on the Docker host, expressed 
+ * as a {@link Binding}, is bound to an {@link ExposedPort} of a container.
+ * A {@link PortBinding} corresponds to the <code>--publish</code>
+ * (<code>-p</code>) option of the <code>docker run</code> (and similar)
+ * CLI command for adding port bindings to a container.
+ * <p>
+ * <i>Note: This is an abstraction used for creating new port bindings.
+ * It is not to be confused with the abstraction used for querying existing
+ * port bindings from a container configuration in 
+ * {@link NetworkSettings#getPorts()} and {@link HostConfig#getPortBindings()}.
+ * In that context, a <code>Map&lt;ExposedPort, Binding[]&gt;</code> is used.</i>
+ */
+public class PortBinding {
+	private final Binding binding;
+	private final ExposedPort exposedPort;
+
+	public PortBinding(Binding binding, ExposedPort exposedPort) {
+		this.binding = binding;
+		this.exposedPort = exposedPort;
+	}
+
+	public Binding getBinding() {
+		return binding;
+	}
+
+	public ExposedPort getExposedPort() {
+		return exposedPort;
+	}
+
+	public static PortBinding parse(String serialized) throws IllegalArgumentException {
+		try {
+			String[] parts = StringUtils.splitByWholeSeparator(serialized, ":");
+			switch (parts.length) {
+			case 3:
+				// 127.0.0.1:80:8080/tcp
+				return createFromSubstrings(parts[0] + ":" + parts[1], parts[2]);
+			case 2:
+				// 80:8080 // 127.0.0.1::8080
+				return createFromSubstrings(parts[0], parts[1]);
+			case 1:
+				// 8080
+				return createFromSubstrings("", parts[0]);
+			default:
+				throw new IllegalArgumentException();
+			}
+		} catch (Exception e) {
+			throw new IllegalArgumentException("Error parsing PortBinding '" 
+					+ serialized + "'", e);
+		}
+	}
+
+	private static PortBinding createFromSubstrings(String binding, String exposedPort)
+			throws IllegalArgumentException {
+		return new PortBinding(Binding.parse(binding), ExposedPort.parse(exposedPort));
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if (obj instanceof PortBinding) {
+			PortBinding other = (PortBinding) obj;
+			return new EqualsBuilder().append(binding, other.getBinding())
+					.append(exposedPort, other.getExposedPort()).isEquals();
+		} else
+			return super.equals(obj);
+	}
+
+	@Override
+	public int hashCode() {
+		return new HashCodeBuilder().append(binding).append(exposedPort).toHashCode();
+	}
+
+}