Clarify usage of LocalStorageHelper, explicitly specify which operations are supported and which are not (#2334)

vam-google · web-flow · commit 9ddeb40ad444 · 2017-08-11T14:09:36.000-07:00
diff --git a/TESTING.md b/TESTING.md
@@ -208,7 +208,9 @@ You can test against an in-memory local Resource Manager by following these step
 
 #### On your machine
 
-You can test against an in-memory local Storage by following these steps:
+You can test against an in-memory local Storage. The in-memory configuration supports only limited number of operations; please refer to the `LocalStorageHelper` class documentation for more details. Please use `RemoteStorageHelper` (see next section) if you need to use operations which are not supported by `LocalStorageHelper`. 
+
+To use the in-memory configuration please follow these steps:
 
 1. Follow the [Quickstart instructions][cloud-nio] to add the nio dependency to your project.
 2. In your program, create and use a fake Storage service object.  For example:
@@ -221,7 +223,7 @@ You can test against an in-memory local Storage by following these steps:
 
 #### Remote
 
-The alternative way of testing is to create a test project.  `RemoteStorageHelper` contains convenience methods to make setting up and cleaning up the test project easier.  To use this class, follow the steps below:
+The alternative way of testing is to create a test project. This way allows using operations not supported by the in-memory configuration.  `RemoteStorageHelper` contains convenience methods to make setting up and cleaning up the test project easier.  To use this class, follow the steps below:
 
 1. Create a test Google Cloud project.
 
diff --git a/google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/testing/LocalStorageHelper.java b/google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/testing/LocalStorageHelper.java
@@ -23,6 +23,31 @@
 /**
  * Utility to create an in-memory storage configuration for testing. Storage options can be
  * obtained via the {@link #getOptions()} method. Returned options will point to FakeStorageRpc.
+ *
+ * <p>Note, the created in-memory storage configuration supports limited set of operations and is <b>not</b> thread-safe:
+ * <ul>
+ * <li>Supported operations
+ *   <ul>
+ *   <li>object create
+ *   <li>object get
+ *   <li>object delete
+ *   <li>list the contents of a bucket
+ *   </ul>
+ * <li>Unsupported operations
+ *   <ul>
+ *   <li>bucket create
+ *   <li>bucket get
+ *   <li>bucket delete
+ *   <li>list all buckets
+ *   <li>generations
+ *   <li>file attributes
+ *   <li>patch
+ *   <li>continueRewrite
+ *   <li>createBatch
+ *   <li>checksums, etags
+ *   <li>IAM operations</li>
+ *   </ul>
+ * </ul>
  */
 public final class LocalStorageHelper {
 
