jena-core: add more javadocs about Graph-mem thread-safety and Concur…

…rentModificationException (see apache#1992, apache#1961)

jena-arq/src/main/java/org/apache/jena/sparql/graph/GraphFactory.java

@@ -33,7 +33,9 @@ public class GraphFactory {
     }
 
     /**
-     * Create a graph that is a Jena memory graph
+     * Create a graph that is a Jena memory graph.
+     * The created graph is <strong>not thread safe</strong>.
+     * Inappropriate use of graph iterators and streams may cause {@code ConcurrentModificationException}.
      *
      * @see #createDefaultGraph
      */
@@ -42,7 +44,7 @@ public static Graph createGraphMem() {
     }
 
     /**
-     * Create an in-memory, transactional graph.
+     * Create an in-memory, thread-safe, transactional graph.
      * <p>
      * This fully supports transactions, including abort to roll-back changes. It
      * provides "autocommit" if operations are performed outside a transaction. The

jena-arq/src/main/java/org/apache/jena/sparql/graph/GraphTxn.java

@@ -33,7 +33,7 @@
 import org.apache.jena.util.iterator.WrappedIterator;
 
 /**
- * In-memory, transactional graph.
+ * In-memory, thread-safe, transactional graph.
  *
  * @implNote
  * The implementation uses the default graph of {@link DatasetGraphInMemory}.

jena-core/src/main/java/org/apache/jena/graph/Graph.java

@@ -34,6 +34,17 @@
     of RDF triples. The core interface is small (add, delete, find, contains) and
     is augmented by additional classes to handle more complicated matters
     such as event management.
+    The good practice is to explicitly close every {@link ExtendedIterator} and {@link Stream} produced by the {@code Graph}
+    right after query operation.
+    Depending on the implementation,
+    the iterator and stream may throw a {@link java.util.ConcurrentModificationException}
+    if continued with it after modification operation.
+    This may happen even if the queried data does not relate directly to the modified data
+    (i.e. when triple search pattern does not match added or deleted triple).
+    A {@link ExtendedIterator} and {@link Stream} should be operated on
+    (invoking materializing {@code ExtendedIterator} or terminal {@code Stream} operation) only once;
+    in general reusable are not allowed and may lead to an exception.
+
     @see GraphBase for an implementation framework.
 */
 public interface Graph

jena-core/src/main/java/org/apache/jena/graph/GraphMemFactory.java

@@ -30,8 +30,20 @@
 /**
  * A factory class for creating memory Graphs.
  * <p>
- * Apache Jena is migrating to term semantics graph for consistency across all in-memory and persistent storage graphs
- *
+ * Apache Jena is migrating to term semantics graph for consistency across all in-memory and persistent storage graphs.
+ * <p>
+ * All the graphs that this factory creates are <strong>not thread-safe</strong>.
+ * Note that if the memory Graph is structurally modified at any time after
+ * the iterator has been created by any of the {@code find*} or {@code stream*} methods, the iterator may throw
+ * a {@link java.util.ConcurrentModificationException ConcurrentModificationException}
+ * if continued with it after this modification.
+ * This may happen even if the queried data does not relate directly to the modified data
+ * (i.e. when triple search pattern does not match added or deleted triple).
+ * <p>
+ * The good practice is to explicitly close any {@link ExtendedIterator} immediately after a read operation.
+ * For GraphMem implementations {@code ExtendedIterator}'s materializing methods (such as {@link ExtendedIterator#toList()})
+ * could be used safely without explicit close. The same is true for {@link java.util.stream.Stream Java Stream}'s
+ * terminal operations.
  */
 public class GraphMemFactory
 {

jena-core/src/main/java/org/apache/jena/mem/GraphMem.java

@@ -26,6 +26,8 @@
 import java.util.stream.Stream;
 
 /**
+ * In-memory, non-thread-safe, non-transactional graph.
+ *
  * @deprecated This implementation of GraphMem will be replaced by a new
  *     implementation. Applications should be using
  *     {@link GraphMemFactory#createDefaultGraph()} for a general purpose graph or

jena-core/src/main/java/org/apache/jena/rdf/model/Model.java

@@ -36,7 +36,7 @@
 <p>
     Models may create Resources [URI nodes and bnodes]. Creating a Resource does
     <i>not</i> make the Resource visible to the model; Resources are only "in" Models
-    if Statements about them are added to the Model. Similarly the only way to "remove"
+    if Statements about them are added to the Model. Similarly, the only way to "remove"
     a Resource from a Model is to remove all the Statements that mention it.
 <p>
     When a Resource or Literal is created by a Model, the Model is free to re-use an
@@ -47,6 +47,17 @@
     convenience methods which extends this interface, e.g. performing
     automatic type conversions and support for enhanced resources,
     is defined in {@link ModelCon}.</p>
+ <p>
+	The good practice is to close explicitly every {@link org.apache.jena.util.iterator.ExtendedIterator Jena's ExtendedIterator}
+	produced by the {@code Model} right after query operation.
+	Depending on the implementation,
+	the iterator may throw a {@link java.util.ConcurrentModificationException}
+ 	if continued with it after modification operation.
+	This may happen even if the queried data does not relate directly to the modified data
+	(i.e. when triple search pattern does not match added or deleted triple).
+	A {@code  ExtendedIterator} should be operated on
+	(invoking materializing {@code ExtendedIterator} operation) only once;
+	in general reusable are not allowed and may lead to an exception.
 
  <h2>System Properties</h2>