[JCLOUDS-1007] Implemented Docker Exec support in MiscApi

docker/src/main/java/org/jclouds/docker/domain/Exec.java

@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jclouds.docker.domain;
+
+import org.jclouds.json.SerializedNames;
+
+import com.google.auto.value.AutoValue;
+
+/**
+ * Represents a response from Exec Create call (<code>POST /containers/(id)/exec</code>).
+ */
+@AutoValue
+public abstract class Exec {
+
+   public abstract String id();
+
+   @SerializedNames({ "Id"})
+   public static Exec create(String id) {
+      return new AutoValue_Exec(id);
+   }
+}

docker/src/main/java/org/jclouds/docker/domain/ExecCreateParams.java

@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jclouds.docker.domain;
+
+import static org.jclouds.docker.internal.NullSafeCopies.copyOf;
+
+import java.util.List;
+
+import org.jclouds.json.SerializedNames;
+
+import com.google.auto.value.AutoValue;
+
+/**
+ * Json Parameters (some of them) of Exec Create call.
+ */
+@AutoValue
+public abstract class ExecCreateParams {
+
+   public abstract boolean attachStdout();
+
+   public abstract boolean attachStderr();
+
+   public abstract List<String> cmd();
+
+   @SerializedNames({ "AttachStdout", "AttachStderr", "Cmd" })
+   private static ExecCreateParams create(boolean attachStdout, boolean attachStderr, List<String> cmd) {
+      return builder().attachStdout(attachStdout).attachStderr(attachStderr).cmd(cmd).build();
+   }
+
+   /**
+    * Creates builder for {@link ExecCreateParams}, it sets
+    * {@link #attachStderr()} and {@link #attachStdout()} to true as a default.
+    *
+    * @return new {@link ExecCreateParams.Builder} instance
+    */
+   public static Builder builder() {
+      return new AutoValue_ExecCreateParams.Builder().attachStderr(true).attachStdout(true);
+   }
+
+   @AutoValue.Builder
+   public abstract static class Builder {
+
+      public abstract Builder attachStdout(boolean b);
+
+      public abstract Builder attachStderr(boolean b);
+
+      public abstract Builder cmd(List<String> cmd);
+
+      abstract List<String> cmd();
+
+      abstract ExecCreateParams autoBuild();
+
+      public ExecCreateParams build() {
+         cmd(copyOf(cmd()));
+         return autoBuild();
+      }
+   }
+}

docker/src/main/java/org/jclouds/docker/domain/ExecInspect.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jclouds.docker.domain;
+
+import org.jclouds.json.SerializedNames;
+
+import com.google.auto.value.AutoValue;
+
+/**
+ * Represents a response (part of it) from Exec Inspect call (
+ * <code>GET /exec/(id)/json</code>).
+ */
+@AutoValue
+public abstract class ExecInspect {
+
+   public abstract String id();
+
+   public abstract boolean running();
+
+   public abstract int exitCode();
+
+   @SerializedNames({ "ID", "Running", "ExitCode"})
+   public static ExecInspect create(String id, boolean running, int exitCode) {
+      return new AutoValue_ExecInspect(id, running, exitCode);
+   }
+}

docker/src/main/java/org/jclouds/docker/domain/ExecStartParams.java

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jclouds.docker.domain;
+
+import org.jclouds.json.SerializedNames;
+
+import com.google.auto.value.AutoValue;
+
+/**
+ * Json Parameter(s) (some of them) of Exec Start call.
+ */
+@AutoValue
+public abstract class ExecStartParams {
+
+   public abstract boolean detach();
+
+   @SerializedNames({ "Detach" })
+   public static ExecStartParams create(boolean detach) {
+      return builder().detach(detach).build();
+   }
+
+   public static Builder builder() {
+      return new AutoValue_ExecStartParams.Builder().detach(false);
+   }
+
+   @AutoValue.Builder
+   public abstract static class Builder {
+
+      public abstract Builder detach(boolean b);
+
+      public abstract ExecStartParams build();
+   }
+}

docker/src/main/java/org/jclouds/docker/features/MiscApi.java

@@ -23,13 +23,21 @@
 import javax.ws.rs.GET;
 import javax.ws.rs.POST;
 import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
 import javax.ws.rs.core.MediaType;
 
