docs: Marking Transaction, Batch and DatastoreBatchWriter class with 'NotThreadSafe' annotation (#1082)

jainsahab · web-flow · commit 9e966506c1e8 · 2023-05-26T10:06:19.000+05:30
* doc: Marking Transaction, Batch and DatastoreBatchWriter class with @NotThreadSafe annotation * fix lint * adding jsr dependency explicitly * Empty commit * fixing casing and punctuation. * fix lint
diff --git a/google-cloud-datastore/pom.xml b/google-cloud-datastore/pom.xml
@@ -106,6 +106,10 @@
       <groupId>io.opencensus</groupId>
       <artifactId>opencensus-api</artifactId>
     </dependency>
+    <dependency>
+      <groupId>com.google.code.findbugs</groupId>
+      <artifactId>jsr305</artifactId>
+    </dependency>
 
     <!-- Test dependencies -->
     <dependency>
diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Batch.java
@@ -17,6 +17,7 @@
 package com.google.cloud.datastore;
 
 import java.util.List;
+import javax.annotation.concurrent.NotThreadSafe;
 
 /**
  * An interface to represent a batch of write operations. Any write operation that is applied on a
@@ -32,7 +33,15 @@
  * batch.add(entity2, entity3);
  * batch.submit();
  * }</pre>
+ *
+ * <p><b> WARNING: This class maintains an internal state in terms of {@link
+ * java.util.LinkedHashMap} and {@link java.util.LinkedHashSet} which gets updated on every method
+ * call performing CRUD operations to record the mutations. Since {@link java.util.LinkedHashMap} is
+ * not thread safe as per its <a
+ * href="https://docs.oracle.com/javase/8/docs/api/java/util/LinkedHashMap.html">documentation</a>,
+ * This class too should not be treated as a thread safe class. </b>
  */
+@NotThreadSafe
 public interface Batch extends DatastoreBatchWriter {
 
   interface Response {
diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreBatchWriter.java
@@ -17,11 +17,20 @@
 package com.google.cloud.datastore;
 
 import java.util.List;
+import javax.annotation.concurrent.NotThreadSafe;
 
 /**
  * An interface to represent a batch of write operations. All write operation for a batch writer
  * will be applied to the Datastore in one RPC call.
+ *
+ * <p><b> WARNING: This class maintains an internal state in terms of {@link
+ * java.util.LinkedHashMap} and {@link java.util.LinkedHashSet} which gets updated on every method
+ * call performing CRUD operations to record the mutations. Since {@link java.util.LinkedHashMap} is
+ * not thread safe as per its <a
+ * href="https://docs.oracle.com/javase/8/docs/api/java/util/LinkedHashMap.html">documentation</a>,
+ * This class too should not be treated as a thread safe class. </b>
  */
+@NotThreadSafe
 public interface DatastoreBatchWriter extends DatastoreWriter {
 
   /**
diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java b/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Transaction.java
@@ -19,14 +19,15 @@
 import com.google.protobuf.ByteString;
 import java.util.Iterator;
 import java.util.List;
+import javax.annotation.concurrent.NotThreadSafe;
 
 /**
  * A Google cloud datastore transaction. Similar to {@link Batch} any write operation that is
  * applied on a transaction will only be sent to the Datastore upon {@link #commit}. A call to
  * {@link #rollback} will invalidate the transaction and discard the changes. Any read operation
  * that is done by a transaction will be part of it and therefore a {@code commit} is guaranteed to
- * fail if an entity was modified outside of the transaction after it was read. Write operation on
- * this transaction will not be reflected by read operation (as the changes are only sent to the
+ * fail if an entity was modified outside the transaction after it was read. Write operation on this
+ * transaction will not be reflected by read operation (as the changes are only sent to the
  * Datastore upon {@code commit}. A usage example:
  *
  * <pre>{@code
@@ -52,7 +53,14 @@
  *
  * @see <a href="https://cloud.google.com/datastore/docs/concepts/transactions">Google Cloud
  *     Datastore transactions</a>
+ *     <p><b> WARNING: This class maintains an internal state in terms of {@link
+ *     java.util.LinkedHashMap} and {@link java.util.LinkedHashSet} which gets updated on every
+ *     method call performing CRUD operations to record the mutations. Since {@link
+ *     java.util.LinkedHashMap} is not thread safe as per its <a
+ *     href="https://docs.oracle.com/javase/8/docs/api/java/util/LinkedHashMap.html">documentation</a>,
+ *     This class too should not be treated as a thread safe class. </b>
  */
+@NotThreadSafe
 public interface Transaction extends DatastoreBatchWriter, DatastoreReaderWriter {
 
   interface Response {
