kafka git commit: MINOR: improve StateStore JavaDocs

[gu...@apache.org]

Repository: kafka
Updated Branches:
  refs/heads/trunk 406071c2b -> b604540fb


MINOR: improve StateStore JavaDocs

Clarify that state directory must use `storeName`

Author: Matthias J. Sax <ma...@confluent.io>

Reviewers: Bill Bejeck <bi...@confluent.io>, Guozhang Wang <wa...@gmail.com>

Closes #4228 from mjsax/minor-state-store-javadoc


Project: http://git-wip-us.apache.org/repos/asf/kafka/repo
Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/b604540f
Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/b604540f
Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/b604540f

Branch: refs/heads/trunk
Commit: b604540fbde818025afac85c3e96be76f212503e
Parents: 406071c
Author: Matthias J. Sax <ma...@confluent.io>
Authored: Fri Nov 17 11:49:09 2017 -0800
Committer: Guozhang Wang <wa...@gmail.com>
Committed: Fri Nov 17 11:49:09 2017 -0800

----------------------------------------------------------------------
 .../org/apache/kafka/streams/processor/StateStore.java | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kafka/blob/b604540f/streams/src/main/java/org/apache/kafka/streams/processor/StateStore.java
----------------------------------------------------------------------
diff --git a/streams/src/main/java/org/apache/kafka/streams/processor/StateStore.java b/streams/src/main/java/org/apache/kafka/streams/processor/StateStore.java
index cb8139c..f098cd0 100644
--- a/streams/src/main/java/org/apache/kafka/streams/processor/StateStore.java
+++ b/streams/src/main/java/org/apache/kafka/streams/processor/StateStore.java
@@ -20,13 +20,22 @@ import org.apache.kafka.streams.errors.StreamsException;
 
 /**
  * A storage engine for managing state maintained by a stream processor.
- *
+ * <p>
+ * If the store is implemented as a persistent store, it <em>must</em> use the store name as directory name and write
+ * all data into this store directory.
+ * The store directory must be created with the state directory.
+ * The state directory can be obtained via {@link ProcessorContext#stateDir() #stateDir()} using the
+ * {@link ProcessorContext} provided via {@link #init(ProcessorContext, StateStore) init(...)}.
+ * <p>
+ * Using nested store directories within the state directory isolates different state stores.
+ * If a state store would write into the state directory directly, it might conflict with others state stores and thus,
+ * data might get corrupted and/or Streams might fail with an error.
+ * Furthermore, Kafka Streams relies on using the store name as store directory name to perform internal cleanup tasks.
  * <p>
  * This interface does not specify any query capabilities, which, of course,
  * would be query engine specific. Instead it just specifies the minimum
  * functionality required to reload a storage engine from its changelog as well
  * as basic lifecycle management.
- * </p>
  */
 public interface StateStore {