HCOLL-155 added java doc to - ReadContext<K, V> getUsingLocked(@NotNull K key, @NotNull V usingValue);

src/main/java/net/openhft/chronicle/map/ChronicleMap.java

@@ -32,13 +32,9 @@ import java.util.concurrent.ConcurrentMap;
 /**
  * Extension of {@link ConcurrentMap} interface, stores the data off-heap.
  *
- * <p>For information on
- * <ul>
- *     <li>how to construct a {@code ChronicleMap}</li>
- *     <li>{@code ChronicleMap} flavors and properties</li>
- *     <li>available configurations</li>
- * </ul>
- * see {@link AbstractChronicleMapBuilder} documentation.
+ * <p>For information on <ul> <li>how to construct a {@code ChronicleMap}</li> <li>{@code
+ * ChronicleMap} flavors and properties</li> <li>available configurations</li> </ul> see {@link
+ * AbstractChronicleMapBuilder} documentation.
  *
  * <p>Functionally this interface defines some methods supporting garbage-free off-heap programming:
  * {@link #getUsing(Object, Object)}, {@link #acquireUsing(Object, Object)}.
@@ -47,8 +43,8 @@ import java.util.concurrent.ConcurrentMap;
  * form, that shouldn't necessary be the same equality relation as defined by built-in {@link
  * Object#equals(Object)} method, which is prescribed by general {@link Map} contract.
  *
- * <p>Note that {@code ChronicleMap} extends {@link Closeable}, don't forget
- * to {@linkplain #close() close} map when it is no longer needed.
+ * <p>Note that {@code ChronicleMap} extends {@link Closeable}, don't forget to {@linkplain #close()
+ * close} map when it is no longer needed.
  *
  * @param <K> the map key type
  * @param <V> the map value type
@@ -67,11 +63,12 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
      * no mapping for the key.
      *
      * <p>If the value class allows reusing, particularly if it is a {@link Byteable} subclass,
-     * consider {@link #getUsing(Object, Object)} method instead of this to reduce garbage creation.
+     * consider {@link #getUsing(Object, Object)} method instead of this to reduce garbage
+     * creation.
      *
      * @param key the key whose associated value is to be returned
-     * @return the value to which the specified key is mapped after this method call,
-     * or {@code null} if no value is mapped
+     * @return the value to which the specified key is mapped after this method call, or {@code
+     * null} if no value is mapped
      * @see #getUsing(Object, Object)
      */
     @Override
@@ -81,17 +78,17 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
      * Returns the value to which the specified key is mapped, read to the provided {@code value}
      * object, if possible, or returns {@code null}, if this map contains no mapping for the key.
      *
