KAFKA-4919: Document that stores must not be closed when Processors are closed

Author: Damian Guy <damian.guy@gmail.com>

Reviewers: Michael G. Noll, Eno Thereska, Matthias J. Sax, Elias Levy, Guozhang Wang

Closes #2725 from dguy/minor-processor-java-doc

docs/streams.html

@@ -355,8 +355,9 @@ public class MyProcessor implements Processor<String, String> {
 
     @Override
     public void close() {
-        // close the key-value store
-        this.kvStore.close();
+        // close any resources managed by this processor.
+        // Note: Do not close any StateStores as these are managed
+        // by the library
     }
 };
 </pre>

streams/examples/src/main/java/org/apache/kafka/streams/examples/wordcount/WordCountProcessorDemo.java

@@ -94,9 +94,7 @@ public class WordCountProcessorDemo {
                 }
 
                 @Override
-                public void close() {
-                    this.kvStore.close();
-                }
+                public void close() {}
             };
         }
     }

streams/src/main/java/org/apache/kafka/streams/processor/Processor.java

@@ -54,6 +54,8 @@ public interface Processor<K, V> {
     /**
      * Close this processor and clean up any resources. Be aware that {@link #close()} is called after an internal cleanup.
      * Thus, it is not possible to write anything to Kafka as underlying clients are already closed.
+     * <p>
+     * Note: Do not close any streams managed resources, like {@link StateStore}s here, as they are managed by the library.
      */
     void close();
 }

streams/src/main/java/org/apache/kafka/streams/processor/StateStore.java

@@ -48,6 +48,9 @@ public interface StateStore {
      * Close the storage engine.
      * Note that this function needs to be idempotent since it may be called
      * several times on the same state store.
+     * <p>
+     * Users only need to implement this function but should NEVER need to call this api explicitly
+     * as it will be called by the library automatically when necessary
      */
     void close();