From 4fb73bb8218b1ba4ef6d2062e8bfab0049d36b92 Mon Sep 17 00:00:00 2001 From: leventov Date: Wed, 27 May 2015 04:30:58 +0100 Subject: [PATCH] Improved documentation --- pom.xml | 10 ++++++- .../openhft/chronicle/hash/AbstractValue.java | 21 +++++++++++++++ .../chronicle/hash/AcceptanceDecision.java | 24 ++++++++++++++++- .../hash/ExternalHashQueryContext.java | 10 +++++++ .../chronicle/hash/HashAbsentEntry.java | 12 +++++++++ .../net/openhft/chronicle/hash/HashEntry.java | 9 +++++-- .../chronicle/hash/HashQueryContext.java | 20 ++++++++++---- .../openhft/chronicle/hash/KeyContext.java | 1 + .../net/openhft/chronicle/hash/Value.java | 19 +++++++++++--- .../chronicle/hash/hashing/Access.java | 2 ++ .../chronicle/hash/hashing/BytesAccess.java | 1 + .../hash/hashing/LongHashFunction.java | 3 +++ .../DefaultEventualConsistencyStrategy.java | 26 ++++++++++++++++++- .../chronicle/map/DefaultValueProvider.java | 2 ++ .../map/ExternalMapQueryContext.java | 11 ++++++++ .../openhft/chronicle/map/MapAbsentEntry.java | 17 +++++++++--- .../net/openhft/chronicle/map/MapContext.java | 21 +++++++++++---- .../net/openhft/chronicle/map/MapEntry.java | 26 ++++++++++++++----- .../chronicle/map/MapEntryOperations.java | 14 ++++++---- .../openhft/chronicle/map/MapKeyContext.java | 5 ++++ .../chronicle/map/MapQueryContext.java | 14 ++++++---- .../replication/MapRemoteQueryContext.java | 10 +++++++ .../set/ExternalSetQueryContext.java | 9 +++++++ .../openhft/chronicle/set/SetAbsentEntry.java | 21 ++++++++++++++- .../net/openhft/chronicle/set/SetContext.java | 15 +++++++++-- .../net/openhft/chronicle/set/SetEntry.java | 16 ++++++++++++ .../chronicle/set/SetQueryContext.java | 13 ++++++++++ .../replication/SetRemoteQueryContext.java | 9 +++++++ 28 files changed, 319 insertions(+), 42 deletions(-) diff --git a/pom.xml b/pom.xml index eaeaaf1a8..7b31fac4f 100755 --- a/pom.xml +++ b/pom.xml @@ -213,13 +213,21 @@ org.apache.maven.plugins maven-javadoc-plugin + 2.10.2 http://openhft.github.io/Java-Lang/apidocs/ + http://openhft.github.io/Chronicle-Bytes/apidocs/ + http://openhft.github.io/Chronicle-Algorithms/apidocs/ - net.openhft.chronicle.hash.serialization.internal:net.openhft.xstream:net.openhft.xstream.*:net.openhft.chronicle.hash.impl.* + net.openhft.chronicle.hash.serialization.internal:net.openhft.xstream:net.openhft.xstream.*:net.openhft.chronicle.hash.impl:net.openhft.chronicle.map.impl:net.openhft.chronicle.hash.hashing + + net/openhft/chronicle/map/VanillaChronicleMap.java + net/openhft/chronicle/map/ReplicatedChronicleMap.java + net/openhft/chronicle/map/Replica.java + -Xdoclint:none diff --git a/src/main/java/net/openhft/chronicle/hash/AbstractValue.java b/src/main/java/net/openhft/chronicle/hash/AbstractValue.java index e42b91382..b95adf57e 100644 --- a/src/main/java/net/openhft/chronicle/hash/AbstractValue.java +++ b/src/main/java/net/openhft/chronicle/hash/AbstractValue.java @@ -20,13 +20,31 @@ package net.openhft.chronicle.hash; import net.openhft.chronicle.algo.hashing.LongHashFunction; +/** + * Defines reasonable defaults for {@code Value}'s {@code equals()}, {@code hashCode()} and + * {@code toString()}. They should be default implementations in the {@code Value} interface itself, + * but Java 8 doesn't allow to override {@code Object}'s methods by default implementations + * in interfaces. + */ public abstract class AbstractValue implements Value { + /** + * Constructor for use by subclasses. + */ + protected AbstractValue() {} + + /** + * Computes value's hash code by applying a hash function to {@code Value}'s bytes + * representation. + */ @Override public int hashCode() { return (int) hash(LongHashFunction.city_1_1()); } + /** + * Compares {@code Value}s' bytes representations. + */ @Override public boolean equals(Object obj) { return obj != null && @@ -34,6 +52,9 @@ public abstract class AbstractValue implements Value { Value.bytesEquivalent(this, (Value) obj); } + /** + * Delegates to {@code Value}'s object {@code toString()}. + */ @Override public String toString() { return get().toString(); diff --git a/src/main/java/net/openhft/chronicle/hash/AcceptanceDecision.java b/src/main/java/net/openhft/chronicle/hash/AcceptanceDecision.java index e6392e8fc..f3c7a9f37 100644 --- a/src/main/java/net/openhft/chronicle/hash/AcceptanceDecision.java +++ b/src/main/java/net/openhft/chronicle/hash/AcceptanceDecision.java @@ -18,6 +18,28 @@ package net.openhft.chronicle.hash; +import net.openhft.chronicle.map.replication.MapRemoteOperations; +import net.openhft.chronicle.set.replication.SetRemoteOperations; + +/** + * Decision, if {@link MapRemoteOperations remote modification operation} should be accepted + * or discarded. + * * + * @see MapRemoteOperations + * @see SetRemoteOperations + */ public enum AcceptanceDecision { - ACCEPT, DISCARD + /** + * Acceptance decision -- the remote modification operation is applied to the local + * {@link ChronicleHash} state. This decision should also been returned, when the actual + * state modification is not needed (for example, remote {@code remove entry} operation, while + * the entry is not present in the ChronicleHash locally), but the operation is generally + * considered acceptable. + */ + ACCEPT, + + /** + * Discard decision -- the remote modification operation is rejected. + */ + DISCARD } diff --git a/src/main/java/net/openhft/chronicle/hash/ExternalHashQueryContext.java b/src/main/java/net/openhft/chronicle/hash/ExternalHashQueryContext.java index 1c5dcd9be..6e4639223 100644 --- a/src/main/java/net/openhft/chronicle/hash/ExternalHashQueryContext.java +++ b/src/main/java/net/openhft/chronicle/hash/ExternalHashQueryContext.java @@ -1,7 +1,17 @@ package net.openhft.chronicle.hash; +/** + * {@link HashQueryContext} + {@link AutoCloseable}, for external {@link ChronicleHash} queries + * in try-with-resources blocks. + * + * @param the hash key type + * @see ChronicleHash#queryContext(Object) + */ public interface ExternalHashQueryContext extends HashQueryContext, AutoCloseable { + /** + * Could throw only unchecked exception. + */ @Override void close(); } diff --git a/src/main/java/net/openhft/chronicle/hash/HashAbsentEntry.java b/src/main/java/net/openhft/chronicle/hash/HashAbsentEntry.java index 2e8300055..d471e085a 100644 --- a/src/main/java/net/openhft/chronicle/hash/HashAbsentEntry.java +++ b/src/main/java/net/openhft/chronicle/hash/HashAbsentEntry.java @@ -1,7 +1,19 @@ package net.openhft.chronicle.hash; +import net.openhft.chronicle.map.MapAbsentEntry; +import net.openhft.chronicle.set.SetAbsentEntry; import org.jetbrains.annotations.NotNull; +/** + * Low-level operational context for the situations, when the new entry is going to be inserted + * into the {@link ChronicleHash}. + * + *

