Warning comment on 'followStream'

Marcus Linke · Marcus Linke · commit 1ed6fbfe5ae6 · 2015-05-15T15:30:20.000+02:00
diff --git a/src/main/java/com/github/dockerjava/api/command/AttachContainerCmd.java b/src/main/java/com/github/dockerjava/api/command/AttachContainerCmd.java
@@ -2,6 +2,7 @@
 
 import java.io.InputStream;
 
+import com.github.dockerjava.api.DockerClient;
 import com.github.dockerjava.api.NotFoundException;
 
 /**
@@ -20,7 +21,7 @@
  *            - true or false, if true, print timestamps for every log line.
  *            Defaults to false.
  */
-public interface AttachContainerCmd extends DockerCmd<InputStream>{
+public interface AttachContainerCmd extends DockerCmd<InputStream> {
 
 	public String getContainerId();
 
@@ -36,8 +37,17 @@ public interface AttachContainerCmd extends DockerCmd<InputStream>{
 
 	public AttachContainerCmd withContainerId(String containerId);
 
+	/**
+	 * See {@link #withFollowStream(boolean)}
+	 */
 	public AttachContainerCmd withFollowStream();
 
+	/**
+	 * Following the stream means the resulting {@link InputStream} returned by
+	 * {@link #exec()} reads infinitely. So a {@link InputStream#read()} MAY
+	 * BLOCK FOREVER as long as no data is streamed from the docker host to
+	 * {@link DockerClient}!
+	 */
 	public AttachContainerCmd withFollowStream(boolean followStream);
 
 	public AttachContainerCmd withTimestamps(boolean timestamps);
@@ -51,19 +61,21 @@ public interface AttachContainerCmd extends DockerCmd<InputStream>{
 	public AttachContainerCmd withStdErr(boolean stderr);
 
 	public AttachContainerCmd withLogs(boolean logs);
-	
+
 	public AttachContainerCmd withLogs();
 
 	/**
-	 * Its the responsibility of the caller to consume and/or close the {@link InputStream} to prevent
-	 * connection leaks.
+	 * Its the responsibility of the caller to consume and/or close the
+	 * {@link InputStream} to prevent connection leaks.
 	 * 
-	 * @throws NotFoundException No such container 
+	 * @throws NotFoundException
+	 *             No such container
 	 */
 	@Override
 	public InputStream exec() throws NotFoundException;
-	
-	public static interface Exec extends DockerCmdExec<AttachContainerCmd, InputStream> {
+
+	public static interface Exec extends
+			DockerCmdExec<AttachContainerCmd, InputStream> {
 	}
 
 }
diff --git a/src/main/java/com/github/dockerjava/api/command/LogContainerCmd.java b/src/main/java/com/github/dockerjava/api/command/LogContainerCmd.java
@@ -1,12 +1,13 @@
 package com.github.dockerjava.api.command;
 
+import com.github.dockerjava.api.DockerClient;
 import com.github.dockerjava.api.NotFoundException;
 
 import java.io.InputStream;
 
 /**
  * Get container logs
- *
+ * 
  * @param followStream
  *            - true or false, return stream. Defaults to false.
  * @param stdout
@@ -17,13 +18,15 @@
  *            - true or false, if true, print timestamps for every log line.
  *            Defaults to false.
  * @param tail
- * 			  - `all` or `<number>`, Output specified number of lines at the end of logs
- *
- * Consider wrapping any input stream you get with a frame reader to make reading frame easier.
- *
+ *            - `all` or `<number>`, Output specified number of lines at the end
+ *            of logs
+ * 
+ *            Consider wrapping any input stream you get with a frame reader to
+ *            make reading frame easier.
+ * 
  * @see com.github.dockerjava.core.command.FrameReader
  */
-public interface LogContainerCmd extends DockerCmd<InputStream>{
+public interface LogContainerCmd extends DockerCmd<InputStream> {
 
 	public String getContainerId();
 
@@ -39,12 +42,21 @@ public interface LogContainerCmd extends DockerCmd<InputStream>{
 
 	public LogContainerCmd withContainerId(String containerId);
 
+	/**
+	 * See {@link #withFollowStream(boolean)}
+	 */
 	public LogContainerCmd withFollowStream();
 
+	/**
+	 * Following the stream means the resulting {@link InputStream} returned by
+	 * {@link #exec()} reads infinitely. So a {@link InputStream#read()} MAY
+	 * BLOCK FOREVER as long as no data is streamed from the docker host to
+	 * {@link DockerClient}!
+	 */
 	public LogContainerCmd withFollowStream(boolean followStream);
 
 	public LogContainerCmd withTimestamps();
-	
+
 	public LogContainerCmd withTimestamps(boolean timestamps);
 
 	public LogContainerCmd withStdOut();
@@ -60,16 +72,17 @@ public interface LogContainerCmd extends DockerCmd<InputStream>{
 	public LogContainerCmd withTail(int tail);
 
 	/**
-	 * Its the responsibility of the caller to consume and/or close the {@link InputStream} to prevent
-	 * connection leaks.
-	 *  
-	 * @throws NotFoundException No such container
+	 * Its the responsibility of the caller to consume and/or close the
+	 * {@link InputStream} to prevent connection leaks.
+	 * 
+	 * @throws NotFoundException
+	 *             No such container
 	 */
 	@Override
 	public InputStream exec() throws NotFoundException;
-	
-	public static interface Exec extends DockerCmdExec<LogContainerCmd, InputStream> {
-	}
 
+	public static interface Exec extends
+			DockerCmdExec<LogContainerCmd, InputStream> {
+	}
 
 }
