Github user srowen commented on a diff in the pull request:
https://github.com/apache/spark/pull/14731#discussion_r95058504
--- Diff: docs/streaming-programming-guide.md ---
@@ -630,35 +630,106 @@ which creates a DStream from text
data received over a TCP socket connection. Besides sockets, the
StreamingContext API provides
methods for creating DStreams from files as input sources.
-- **File Streams:** For reading data from files on any file system
compatible with the HDFS API (that is, HDFS, S3, NFS, etc.), a DStream can be
created as:
+#### File Streams
+{:.no_toc}
+
+For reading data from files on any file system compatible with the HDFS
API (that is, HDFS, S3, NFS, etc.), a DStream can be created as
+via `StreamingContext.fileStream[KeyClass, ValueClass, InputFormatClass]`.
+
+File streams do not require running a receiver, hence does not require
allocating cores.
- <div class="codetabs">
- <div data-lang="scala" markdown="1">
- streamingContext.fileStream[KeyClass, ValueClass,
InputFormatClass](dataDirectory)
- </div>
- <div data-lang="java" markdown="1">
- streamingContext.fileStream<KeyClass, ValueClass,
InputFormatClass>(dataDirectory);
- </div>
- <div data-lang="python" markdown="1">
- streamingContext.textFileStream(dataDirectory)
- </div>
- </div>
+For simple text files, the easiest method is
`StreamingContext.textFileStream(dataDirectory)`.
- Spark Streaming will monitor the directory `dataDirectory` and process
any files created in that directory (files written in nested directories not
supported). Note that
+<div class="codetabs">
+<div data-lang="scala" markdown="1">
- + The files must have the same data format.
- + The files must be created in the `dataDirectory` by atomically
*moving* or *renaming* them into
- the data directory.
- + Once moved, the files must not be changed. So if the files are
being continuously appended, the new data will not be read.
+{% highlight scala %}
+streamingContext.fileStream[KeyClass, ValueClass,
InputFormatClass](dataDirectory)
+{% endhighlight %}
+For text files
+
+{% highlight scala %}
+streamingContext.textFileStream(dataDirectory)
+{% endhighlight %}
+</div>
- For simple text files, there is an easier method
`streamingContext.textFileStream(dataDirectory)`. And file streams do not
require running a receiver, hence does not require allocating cores.
+<div data-lang="java" markdown="1">
+{% highlight java %}
+streamingContext.fileStream<KeyClass, ValueClass,
InputFormatClass>(dataDirectory);
+{% endhighlight %}
+For text files
- <span class="badge" style="background-color: grey">Python API</span>
`fileStream` is not available in the Python API, only `textFileStream` is
available.
+{% highlight java %}
+streamingContext.textFileStream(dataDirectory);
+{% endhighlight %}
+</div>
-- **Streams based on Custom Receivers:** DStreams can be created with data
streams received through custom receivers. See the [Custom Receiver
+<div data-lang="python" markdown="1">
+`fileStream` is not available in the Python API; only `textFileStream` is
available.
+{% highlight python %}
+streamingContext.textFileStream(dataDirectory)
+{% endhighlight %}
+</div>
+
+</div>
+
+##### How Directories are Monitored
+{:.no_toc}
+
+Spark Streaming will monitor the directory `dataDirectory` and process any
files created in that directory.
+
+ * A simple directory can be monitored, such as
`hdfs://namenode:8040/logs/`.
+ All files directly under such a path will be processed as they are
discovered.
+ + A [POSIX glob
pattern](http://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_02)
can be supplied, such as
+ `hdfs://namenode:8040/logs/2017/*`.
+ Here, the DStream will consist of all files in the directories
+ matching the pattern.
+ That is: it is a pattern of directories, not of files in directories.
+ + All files must be in the same data format.
+ * A file is considered part of a time period based on its modification
time,
+ not its creation time.
+ + Once processed, changes to a file within the current window will not
cause the file to be reread.
+ That is: *updates are ignored*.
+ + The more files under a directory, the longer it will take to
+ scan for changes âeven if no files have been modified.
--- End diff --
Nits now: space after hyphen if you please
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscr...@spark.apache.org
For additional commands, e-mail: reviews-h...@spark.apache.org