This interface is not usable by itself; it merely defines the common base for {@link + * MapAbsentEntry} and {@link SetAbsentEntry}. + * + * @param the hash key type + * @see HashQueryContext#absentEntry() + */ public interface HashAbsentEntry { /** diff --git a/src/main/java/net/openhft/chronicle/hash/HashEntry.java b/src/main/java/net/openhft/chronicle/hash/HashEntry.java index 91c3d7b66..e1dd630b5 100644 --- a/src/main/java/net/openhft/chronicle/hash/HashEntry.java +++ b/src/main/java/net/openhft/chronicle/hash/HashEntry.java @@ -18,14 +18,19 @@ package net.openhft.chronicle.hash; +import net.openhft.chronicle.map.MapEntry; import net.openhft.chronicle.map.MapEntryOperations; +import net.openhft.chronicle.set.SetEntry; import org.jetbrains.annotations.NotNull; /** - * Access to the present {@code ChronicleHash} entry. + * The present {@code ChronicleHash} entry context. + * + *

This interface is not usable by itself; it merely defines the common base for {@link MapEntry} + * and {@link SetEntry}. * * @param type of the key in {@code ChronicleHash} - * @see MapEntryOperations + * @see HashQueryContext#entry() */ public interface HashEntry { /** diff --git a/src/main/java/net/openhft/chronicle/hash/HashQueryContext.java b/src/main/java/net/openhft/chronicle/hash/HashQueryContext.java index 3196f42f2..d3b2269ad 100644 --- a/src/main/java/net/openhft/chronicle/hash/HashQueryContext.java +++ b/src/main/java/net/openhft/chronicle/hash/HashQueryContext.java @@ -2,6 +2,12 @@ package net.openhft.chronicle.hash; import net.openhft.chronicle.hash.locks.InterProcessReadWriteUpdateLock; +/** + * Context of {@link ChronicleHash} operations with individual keys. + * + * @param the hash key type + * @see ChronicleHash#queryContext(Object) + */ public interface HashQueryContext extends HashContext, InterProcessReadWriteUpdateLock { /** @@ -10,16 +16,20 @@ public interface HashQueryContext extends HashContext, InterProcessReadWri Value queriedKey(); /** - * Returns the entry access object, if the entry with the queried key is present - * in the hash, returns {@code null} is the entry is absent. Might acquire - * {@link #readLock} before searching for the key, if the context is not locked yet. + * Returns the entry context, if the entry with the queried key is present + * in the {@code ChronicleHash}, returns {@code null} is the entry is absent. + * + * @implNote Might acquire {@link #readLock} before searching for the key, if the context + * is not locked yet. */ HashEntry entry(); /** * Returns the special absent entry object, if the entry with the queried key - * is absent in the hash, returns {@code null}, if the entry is present. Might - * acquire {@link #readLock} before searching for the key, if the context is not locked yet. + * is absent in the hash, returns {@code null}, if the entry is present. + * + * @implNote Might acquire {@link #readLock} before searching for the key, if the context + * is not locked yet. */ HashAbsentEntry absentEntry(); } diff --git a/src/main/java/net/openhft/chronicle/hash/KeyContext.java b/src/main/java/net/openhft/chronicle/hash/KeyContext.java index e15a10679..2ebf848a7 100644 --- a/src/main/java/net/openhft/chronicle/hash/KeyContext.java +++ b/src/main/java/net/openhft/chronicle/hash/KeyContext.java @@ -35,6 +35,7 @@ import java.util.ConcurrentModificationException; * * * @param key type + * @deprecated incoherent abstraction. Replaced by {@link HashQueryContext} and {@link HashEntry} */ @Deprecated public interface KeyContext extends AutoCloseable, InterProcessReadWriteUpdateLock { diff --git a/src/main/java/net/openhft/chronicle/hash/Value.java b/src/main/java/net/openhft/chronicle/hash/Value.java index 17e341065..5ebd1a4b7 100644 --- a/src/main/java/net/openhft/chronicle/hash/Value.java +++ b/src/main/java/net/openhft/chronicle/hash/Value.java @@ -29,20 +29,33 @@ import org.jetbrains.annotations.Nullable; * *