-     * <p>If the specified key is present in the map, the value data is read to the provided
-     * {@code value} object via value marshaller's {@link BytesMarshaller#read(Bytes, Object)
-     * read(Bytes, value)} or value reader's {@link BytesReader#read(Bytes, long, Object)
-     * read(Bytes, size, value)} method, depending on what deserialization strategy is configured
-     * on the builder, using which this map was constructed. If the value deserializer is able
-     * to reuse the given {@code value} object, calling this method instead of {@link #get(Object)}
-     * could help to reduce garbage creation.
+     * <p>If the specified key is present in the map, the value data is read to the provided {@code
+     * value} object via value marshaller's {@link BytesMarshaller#read(Bytes, Object) read(Bytes,
+     * value)} or value reader's {@link BytesReader#read(Bytes, long, Object) read(Bytes, size,
+     * value)} method, depending on what deserialization strategy is configured on the builder,
+     * using which this map was constructed. If the value deserializer is able to reuse the given
+     * {@code value} object, calling this method instead of {@link #get(Object)} could help to
+     * reduce garbage creation.
      *
-     * <p>The provided {@code value} object is allowed to be {@code null}, in this case
-     * {@code map.getUsing(key, null)} call is semantically equivalent to simple
-     * {@code map.get(key)} call.
+     * <p>The provided {@code value} object is allowed to be {@code null}, in this case {@code
+     * map.getUsing(key, null)} call is semantically equivalent to simple {@code map.get(key)}
+     * call.
      *
      * @param key        the key whose associated value is to be returned
      * @param usingValue the object to read value data in, if possible
@@ -101,24 +98,70 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
      * @see #acquireUsing(Object, Object)
      * @see ChronicleMapBuilder#valueMarshaller(BytesMarshaller)
      */
-     V getUsing(K key, V usingValue);
+    V getUsing(K key, V usingValue);
 
-    // todo document
-    ReadContext<K,V> getUsingLocked(@NotNull K key, @NotNull V usingValue);
+    /**
+     * The method is similar {@link  V getUsing(K key, V usingValue);}  but in addition locks the
+     * map segment to operations to be performed atomically. ( see the example below )
+     *
+     * Returns the  ReadContext which holds a map segment lock and provides method to get the value
+     * ( to which the specified key is mapped)  atomically ( see example below for an explanation ),
+     * read to the provided {@code value} object, if possible, or returns {@code null}, if this map
+     * contains no mapping for the key.
+     *
+     * <p>If the specified key is present in the map, the value readContext.value() uses the
+     * provided {@code usingValue} object via value marshaller's {@link BytesMarshaller#read(Bytes,
+     * Object) read(Bytes, value)} or value reader's {@link BytesReader#read(Bytes, long, Object)
+     * read(Bytes, size, value)} method, depending on what deserialization strategy is configured on
+     * the builder, using which this map was constructed. If the value deserializer is able to reuse
+     * the given {@code usingValue} object, calling this method instead of {@link #get(Object)}
+     * could help to reduce garbage creation.
+     *
+     * <p> try (ReadContext<?, BondVOInterface> context = map.getUsingLocked(key,using)) {
+     * BondVOInterface bond =  context.value().getValue();
+     *
+     * long issueDate =  bond.getIssueDate(); String symbol = bond.getSymbol();
+     *
+     * // add your logic here ( the lock will ensure this bond can not be changed by another thread
+     * )
+     *
+     * } // the lock is released here </p>
+     *
+     * To ensure that you can read the 'issueDate' and 'symbol' can be read atomically, these values
+     * must be read while the segment lock is in place.
+     *
+     *
+     * <p>The provided {@code value} object is allowed to be {@code null}, in this case
+     *
+     * {@code map.getUsing(key, null)} call is semantically equivalent to simple
+     *
+     * {@code map.get(key)} call.
+     *
+     * @param key        the key whose associated value is to be returned
+     * @param usingValue the object to read value data in, if possible
+     * @return the read context containing the value to which the specified key is mapped
+     *
+     * no mapping for the key
+     * @see #get(Object)
+     * @see #acquireUsing(Object, Object)
+     * @see ChronicleMapBuilder#valueMarshaller(BytesMarshaller)
+     */
+    @NotNull
+    ReadContext<K, V> getUsingLocked(@NotNull K key, @NotNull V usingValue);
 
     /**
      * Acquire a value for a key, creating if absent.
      *
-     * <p>If the specified key if absent in the map, {@linkplain
-     * AbstractChronicleMapBuilder#defaultValue(Object) default value} is taken or {@linkplain
-     * AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider) default value
-     * provider} is called. Then this object is put to this map for the specified key.
+     * <p>If the specified key if absent in the map, {@linkplain AbstractChronicleMapBuilder#defaultValue(Object)
+     * default value} is taken or {@linkplain AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider)
+     * default value provider} is called. Then this object is put to this map for the specified
+     * key.
      *
-     * <p>Then, either if the key was initially absent in the map or already present,
-     * the value is deserialized just as during {@link #getUsing(Object, Object)
-     * getUsing(key, usingValue)} call, passed the same {@code key} and {@code usingValue} as into
-     * this method call. This means, as in {@link #getUsing}, {@code usingValue} could safely be
-     * {@code null}, in this case a new value instance is created to deserialize the data.
+     * <p>Then, either if the key was initially absent in the map or already present, the value is
+     * deserialized just as during {@link #getUsing(Object, Object) getUsing(key, usingValue)} call,
+     * passed the same {@code key} and {@code usingValue} as into this method call. This means, as
+     * in {@link #getUsing}, {@code usingValue} could safely be {@code null}, in this case a new
+     * value instance is created to deserialize the data.
      *
      * <p>In code, {@code acquireUsing} is specified as <pre>{@code
      * V acquireUsing(K key, V usingValue) {
@@ -127,25 +170,26 @@ public interface ChronicleMap<K, V> extends ConcurrentMap<K, V>, ChronicleHash {
      *     return getUsing(key, usingValue);
      * }}</pre> Where {@code defaultValue(key)} returns either {@linkplain
      * AbstractChronicleMapBuilder#defaultValue(Object) default value} or {@link
-     * AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider) defaultValueProvider.}
+     * AbstractChronicleMapBuilder#defaultValueProvider(DefaultValueProvider)
+     * defaultValueProvider.}
      *
      * <p>If the {@code ChronicleMap} is off-heap updatable, i. e. created via {@link
      * OffHeapUpdatableChronicleMapBuilder} builder (values are {@link Byteable}), there is one more
      * option of what to do if the key is absent in the map, see {@link
-     * OffHeapUpdatableChronicleMapBuilder#prepareValueBytesOnAcquire(PrepareValueBytes)}.
-     * By default, value bytes are just zeroed out, no default value, either provided for key
-     * or constant, is put for the absent key.
+     * OffHeapUpdatableChronicleMapBuilder#prepareValueBytesOnAcquire(PrepareValueBytes)}. By
+     * default, value bytes are just zeroed out, no default value, either provided for key or
+     * constant, is put for the absent key.
      *
      * @param key        the key whose associated value is to be returned
      * @param usingValue the object to read value data in, if possible
      * @return value to which the given key is mapping after this call, either found or created
      * @see #getUsing(Object, Object)
      */
-    public V acquireUsing(K key, V usingValue) ;
+    public V acquireUsing(K key, V usingValue);
 
 
-    // todo document
-    WriteContext<K,V> acquireUsingLocked(@NotNull K key, @NotNull V usingValue);
+    @NotNull
+    WriteContext<K, V> acquireUsingLocked(@NotNull K key, @NotNull V usingValue);
 
 
 }