+import org.jclouds.docker.domain.Exec;
+import org.jclouds.docker.domain.ExecCreateParams;
+import org.jclouds.docker.domain.ExecInspect;
+import org.jclouds.docker.domain.ExecStartParams;
 import org.jclouds.docker.domain.Info;
 import org.jclouds.docker.domain.Version;
 import org.jclouds.docker.options.BuildOptions;
+import org.jclouds.docker.util.DockerInputStream;
 import org.jclouds.io.Payload;
+import org.jclouds.rest.annotations.BinderParam;
 import org.jclouds.rest.annotations.Headers;
+import org.jclouds.rest.binders.BindToJsonPayload;
 
 @Consumes(MediaType.APPLICATION_JSON)
 @Path("/v{jclouds.api-version}")
@@ -82,4 +90,51 @@ public interface MiscApi {
    @Headers(keys = { "Content-Type", "Connection" }, values = { "application/tar", "close" })
    InputStream build(Payload inputStream, BuildOptions options);
 
+   /**
+    * Sets up an exec instance in a running container with given Id.
+    *
+    * @param containerId
+    *           container Id
+    * @param execCreateParams
+    *           exec parameters
+    * @return an instance which holds exec identifier
+    */
+   @Named("container:exec")
+   @POST
+   @Path("/containers/{id}/exec")
+   Exec execCreate(@PathParam("id") String containerId,
+         @BinderParam(BindToJsonPayload.class) ExecCreateParams execCreateParams);
+
+   /**
+    * Starts a previously set up exec instance id. If
+    * {@link ExecStartParams#detach()} is true, this API returns after starting
+    * the exec command. Otherwise, this API sets up an interactive session with
+    * the exec command.
+    *
+    * @param execId
+    *           exec instance id
+    * @param execStartParams
+    *           start parameters
+    * @return raw docker stream which can be wrapped to
+    *         {@link DockerInputStream}
+    * @see #execCreate(String, ExecCreateParams)
+    * @see DockerInputStream
+    */
+   @Named("exec:start")
+   @POST
+   @Path("/exec/{id}/start")
+   InputStream execStart(@PathParam("id") String execId,
+         @BinderParam(BindToJsonPayload.class) ExecStartParams execStartParams);
+
+   /**
+    * Returns low-level information about the exec command id.
+    * 
+    * @param execId
+    *           exec instance id
+    * @return details about exec instance
+    */
+   @Named("exec:inspect")
+   @GET
+   @Path("/exec/{id}/json")
+   ExecInspect execInspect(@PathParam("id") String execId);
 }

docker/src/main/java/org/jclouds/docker/util/DockerInputStream.java

@@ -0,0 +1,73 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.jclouds.docker.util;
+
+import java.io.DataInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+
+/**
+ * Extension to {@link DataInputStream} which adds method
+ * {@link #readStdStreamData()} to allow read multiplexed standard streams.
+ */
+public final class DockerInputStream extends DataInputStream {
+
+   /**
+    * Ctor from superclass.
+    *
+    * @param in
+    * @see DataInputStream#DataInputStream(InputStream)
+    */
+   public DockerInputStream(InputStream in) {
+      super(in);
+   }
+
+   /**
+    * @return {@link StdStreamData} instance read from the input stream or
+    *         <code>null</code> if we reached end of the stream.
+    * @throws IOException
+    */
+   public StdStreamData readStdStreamData() throws IOException {
+      byte[] header = new byte[8];
+      // try to read first byte from the message header - just to check if we
+      // are at the end
+      // of stream
+      if (-1 == read(header, 0, 1)) {
+         return null;
+      }
+      // read the rest of the header
+      readFully(header, 1, 7);
+      // decode size as an unsigned int
+      long size = (long) (header[4] & 0xFF) << 24 | (header[5] & 0xFF) << 16 | (header[6] & 0xFF) << 8
+            | (header[7] & 0xFF);
+
+      byte[] payload;
+      // The size from the header is an unsigned int so it can happen the byte
+      // array has not a sufficient size and we'll have to truncate the frame
+      payload = new byte[(int) Math.min(Integer.MAX_VALUE, size)];
+      readFully(payload);
+      boolean truncated = false;
+      if (size > Integer.MAX_VALUE) {
+         truncated = true;
+         // skip the rest
+         readFully(new byte[(int) (size - Integer.MAX_VALUE)]);
+      }
+      return new StdStreamData(header[0], payload, truncated);
+   }
+
+}