Document read effects after SharedValue.setValue (#1261)

Closes #1254.

Author: kezhuw

curator-recipes/src/main/java/org/apache/curator/framework/recipes/shared/SharedCount.java

@@ -65,7 +65,10 @@ public VersionedValue<Integer> getVersionedValue() {
     }
 
     /**
-     * Change the shared count value irrespective of its previous state
+     * Change the shared count value irrespective of its previous state.
+     *
+     * <p>Later {@link #getCount()} will get some more updated value, whether that value is set
+     * by this session or a different one cannot be guaranteed though.
      *
      * @param newCount new value
      * @throws Exception ZK errors, interruptions, etc.
@@ -100,6 +103,9 @@ public boolean trySetCount(int newCount) throws Exception {
      * value is updated. i.e. if the count is not successful you can get the updated value
      * by calling {@link #getCount()}.
      *
+     * <p>Later {@link #getCount()} will get some more updated value, whether that value is set
+     * by this session or a different one cannot be guaranteed though.
+     *
      * @param newCount the new value to attempt
      * @return true if the change attempt was successful, false if not. If the change
      * was not successful, {@link #getCount()} will return the updated value

curator-recipes/src/main/java/org/apache/curator/framework/recipes/shared/SharedValue.java

@@ -130,7 +130,10 @@ public VersionedValue<byte[]> getVersionedValue() {
     }
 
     /**
-     * Change the shared value irrespective of its previous state
+     * Change the shared value irrespective of its previous state.
+     *
+     * <p>Later {@link #getValue()} will get some more updated value, whether that value is set
+     * by this session or a different one cannot be guaranteed though.
      *
      * @param newValue new value
      * @throws Exception ZK errors, interruptions, etc.
@@ -168,6 +171,9 @@ public boolean trySetValue(byte[] newValue) throws Exception {
      * value is updated. i.e. if the value is not successful you can get the updated value
      * by calling {@link #getValue()}.
      *
+     * <p>Later {@link #getValue()} will get some more updated value, whether that value is set
+     * by this session or a different one cannot be guaranteed though.
+     *
      * @param newValue the new value to attempt
      * @return true if the change attempt was successful, false if not. If the change
      * was not successful, {@link #getValue()} will return the updated value