Object access: {@link #get()}. * - * In most cases, each particular value wraps either some object or some bytes. Object is marshalled - * to bytes lazily on demand, and bytes are lazily deserialized to object, accordingly. + *

In most cases, each particular value wraps either some object or some bytes. Object + * is marshalled to bytes lazily on demand, and bytes are lazily deserialized to object, + * accordingly. * * @param type of the accessed objects * @param type of the handle for bytes access */ public interface Value { - + + /** + * Returns access to the value's bytes. + */ ReadAccess access(); + /** + * Returns a handle to access the value's bytes. + */ T handle(); + /** + * Returns the offset to the value's bytes. + */ long offset(); + /** + * Returns the size of the value's bytes. + */ long size(); default long hash(LongHashFunction f) { diff --git a/src/main/java/net/openhft/chronicle/hash/hashing/Access.java b/src/main/java/net/openhft/chronicle/hash/hashing/Access.java index 6f896bd7f..b70d0debf 100644 --- a/src/main/java/net/openhft/chronicle/hash/hashing/Access.java +++ b/src/main/java/net/openhft/chronicle/hash/hashing/Access.java @@ -55,7 +55,9 @@ import static java.nio.ByteOrder.LITTLE_ENDIAN; * * @param the type of the object to access * @see LongHashFunction#hash(Object, Access, long, long) + * @deprecated moved to Chronicle-Bytes: {@link net.openhft.chronicle.bytes.Access} */ +@Deprecated public abstract class Access { /** diff --git a/src/main/java/net/openhft/chronicle/hash/hashing/BytesAccess.java b/src/main/java/net/openhft/chronicle/hash/hashing/BytesAccess.java index ad08c3649..61c625156 100644 --- a/src/main/java/net/openhft/chronicle/hash/hashing/BytesAccess.java +++ b/src/main/java/net/openhft/chronicle/hash/hashing/BytesAccess.java @@ -20,6 +20,7 @@ import net.openhft.lang.io.Bytes; import java.nio.ByteOrder; +@Deprecated public final class BytesAccess extends Access { public static final BytesAccess INSTANCE = new BytesAccess(); diff --git a/src/main/java/net/openhft/chronicle/hash/hashing/LongHashFunction.java b/src/main/java/net/openhft/chronicle/hash/hashing/LongHashFunction.java index 4f57a6b72..b5b62b145 100644 --- a/src/main/java/net/openhft/chronicle/hash/hashing/LongHashFunction.java +++ b/src/main/java/net/openhft/chronicle/hash/hashing/LongHashFunction.java @@ -49,7 +49,10 @@ import static net.openhft.chronicle.hash.hashing.UnsafeAccess.*; * * * @see BytesInterop#hash(LongHashFunction, Object) + * @deprecated moved to Chronicle-Algorithms: + * {@link net.openhft.chronicle.algo.hashing.LongHashFunction} */ +@Deprecated public abstract class LongHashFunction implements Serializable { private static final long serialVersionUID = 0L; diff --git a/src/main/java/net/openhft/chronicle/hash/replication/DefaultEventualConsistencyStrategy.java b/src/main/java/net/openhft/chronicle/hash/replication/DefaultEventualConsistencyStrategy.java index 5bf2c0669..5614e8b76 100644 --- a/src/main/java/net/openhft/chronicle/hash/replication/DefaultEventualConsistencyStrategy.java +++ b/src/main/java/net/openhft/chronicle/hash/replication/DefaultEventualConsistencyStrategy.java @@ -19,12 +19,36 @@ package net.openhft.chronicle.hash.replication; import net.openhft.chronicle.hash.AcceptanceDecision; +import net.openhft.chronicle.hash.ChronicleHash; +import net.openhft.chronicle.hash.ChronicleHashBuilder; +import net.openhft.chronicle.map.replication.MapRemoteOperations; +import net.openhft.chronicle.set.replication.SetRemoteOperations; import static net.openhft.chronicle.hash.AcceptanceDecision.ACCEPT; import static net.openhft.chronicle.hash.AcceptanceDecision.DISCARD; +/** + * Specifies the default eventual consistency strategy for {@link ChronicleHashBuilder#replication( + * byte) replicated} {@link ChronicleHash}es: + * last write wins. If two writes to a single entry occurred simultaneously on different + * nodes, the write on the node with lower identifier wins. + * + * @see MapRemoteOperations + * @see SetRemoteOperations + */ public final class DefaultEventualConsistencyStrategy { - + + /** + * Returns the acceptance decision, should be made about the modification operation in the + * given {@code context}, aiming to modify the given {@code entry}. This method doesn't do any + * changes to {@code entry} nor {@code context} state. {@link MapRemoteOperations} and + * {@link SetRemoteOperations} method implementations should guide the result of calling this + * method to do something to actually apply the remote operation. + * + * @param entry the entry to be modified + * @param context the remote operation context + * @return if the remote operation should be accepted or discarded + */ public static AcceptanceDecision decideOnRemoteModification( HashReplicableEntry entry, RemoteOperationContext context) { long remoteTimestamp = context.remoteTimestamp(); diff --git a/src/main/java/net/openhft/chronicle/map/DefaultValueProvider.java b/src/main/java/net/openhft/chronicle/map/DefaultValueProvider.java index a0010e7b7..26458e069 100644 --- a/src/main/java/net/openhft/chronicle/map/DefaultValueProvider.java +++ b/src/main/java/net/openhft/chronicle/map/DefaultValueProvider.java @@ -28,7 +28,9 @@ import java.io.Serializable; * * @param map key class * @param map value class + * @deprecated specialize {@link MapEntryOperations#defaultValue(MapAbsentEntry)} instead */ +@Deprecated public interface DefaultValueProvider extends Serializable { /** * Returns a value to be put during {@link ChronicleMap#acquireUsing(Object, Object)} call diff --git a/src/main/java/net/openhft/chronicle/map/ExternalMapQueryContext.java b/src/main/java/net/openhft/chronicle/map/ExternalMapQueryContext.java index 1850a9bd2..ee86bfdae 100644 --- a/src/main/java/net/openhft/chronicle/map/ExternalMapQueryContext.java +++ b/src/main/java/net/openhft/chronicle/map/ExternalMapQueryContext.java @@ -20,6 +20,17 @@ package net.openhft.chronicle.map; import net.openhft.chronicle.hash.ExternalHashQueryContext; +/** + * {@link MapQueryContext} + {@link AutoCloseable}, for external {@link ChronicleMap} queries + * in try-with-resources blocks. + * + * @param the map key type + * @param the map value type + * @param the return type of {@link MapEntryOperations}, {@link + * ChronicleMapBuilder#entryOperations(MapEntryOperations) specified} for the queried {@code + * ChronicleMap} + * @see ChronicleMap#queryContext(Object) + */ public interface ExternalMapQueryContext extends MapQueryContext, ExternalHashQueryContext { } diff --git a/src/main/java/net/openhft/chronicle/map/MapAbsentEntry.java b/src/main/java/net/openhft/chronicle/map/MapAbsentEntry.java index 2cba0b7d9..a89e65260 100644 --- a/src/main/java/net/openhft/chronicle/map/MapAbsentEntry.java +++ b/src/main/java/net/openhft/chronicle/map/MapAbsentEntry.java @@ -38,20 +38,29 @@ public interface MapAbsentEntry extends HashAbsentEntry { @NotNull MapContext context(); /** - * Inserts the new entry into the map, of {@link #absentKey() the key} and the given value. + * Inserts the new entry into the map, of {@linkplain #absentKey() the key} and the given {@code + * value}. + * + *

This method is the default implementation for {@link MapEntryOperations#insert( + * MapAbsentEntry, Value)}, which might be customized over the default. * + * @param value the value to insert into the map along with {@link #absentKey() the key} * @throws IllegalStateException if some locking/state conditions required to perform insertion * operation are not met + * @see MapEntryOperations#insert(MapAbsentEntry, Value) */ void doInsert(Value value); /** - * 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}. + * Returns the default (or nil) value, that should be inserted into the map in + * this context. This is primarily used in {@link ChronicleMap#acquireUsing} operation + * implementation, i. e. {@link MapMethods#acquireUsing}. * *

This method if the default implementation for {@link * MapEntryOperations#defaultValue}, which might be customized over the default. + * + * @return the default value to be inserted into the map + * @see MapEntryOperations#defaultValue(MapAbsentEntry) */ @NotNull Value defaultValue(); } diff --git a/src/main/java/net/openhft/chronicle/map/MapContext.java b/src/main/java/net/openhft/chronicle/map/MapContext.java index aff38809d..ccf2ca7d0 100644 --- a/src/main/java/net/openhft/chronicle/map/MapContext.java +++ b/src/main/java/net/openhft/chronicle/map/MapContext.java @@ -24,12 +24,13 @@ import net.openhft.chronicle.hash.Value; /** * Context, in which {@link MapEntry MapEntries} are accessed. * - * @param the key type of accessed {@link ChronicleMap} - * @param the value type of accessed {@code ChronicleMap} + * @param the map key type + * @param the map value type + * @param the return type of {@link MapEntryOperations} specialized for the queried map */ public interface MapContext extends HashContext, MapEntryOperations { /** - * Returns the accessed {@code ChronicleMap}. + * Returns the accessed {@code ChronicleMap}. Synonym to {@link #map()}. */ @Override default ChronicleMap hash() { @@ -37,9 +38,19 @@ public interface MapContext extends HashContext, MapEntryOperations< } /** - * Synonym to {@link #hash()}. + * Returns the accessed {@code ChronicleMap}. Synonym to {@link #hash()}. */ ChronicleMap map(); - + + /** + * Wraps the given value as a {@code Value}. Useful when you need to pass a value + * to some method accepting {@code Value}, for example, {@link MapEntryOperations#replaceValue( + * MapEntry, Value)}, without allocating new objects (i. e. garbage) and {@code ThreadLocals}. + * + *

The returned {@code Value} object shouldn't outlive this {@code MapContext}. + * + * @param value the value object to wrap + * @return the value as {@code Value} + */ Value wrapValueAsValue(V value); } diff --git a/src/main/java/net/openhft/chronicle/map/MapEntry.java b/src/main/java/net/openhft/chronicle/map/MapEntry.java index 0cf14687d..357c59abe 100644 --- a/src/main/java/net/openhft/chronicle/map/MapEntry.java +++ b/src/main/java/net/openhft/chronicle/map/MapEntry.java @@ -1,5 +1,3 @@ - - /* * Copyright 2015 Higher Frequency Trading * @@ -25,12 +23,12 @@ import net.openhft.chronicle.hash.Value; import org.jetbrains.annotations.NotNull; /** - * Access to the present {@link ChronicleMap} entry. + * The present {@code ChronicleHash} entry context. * - * @param type of the key in {@code ChronicleMap} - * @param type of the value in {@code ChronicleMap} - * + * @param the map key type + * @param the map value type * @see MapEntryOperations + * @see MapQueryContext#entry() */ public interface MapEntry extends HashEntry { @Override @@ -42,10 +40,24 @@ public interface MapEntry extends HashEntry { @NotNull Value value(); /** - * Replaces the entry's value with the new one. + * Replaces the entry's value with the given {@code newValue}. + * + *

This method is the default implementation for {@link MapEntryOperations#replaceValue( + * MapEntry, Value)}, which might be customized over the default. * + * @param newValue the value to be put into the map instead of the {@linkplain #value() current + * value} * @throws IllegalStateException if some locking/state conditions required to perform replace * operation are not met */ void doReplaceValue(Value newValue); + + /** + * Removes the entry from the map. + * + *

This method is the default implementation for {@link MapEntryOperations#remove(MapEntry)}, + * which might be customized over the default. + */ + @Override + void doRemove(); } diff --git a/src/main/java/net/openhft/chronicle/map/MapEntryOperations.java b/src/main/java/net/openhft/chronicle/map/MapEntryOperations.java index daaf01f64..956590c34 100644 --- a/src/main/java/net/openhft/chronicle/map/MapEntryOperations.java +++ b/src/main/java/net/openhft/chronicle/map/MapEntryOperations.java @@ -22,16 +22,20 @@ import net.openhft.chronicle.hash.Value; import org.jetbrains.annotations.NotNull; /** - * SPI interface for customizing "low-level" modification operations on {@link ChronicleMap} entry. + * SPI interface for customizing "low-level" modification operations on {@link ChronicleMap} + * entries. * - * @param type of the key in {@code ChronicleMap} - * @param type of the value in {@code ChronicleMap} + * @param the map key type + * @param the map value type + * @see ChronicleMapBuilder#entryOperations(MapEntryOperations) */ public interface MapEntryOperations { /** - * Removes the given entry from the {@code ChronicleHash}. Returns {@code true} if the remove - * was successful, {@code false} if it was discarded for any reason. + * Removes the given entry from the map. + * + * @implNote default implementation calls {@link MapEntry#doRemove()} on the given entry + * and returns {@code null}. * * @param entry the entry to remove * @throws IllegalStateException if some locking/state conditions required to perform remove diff --git a/src/main/java/net/openhft/chronicle/map/MapKeyContext.java b/src/main/java/net/openhft/chronicle/map/MapKeyContext.java index 1917124e8..f7d124ec8 100644 --- a/src/main/java/net/openhft/chronicle/map/MapKeyContext.java +++ b/src/main/java/net/openhft/chronicle/map/MapKeyContext.java @@ -18,6 +18,11 @@ package net.openhft.chronicle.map; import net.openhft.chronicle.hash.KeyContext; +/** + * @param the map key type + * @param the map value type + * @deprecated incoherent abstraction. Replaced by {@link MapQueryContext} and {@link MapEntry} + */ @Deprecated public interface MapKeyContext extends KeyContext { diff --git a/src/main/java/net/openhft/chronicle/map/MapQueryContext.java b/src/main/java/net/openhft/chronicle/map/MapQueryContext.java index 0226eb367..5c8a6bc67 100644 --- a/src/main/java/net/openhft/chronicle/map/MapQueryContext.java +++ b/src/main/java/net/openhft/chronicle/map/MapQueryContext.java @@ -19,14 +19,18 @@ package net.openhft.chronicle.map; import net.openhft.chronicle.hash.HashQueryContext; +import net.openhft.chronicle.map.replication.MapRemoteOperations; import org.jetbrains.annotations.Nullable; /** - * The context of Map operations with individual keys (most: get(), put(), etc., opposed - * to bulk operations). - * - * @param - * @param + * The context of {@link ChronicleMap} operations with individual keys + * (most: {@code get()}, {@code put()}, etc., opposed to bulk operations). This is the main + * context type of {@link MapMethods} and {@link MapRemoteOperations}. + * + * @param the map key type + * @param the map value type + * @param the return type of {@link MapEntryOperations} specialized for the queried map + * @see ChronicleMap#queryContext(Object) */ public interface MapQueryContext extends HashQueryContext, MapContext { diff --git a/src/main/java/net/openhft/chronicle/map/replication/MapRemoteQueryContext.java b/src/main/java/net/openhft/chronicle/map/replication/MapRemoteQueryContext.java index c5c6c8b5c..168561eb2 100644 --- a/src/main/java/net/openhft/chronicle/map/replication/MapRemoteQueryContext.java +++ b/src/main/java/net/openhft/chronicle/map/replication/MapRemoteQueryContext.java @@ -20,9 +20,19 @@ package net.openhft.chronicle.map.replication; import net.openhft.chronicle.hash.replication.HashRemoteQueryContext; import net.openhft.chronicle.hash.replication.RemoteOperationContext; +import net.openhft.chronicle.map.ChronicleMap; +import net.openhft.chronicle.map.MapEntryOperations; import net.openhft.chronicle.map.MapQueryContext; import org.jetbrains.annotations.Nullable; +/** + * Context of remote {@link ChronicleMap} queries and internal replication operations. + * + * @param the map key type + * @param the map value type + * @param the return type of {@link MapEntryOperations} specialized for the queried map + * @see MapRemoteOperations + */ public interface MapRemoteQueryContext extends MapQueryContext, HashRemoteQueryContext { @Nullable diff --git a/src/main/java/net/openhft/chronicle/set/ExternalSetQueryContext.java b/src/main/java/net/openhft/chronicle/set/ExternalSetQueryContext.java index cdd14a56b..fda05d838 100644 --- a/src/main/java/net/openhft/chronicle/set/ExternalSetQueryContext.java +++ b/src/main/java/net/openhft/chronicle/set/ExternalSetQueryContext.java @@ -2,6 +2,15 @@ package net.openhft.chronicle.set; import net.openhft.chronicle.hash.ExternalHashQueryContext; +/** + * {@link SetQueryContext} + {@link AutoCloseable}, for external {@link ChronicleSet} queries + * in try-with-resources blocks. + * + * @param the set key type + * @param the return type of {@link SetEntryOperations}, specified for the queried {@code + * ChronicleSet} + * @see ChronicleSet#queryContext(Object) + */ public interface ExternalSetQueryContext extends SetQueryContext, ExternalHashQueryContext { } diff --git a/src/main/java/net/openhft/chronicle/set/SetAbsentEntry.java b/src/main/java/net/openhft/chronicle/set/SetAbsentEntry.java index baa5a5e11..14c1d37d9 100644 --- a/src/main/java/net/openhft/chronicle/set/SetAbsentEntry.java +++ b/src/main/java/net/openhft/chronicle/set/SetAbsentEntry.java @@ -2,9 +2,28 @@ package net.openhft.chronicle.set; import net.openhft.chronicle.hash.HashAbsentEntry; +/** + * Low-level operational context for the situations, when the new key is going to be inserted + * into the {@link ChronicleSet}. + * + * @param the set key type + * + * @see SetEntryOperations + * @see SetQueryContext#absentEntry() + */ public interface SetAbsentEntry extends HashAbsentEntry { @Override SetContext context(); - + + /** + * Inserts {@link #absentKey() the new key} into the set. + * + *

This method is the default implementation for {@link SetEntryOperations#insert( + * SetAbsentEntry)}, which might be customized over the default. + * + * @throws IllegalStateException if some locking/state conditions required to perform insertion + * operation are not met + * @see SetEntryOperations#insert(SetAbsentEntry) + */ void doInsert(); } diff --git a/src/main/java/net/openhft/chronicle/set/SetContext.java b/src/main/java/net/openhft/chronicle/set/SetContext.java index 08d4d5c52..33783a5b2 100644 --- a/src/main/java/net/openhft/chronicle/set/SetContext.java +++ b/src/main/java/net/openhft/chronicle/set/SetContext.java @@ -1,14 +1,25 @@ package net.openhft.chronicle.set; -import net.openhft.chronicle.hash.ChronicleHash; import net.openhft.chronicle.hash.HashContext; +/** + * Context, in which {@link SetEntry SetEntries} are accessed. + * + * @param the set key type + * @param the return type of {@link SetEntryOperations} specialized for the queried set + */ public interface SetContext extends HashContext, SetEntryOperations { + /** + * Returns the accessed {@code ChronicleSet}. Synonym to {@link #set()}. + */ @Override - default ChronicleHash hash() { + default ChronicleSet hash() { return set(); } + /** + * Returns the accessed {@code ChronicleSet}. Synonym to {@link #hash()}. + */ ChronicleSet set(); } diff --git a/src/main/java/net/openhft/chronicle/set/SetEntry.java b/src/main/java/net/openhft/chronicle/set/SetEntry.java index 2b549fc8d..9a939bbb9 100644 --- a/src/main/java/net/openhft/chronicle/set/SetEntry.java +++ b/src/main/java/net/openhft/chronicle/set/SetEntry.java @@ -2,7 +2,23 @@ package net.openhft.chronicle.set; import net.openhft.chronicle.hash.HashEntry; +/** + * The present {@link ChronicleSet} entry context. + * + * @param the set key type + * @see SetEntryOperations + * @see SetQueryContext#entry() + */ public interface SetEntry extends HashEntry { @Override SetContext context(); + + /** + * Removes the entry from the {@code ChronicleSet}. + * + *

This method is the default implementation for {@link SetEntryOperations#remove(SetEntry)}, + * which might be customized over the default. + */ + @Override + void doRemove(); } diff --git a/src/main/java/net/openhft/chronicle/set/SetQueryContext.java b/src/main/java/net/openhft/chronicle/set/SetQueryContext.java index 8184d6cb8..4b8a0437b 100644 --- a/src/main/java/net/openhft/chronicle/set/SetQueryContext.java +++ b/src/main/java/net/openhft/chronicle/set/SetQueryContext.java @@ -1,8 +1,21 @@ package net.openhft.chronicle.set; import net.openhft.chronicle.hash.HashQueryContext; +import net.openhft.chronicle.map.ChronicleMap; +import net.openhft.chronicle.map.MapEntryOperations; +import net.openhft.chronicle.map.MapMethods; +import net.openhft.chronicle.map.replication.MapRemoteOperations; +import net.openhft.chronicle.set.replication.SetRemoteOperations; import org.jetbrains.annotations.Nullable; +/** + * The context of {@link ChronicleSet} operations with individual keys + * (most: {@code contains()}, {@code add()}, etc., opposed to bulk operations). + * + * @param the set key type + * @param the return type of {@link SetEntryOperations} specialized for the queried set + * @see ChronicleSet#queryContext(Object) + */ public interface SetQueryContext extends HashQueryContext, SetContext { @Override diff --git a/src/main/java/net/openhft/chronicle/set/replication/SetRemoteQueryContext.java b/src/main/java/net/openhft/chronicle/set/replication/SetRemoteQueryContext.java index df7d02765..ff597e6c0 100644 --- a/src/main/java/net/openhft/chronicle/set/replication/SetRemoteQueryContext.java +++ b/src/main/java/net/openhft/chronicle/set/replication/SetRemoteQueryContext.java @@ -1,9 +1,18 @@ package net.openhft.chronicle.set.replication; import net.openhft.chronicle.hash.replication.HashRemoteQueryContext; +import net.openhft.chronicle.set.ChronicleSet; +import net.openhft.chronicle.set.SetEntryOperations; import net.openhft.chronicle.set.SetQueryContext; import org.jetbrains.annotations.Nullable; +/** + * Context of remote {@link ChronicleSet} queries and internal replication operations. + * + * @param the set key type + * @param the return type of {@link SetEntryOperations} specialized for the queried set + * @see SetRemoteOperations + */ public interface SetRemoteQueryContext extends SetQueryContext, HashRemoteQueryContext { @Override