Merge pull request #75 from albers/exposed-port · docker-java/docker-java@eb5db45
@@ -18,20 +18,38 @@
1818import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
1919import com.fasterxml.jackson.databind.annotation.JsonSerialize;
2020import com.fasterxml.jackson.databind.node.NullNode;
21-21+import com.github.dockerjava.api.model.Ports.Binding;
22+23+/**
24+ * Represents a container port that Docker exposes to external clients.
25+ * The port is defined by its {@link #getPort() port number} and a
26+ * {@link #getScheme() scheme}, e.g. <code>tcp</code>.
27+ * It can be published by Docker by {@link Ports#bind(ExposedPort, Binding) binding}
28+ * it to a host port, represented by a {@link Binding}.
29+ */
2230@JsonDeserialize(using = ExposedPort.Deserializer.class)
2331@JsonSerialize(using = ExposedPort.Serializer.class)
2432public class ExposedPort {
253326-private String scheme;
34+private final String scheme;
273528-private int port;
36+private final int port;
293738+/**
39+ * Creates an {@link ExposedPort} for the given parameters.
40+ *
41+ * @param scheme the {@link #getScheme() scheme}, <code>tcp</code> or
42+ * <code>udp</code>
43+ * @param port the {@link #getPort() port number}
44+ */
3045public ExposedPort(String scheme, int port) {
3146this.scheme = scheme;
3247this.port = port;
3348 }
344950+/**
51+ * @return the scheme (IP protocol), <code>tcp</code> or <code>udp</code>
52+ */
3553public String getScheme() {
3654return scheme;
3755 }
@@ -40,27 +58,50 @@ public int getPort() {
4058return port;
4159 }
426061+/**
62+ * Creates an {@link ExposedPort} for the TCP scheme.
63+ * This is a shortcut for <code>new ExposedPort("tcp", port)</code>
64+ */
4365public static ExposedPort tcp(int port) {
4466return new ExposedPort("tcp", port);
4567 }
466869+/**
70+ * Creates an {@link ExposedPort} for the UDP scheme.
71+ * This is a shortcut for <code>new ExposedPort("udp", port)</code>
72+ */
4773public static ExposedPort udp(int port) {
4874return new ExposedPort("udp", port);
4975 }
507651-public static ExposedPort parse(String serialized) {
77+/**
78+ * Parses a textual port specification (as used by the Docker CLI) to an
79+ * {@link ExposedPort}.
80+ *
81+ * @param serialized the specification, e.g. <code>80/tcp</code>
82+ * @return an {@link ExposedPort} matching the specification
83+ * @throws IllegalArgumentException if the specification cannot be parsed
84+ */
85+public static ExposedPort parse(String serialized) throws IllegalArgumentException {
5286try {
5387String[] parts = serialized.split("/");
5488ExposedPort out = new ExposedPort(parts[1], Integer.valueOf(parts[0]));
5589return out;
5690 } catch (Exception e) {
57-throw new RuntimeException("Error parsing ExposedPort '" + serialized + "'");
91+throw new IllegalArgumentException("Error parsing ExposedPort '" + serialized + "'");
5892 }
5993 }
609495+/**
96+ * Returns a string representation of this {@link ExposedPort} suitable
97+ * for inclusion in a JSON message.
98+ * The format is <code>port/scheme</code>, like the argument in {@link #parse(String)}.
99+ *
100+ * @return a string representation of this {@link ExposedPort}
101+ */
61102@Override
62103public String toString() {
63-return getPort() + "/" + getScheme();
104+return port + "/" + scheme;
64105 }
6510666107@Override