src/main/java/net/openhft/chronicle/map/StatelessChronicleMap.java

@@ -400,13 +400,15 @@ class StatelessChronicleMap<K, V> implements ChronicleMap<K, V>, Closeable {
                 "clients");
     }
 
+    @NotNull
     @Override
-    public WriteContext<K,V> acquireUsingLocked(K key, V usingValue) {
+    public WriteContext<K,V> acquireUsingLocked(@NotNull K key, @NotNull V usingValue) {
         throw new UnsupportedOperationException();
     }
 
+    @NotNull
     @Override
-    public ReadContext<K,V> getUsingLocked(K key, V usingValue) {
+    public ReadContext<K,V> getUsingLocked(@NotNull K key, @NotNull V usingValue) {
         throw new UnsupportedOperationException();
     }
 

src/main/java/net/openhft/chronicle/map/VanillaChronicleMap.java

@@ -373,13 +373,15 @@ class VanillaChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
         }
     }
 
+    @NotNull
     @Override
-    public WriteContext<K, V> acquireUsingLocked(K key, V usingValue) {
+    public WriteContext<K, V> acquireUsingLocked(@NotNull K key, @NotNull V usingValue) {
         return this.lookupUsing(key, usingValue, LockType.WRITE_LOCK);
     }
 
+    @NotNull
     @Override
-    public ReadContext<K, V> getUsingLocked(K key, V usingValue) {
+    public ReadContext<K, V> getUsingLocked(@NotNull K key, @NotNull V usingValue) {
         return this.lookupUsing(key, usingValue, LockType.READ_LOCK);
     }