Added MapEntries' contexts and updated SPI documentation

src/main/java/net/openhft/chronicle/hash/HashContext.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2015 Higher Frequency Trading
+ *
+ *  http://www.higherfrequencytrading.com
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package net.openhft.chronicle.hash;
+
+/**
+ * Root interface for contexts, in which {@link HashEntry HashEntries} could be accessed.
+ * 
+ * @param <K> the key type of accessed {@link ChronicleHash}
+ */
+public interface HashContext<K> {
+    /**
+     * Returns the accessed {@code ChronicleHash}.
+     */
+    ChronicleHash<K, ?> hash();
+}

src/main/java/net/openhft/chronicle/hash/HashEntry.java

@@ -29,6 +29,11 @@ import org.jetbrains.annotations.NotNull;
  * @see MapEntryOperations
  */
 public interface HashEntry<K> {
+    /**
+     * Returns the context, in which the entry is accessed.
+     */
+    HashContext<K> context();
+    
     /**
      * Returns the entry key.
      */

src/main/java/net/openhft/chronicle/hash/ReplicationContext.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2015 Higher Frequency Trading
+ *
+ *  http://www.higherfrequencytrading.com
+ *  
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *  
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *  
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package net.openhft.chronicle.hash;
+
+/**
+ * Context of internal replication operation.
+ *
+ * @param <K> the key type of accessed {@link ChronicleHash}
+ */
+public interface ReplicationContext<K> extends HashContext<K> {
+}

src/main/java/net/openhft/chronicle/hash/Value.java

@@ -25,7 +25,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Dual bytes/object access to keys/values/elements.
  * 
- * <p>Bytes access: {@link #access()} + {@link #handle()} + {@link #size()}.
+ * <p>Bytes access: {@link #access()} + {@link #handle()} + {@link #offset()} + {@link #size()}.
  * 
  * <p>Object access: {@link #get()}. 
  * 

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

@@ -19,12 +19,50 @@
 package net.openhft.chronicle.map;
 
 import net.openhft.chronicle.hash.Value;
+import org.jetbrains.annotations.NotNull;
 
+/**
+ * Low-level operational context for the situations, when the new entry is going to be inserted
+ * into the {@link ChronicleMap}.
+ *
+ * @param <K> type of the key in {@code ChronicleMap}
+ * @param <V> type of the value in {@code ChronicleMap}
+ * 
+ * @see MapAbsentEntryOperations
+ * @see MapQueryContext#absentEntry() 
+ */
 public interface MapAbsentEntry<K, V> {
-    
-    Value<K, ?> absentKey();
-    
+
+    /**
+     * Returns the context, in which the entry is going to be inserted into the map.
+     */
+    @NotNull MapContext<K, V> context();
+
+    /**
+     * Returns the key is going to be inserted into the {@code ChronicleMap}.
+     */
+    @NotNull Value<K, ?> absentKey();
+
+    /**
+     * Inserts the new entry into the map, of {@link #absentKey() the key} and the given value.
+     * Returns {@code true} if the insertion  was successful, {@code false} if it failed for
+     * any reason.
+     *
+     * <p>This method if the default implementation for {@link MapAbsentEntryOperations#insert},
+     * which might be customized over the default.
+     *
+     * @throws IllegalStateException if some locking/state conditions required to perform insertion
+     * operation are not met
+     */
     boolean defaultInsert(Value<V, ?> value);
-    
-    Value<V, ?> defaultValue();
+
+    /**
+     * Returns the "nil" value, which should be inserted into the map in this context. This
+     * is primarily used in {@link ChronicleMap#acquireUsing} operation implementation, i. e. {@link
+     * MapMethods#acquireUsing}.
+     *
+     * <p>This method if the default implementation for {@link
+     * MapAbsentEntryOperations#defaultValue}, which might be customized over the default.
+     */
+    @NotNull Value<V, ?> defaultValue();
 }

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

@@ -21,12 +21,36 @@ package net.openhft.chronicle.map;
 import net.openhft.chronicle.hash.Value;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * SPI interface for customizing "low-level" insertion of a new entry into {@link ChronicleMap}.
+ *
+ * @param <K> type of the key in {@code ChronicleMap}
+ * @param <V> type of the value in {@code ChronicleMap}
+ */
 public interface MapAbsentEntryOperations<K, V> {
-    
+
+    /**
+     * Inserts the new entry into the map, of {@link MapAbsentEntry#absentKey() the key} from
+     * the given insertion context (<code>absentEntry</code>) and the given {@code value}.
+     * Returns {@code true} if the insertion  was successful, {@code false} if it failed
+     * for any reason.
+     *
+     * @implNote simply delegates to {@link MapAbsentEntry#defaultInsert(Value)}.
+     *
+     * @throws IllegalStateException if some locking/state conditions required to perform insertion
+     * operation are not met
+     */
     default boolean insert(@NotNull MapAbsentEntry<K, V> absentEntry, Value<V, ?> value) {
         return absentEntry.defaultInsert(value);
     }
 
+    /**
+     * Returns the "nil" value, which should be inserted into the map, in the given
+     * {@code absentEntry} context. This is primarily used in {@link ChronicleMap#acquireUsing}
+     * operation implementation, i. e. {@link MapMethods#acquireUsing}.
+     * 
+     * @implNote simply delegates to {@link MapAbsentEntry#defaultValue()}.
+     */
     default Value<V, ?> defaultValue(@NotNull MapAbsentEntry<K, V> absentEntry) {
         return absentEntry.defaultValue();
     }

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

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2015 Higher Frequency Trading
+ *
+ *  http://www.higherfrequencytrading.com
+ *  
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *  
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *  
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package net.openhft.chronicle.map;
+
+import net.openhft.chronicle.hash.HashContext;
+
+/**
+ * Context, in which {@link MapEntry MapEntries} are accessed.
+ * 
+ * @param <K> the key type of accessed {@link ChronicleMap}
+ * @param <V> the value type of accessed {@code ChronicleMap}
+ */
+public interface MapContext<K, V> extends HashContext<K> {
+    /**
+     * Returns the accessed {@code ChronicleMap}.
+     */
+    @Override
+    ChronicleMap<K, V> hash();
+
+    /**
+     * Synonym to {@link #hash()}.
+     */
+    ChronicleMap<K, V> map();
+}

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

@@ -22,6 +22,7 @@ package net.openhft.chronicle.map;
 
 import net.openhft.chronicle.hash.HashEntry;
 import net.openhft.chronicle.hash.Value;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Access to the <i>present</i> {@link ChronicleMap} entry.
@@ -32,10 +33,13 @@ import net.openhft.chronicle.hash.Value;
  * @see MapEntryOperations
  */
 public interface MapEntry<K, V> extends HashEntry<K> {
+    @Override
+    @NotNull MapContext<K, V> context();
+
     /**
      * Returns the entry value.
      */
-    Value<V, ?> value();
+    @NotNull Value<V, ?> value();
 
     /**
      * Replaces the entry's value with the new one. Returns {@code true} if the replace operation

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

@@ -49,7 +49,7 @@ public interface MapEntryOperations<K, V> {
      * operation was successful, {@code false} if it failed for any reason.
      *
      * @implNote simply delegates to {@link MapEntry#defaultReplaceValue(Value)
-     * entry.defaultReplace(newValue)} 
+     * entry.defaultReplace(newValue)}.
      *
      * @param entry the entry to replace the value in 
      * @throws IllegalStateException if some locking/state conditions required to perform replace

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

@@ -33,7 +33,7 @@ public interface MapQueryContext<K, V> extends InterProcessReadWriteUpdateLock,
         MapEntryOperations<K, V>, MapAbsentEntryOperations<K, V> {
 
     /**
-     * Returns the queried key as a value.
+     * Returns the queried key as a {@code Value}.
      */
     Value<K, ?> queriedKey();