Alawn/Chronicle-Map
1
0
Fork 0
mirror of https://github.com/OpenHFT/Chronicle-Map.git synced 2021-09-13 01:26:12 +00:00
Code Releases Activity

Fixed Javadoc errors for Java 8

Browse Source
This commit is contained in:
Peter Lawrey
2014-10-24 11:48:51 +01:00
parent ea779997cf
commit 9ace610ca5
12 changed files with 84 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/main/java/net/openhft/chronicle/common/ChronicleHash.java
+1 -1
View File
@@ -37,7 +37,7 @@ public interface ChronicleHash extends Closeable {
*
* @return the file this {@link ChronicleMap} or {@link ChronicleSet} is mapped to,
* or {@code null} if it is not mapped to any file
* @see ChronicleHashBuilder#create(File)
* @see ChronicleHashBuilder#file(java.io.File)
* @see ChronicleHashBuilder#create()
*/
File file();
src/main/java/net/openhft/chronicle/common/ChronicleHashBuilder.java
+1
View File
@@ -390,6 +390,7 @@ public interface ChronicleHashBuilder<K, C extends ChronicleHash,
* @param file the file with existing hash container or a desired location of a new off-heap
* persisted hash container
* @return this builder back
* @throws IOException If the file cannot be created and read.
* @see ChronicleHash#file()
* @see ChronicleHash#close()
*/
src/main/java/net/openhft/chronicle/common/serialization/BytesInterop.java
+1 -1
View File
@@ -25,7 +25,7 @@ import net.openhft.lang.model.Byteable;
* Marshaller for byte sequences, which are copied to off-heap {@link Bytes}
* in a very straightforward manner, e. g. {@link Byteable Byteables}, {@code byte[]} arrays,
* {@code Bytes} themselves. The criterion of this interface applicability --
* {@link #equals} implementation shouldn't require deserialization and any garbage creation.
* {@link Object#equals(Object)} implementation shouldn't require deserialization and any garbage creation.
*
* @param <E> type of marshalled objects
*/
src/main/java/net/openhft/chronicle/map/ChannelProvider.java
+1
View File
@@ -211,6 +211,7 @@ public final class ChannelProvider implements Closeable {
* per channel could be obtained from a single {@code ReplicatingChannel}. The returned replicator could
* be applied to a map at most once.
*
* @param channel number to create
* @return a replicator, dedicated to the specified channel
*/
public ChronicleChannel createChannel(short channel) {
src/main/java/net/openhft/chronicle/map/ChronicleMapBuilder.java
+26 -26
View File
@@ -63,21 +63,21 @@ import static net.openhft.chronicle.map.Objects.builderEquals;
* ChronicleMap<Key, Value> map1 = builder.create();
* ChronicleMap<Key, Value> map2 = builder.create();}</pre>
* i. e. created {@code ChronicleMap} instances don't depend on the builder.
* <p/>
*
* <p>Use static {@link #of(Class, Class)} method to obtain a {@code ChronicleMapBuilder} instance.
* <p/>
*
* <p>{@code ChronicleMapBuilder} is mutable, see a note in {@link net.openhft.chronicle.common.ChronicleHashBuilder}
* interface documentation.
* <p/>
*
* <p>Later in this documentation, "ChronicleMap" means "ChronicleMaps, created by {@code
* ChronicleMapBuilder}", unless specified different, because theoretically someone might provide
* {@code ChronicleMap} implementations with completely different properties.
* <p/>
*
* <p>{@code ChronicleMap} ("ChronicleMaps, created by {@code ChronicleMapBuilder}") currently
* doesn't support resizing. That is why you should <i>always</i> configure {@linkplain
* #entries(long) number of entries} you are going to insert into the created map <i>at most</i>.
* See {@link #entries(long)} method documentation for more information on this.
* <p/>
*
* <p>{@code ChronicleMap} allocates memory by equally sized chunks. This size is called {@linkplain
* #entrySize(int) entry size}, you are strongly recommended to configure it to achieve least memory
* consumption and best speed. See {@link #entrySize(int)} method documentation for more information
@@ -187,7 +187,7 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
/**
* {@inheritDoc}
* <p/>
*
* <p>Example: if keys in your map(s) are English words in {@link String} form, keys size 10
* (a bit more than average English word length) would be a good choice: <pre>{@code
* ChronicleMap<String, LongValue> wordFrequencies = ChronicleMapBuilder
@@ -214,7 +214,7 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
/**
* {@inheritDoc}
* <p/>
*
* <p>For example, if your keys are Git commit hashes:<pre>{@code
* Map<byte[], String> gitCommitMessagesByHash =
* ChronicleMapBuilder.of(byte[].class, String.class)
@@ -238,10 +238,10 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
* Configures the optimal number of bytes, taken by serialized form of values, put into maps,
* created by this builder. If value size is always the same, call {@link
* #constantValueSizeBySample(Object)} method instead of this one.
* <p/>
*
* <p>If value is a boxed primitive type or {@link Byteable} subclass, i. e. if value size is
* known statically, it is automatically accounted and shouldn't be specified by user.
* <p/>
*
* <p>If value size varies moderately, specify the size higher than average, but lower than the
* maximum possible, to minimize average memory overuse. If value size varies in a wide range,
* it's better to use {@linkplain #entrySize(int) entry size} in "chunk" mode and configure it
@@ -263,10 +263,10 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
* Configures the constant number of bytes, taken by serialized form of values, put into maps,
* created by this builder. This is done by providing the {@code sampleValue}, all values should
* take the same number of bytes in serialized form, as this sample object.
* <p/>
*
* <p>If values are of boxed primitive type or {@link Byteable} subclass, i. e. if value size is
* known statically, it is automatically accounted and this method shouldn't be called.
* <p/>
*
* <p>If value size varies, method {@link #valueSize(int)} or {@link #entrySize(int)} should be
* called instead of this one.
*
@@ -295,16 +295,16 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
/**
* {@inheritDoc}
* <p/>
*
* <p>In fully default case you can expect entry size to be about 256 bytes. But it is strongly
* recommended always to configure {@linkplain #keySize(int) key size} and {@linkplain
* #valueSize(int) value size}, if they couldn't be derived statically.
* <p/>
*
* <p>If entry size is not configured explicitly by calling this method, it is computed based on
* {@linkplain #metaDataBytes(int) meta data bytes}, plus {@linkplain #keySize(int) key size},
* plus {@linkplain #valueSize(int) value size}, plus a few bytes required by implementations,
* with respect to {@linkplain #entryAndValueAlignment(Alignment) alignment}.
* <p/>
*
* <p>Note that the actual entrySize will be aligned to 4 (default {@linkplain
* #entryAndValueAlignment(Alignment) entry alignment}). I. e. if you set entry size to 30, the
* actual entry size will be 32 (30 aligned to 4 bytes). If you don't want entry size to be
@@ -352,15 +352,15 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
/**
* Configures alignment strategy of address in memory of entries and independently of address in
* memory of values within entries in ChronicleMaps, created by this builder.
* <p/>
*
* <p>Useful when values of the map are updated intensively, particularly fields with volatile
* access, because it doesn't work well if the value crosses cache lines. Also, on some
* (nowadays rare) architectures any misaligned memory access is more expensive than aligned.
* <p/>
*
* <p>Note that {@linkplain #entrySize(int) entry size} will be aligned according to this
* alignment. I. e. if you set {@code entrySize(20)} and {@link Alignment#OF_8_BYTES}, actual
* entry size will be 24 (20 aligned to 8 bytes).
* <p/>
*
* <p>Default is {@link Alignment#OF_4_BYTES}.
*
* @param alignment the new alignment of the maps constructed by this builder
@@ -449,12 +449,12 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
* Configures if the maps created by this builder should return {@code null} instead of previous
* mapped values on {@link ChronicleMap#put(Object, Object) ChornicleMap.put(key, value)}
* calls.
* <p/>
*
* <p>{@link Map#put(Object, Object) Map.put()} returns the previous value, functionality which
* is rarely used but fairly cheap for {@link HashMap}. In the case, for an off heap collection,
* it has to create a new object and deserialize the data from off-heap memory. It's expensive
* for something you probably don't use.
* <p/>
*
* <p>By default, of cause, {@code ChronicleMap} conforms the general {@code Map} contract and
* returns the previous mapped value on {@code put()} calls.
*
@@ -476,7 +476,7 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
/**
* Configures if the maps created by this builder should return {@code null} instead of the last
* mapped value on {@link ChronicleMap#remove(Object) ChronicleMap.remove(key)} calls.
* <p/>
*
* <p>{@link Map#remove(Object) Map.remove()} returns the previous value, functionality which is
* rarely used but fairly cheap for {@link HashMap}. In the case, for an off heap collection, it
* has to create a new object and deserialize the data from off-heap memory. It's expensive for
@@ -637,7 +637,7 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
/**
* {@inheritDoc}
* <p/>
*
* <p>Example: <pre>{@code Map<Key, Value> map =
* ChronicleMapBuilder.of(Key.class, Value.class)
* .entries(1_000_000)
@@ -645,7 +645,7 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
* // this class hasn't implemented yet, just for example
* .objectSerializer(new KryoObjectSerializer())
* .create();}</pre>
* <p/>
*
* <p>This serializer is used to serialize both keys and values, if they both require this:
* loosely typed, nullable, and custom {@linkplain #keyMarshaller(BytesMarshaller) key} and
* {@linkplain #valueMarshallerAndFactory(BytesMarshaller, ObjectFactory) value} marshallers are
@@ -660,7 +660,7 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
/**
* {@inheritDoc}
* <p/>
*
* <p>Example:
*/
@Override
@@ -719,10 +719,10 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
* Specifies the value to be put for each key queried in {@link ChronicleMap#get get()} and
* {@link ChronicleMap#getUsing(Object, Object) getUsing()} methods, if the key is absent in the
* map. Then this default value is returned from query method.
* <p/>
*
* <p>Setting default value to {@code null} is interpreted as map shouldn't put any default
* value for absent keys. This is by default.
* <p/>
*
* <p>This configuration overrides any previous {@link #defaultValueProvider(DefaultValueProvider)}
* configuration to this {@code ChronicleMapBuilder}.
*
@@ -741,7 +741,7 @@ public class ChronicleMapBuilder<K, V> implements Cloneable,
* and {@link ChronicleMap#getUsing(Object, Object) getUsing()} calls, if the key is absent in
* the map. If the obtained value is non-null, it is put for the key in the map and then
* returned from current {@code get()} or {@code getUsing()} call.
* <p/>
*
* <p>This configuration overrides any previous {@link #defaultValue(Object)} configuration to
* this {@code ChronicleMapBuilder}.
*
src/main/java/net/openhft/chronicle/map/Replica.java
+2 -2
View File
@@ -58,7 +58,7 @@ public interface Replica extends Closeable {
/**
* Returns the timestamp of the last change from the specified remote node, already replicated to this
* Replica. <p/> <p>Used in conjunction with replication, to back fill data from a remote node. This node
* Replica. <p>Used in conjunction with replication, to back fill data from a remote node. This node
* may have missed updates while it was not been running or connected via TCP.
*
* @param remoteIdentifier the identifier of the remote node to check last replicated update time from
@@ -110,7 +110,7 @@ public interface Replica extends Closeable {
/**
* Dirties all entries with a modification time equal to {@code fromTimeStamp} or newer. It means all
* these entries will be considered as "new" by this ModificationIterator and iterated once again no
* matter if they have already been. <p/> <p>This functionality is used to publish recently modified
* matter if they have already been. <p>This functionality is used to publish recently modified
* entries to a new remote node as it connects.
*
* @param fromTimeStamp the timestamp from which all entries should be dirty
src/main/java/net/openhft/chronicle/map/ReplicatedChronicleMap.java
+21 -12
View File
@@ -44,7 +44,8 @@ import static net.openhft.chronicle.common.serialization.Hasher.hash;
import static net.openhft.lang.collection.DirectBitSet.NOT_FOUND;
/**
* A Replicating Multi Master HashMap <p/> <p>Each remote hash map, mirrors its changes over to
* <h2>A Replicating Multi Master HashMap</h2>
* <p>Each remote hash map, mirrors its changes over to
* another remote hash map, neither hash map is considered the master store of data, each hash map
* uses timestamps to reconcile changes. We refer to an instance of a remote hash-map as a node. A
* node will be connected to any number of other nodes, for the first implementation the maximum
@@ -56,8 +57,10 @@ import static net.openhft.lang.collection.DirectBitSet.NOT_FOUND;
* nature of this multi master implementation, this return value will only be the old value on the
* nodes local data store. In other words the nodes are only concurrent locally. Its worth realising
* that another node performing exactly the same operation may return a different value. However
* reconciliation will ensure the maps themselves become eventually consistent. <p/>
* <p>Reconciliation <p/> <p>If two ( or more nodes ) were to receive a change to their maps for the
* reconciliation will ensure the maps themselves become eventually consistent.
* </p>
* <h2>Reconciliation </h2>
* <p>If two ( or more nodes ) were to receive a change to their maps for the
* same key but different values, say by a user of the maps, calling the put(key, value). Then,
* initially each node will update its local store and each local store will hold a different value,
* but the aim of multi master replication is to provide eventual consistency across the nodes. So,
@@ -67,7 +70,8 @@ import static net.openhft.lang.collection.DirectBitSet.NOT_FOUND;
* and value. Eventual consistency is achieved by looking at the timestamp from the remote node, if
* for a given key, the remote nodes timestamp is newer than the local nodes timestamp, then the
* event from the remote node will be applied to the local node, otherwise the event will be
* ignored. <p/> <p>However there is an edge case that we have to concern ourselves with, If two
* ignored. </p>
* <p>However there is an edge case that we have to concern ourselves with, If two
* nodes update their map at the same time with different values, we have to deterministically
* resolve which update wins, because of eventual consistency both nodes should end up locally
* holding the same data. Although it is rare two remote nodes could receive an update to their maps
@@ -77,6 +81,7 @@ import static net.openhft.lang.collection.DirectBitSet.NOT_FOUND;
* made to one node should be identical to the decision made to the other. We resolve this simple
* dilemma by using a node identifier, each node will have a unique identifier, the update from the
* node with the smallest identifier wins.
* </p>
*
* @param <K> the entries key type
* @param <V> the entries value type
@@ -865,7 +870,7 @@ class ReplicatedChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
/**
* Used only with replication, its sometimes possible to receive an old ( or stale update )
* from a remote map. This method is used to determine if we should ignore such updates.
* <p/> <p>We can reject put() and removes() when comparing times stamps with remote
* <p>We can reject put() and removes() when comparing times stamps with remote
* systems
*
* @param entry the maps entry
@@ -1339,15 +1344,18 @@ class ReplicatedChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
}
/**
* Once a change occurs to a map, map replication requires that these changes are picked up by
* another thread, this class provides an iterator like interface to poll for such changes. <p/>
* <p>Once a change occurs to a map, map replication requires that these changes are picked up by
* another thread, this class provides an iterator like interface to poll for such changes.
* </p>
* <p>In most cases the thread that adds data to the node is unlikely to be the same thread that
* replicates the data over to the other nodes, so data will have to be marshaled between the
* main thread storing data to the map, and the thread running the replication. <p/> <p>One way
* to perform this marshalling, would be to pipe the data into a queue. However, This class
* main thread storing data to the map, and the thread running the replication.
* </p>
* <p>One way to perform this marshalling, would be to pipe the data into a queue. However, This class
* takes another approach. It uses a bit set, and marks bits which correspond to the indexes of
* the entries that have changed. It then provides an iterator like interface to poll for such
* changes.
* </p>
*
* @author Rob Austin.
*/
@@ -1543,7 +1551,7 @@ abstract class Replicator {
/**
* Applies the replicator to the map instance and returns a Closeable token to manage resources,
* associated with the replication. <p/> <p>This method isn't intended to be called from the
* associated with the replication. <p>This method isn't intended to be called from the
* client code.
*
* @param builder the builder from which the map was constructed. The replicator may
@@ -1552,7 +1560,7 @@ abstract class Replicator {
* @param map a replicated map instance. Provides basic tools for replication
* implementation.
* @param entryExternalizable the callback for ser/deser implementation in the replicator
* @param chronicleMap
* @param chronicleMap to wrap.
* @return a {@code Closeable} token to control replication resources. It should be closed on
* closing the replicated map.
* @throws java.io.IOException if an io error occurred during the replicator setup
@@ -1562,7 +1570,8 @@ abstract class Replicator {
* maps)
*/
protected abstract Closeable applyTo(ChronicleMapBuilder builder,
Replica map, Replica.EntryExternalizable entryExternalizable, final ChronicleMap chronicleMap)
Replica map, Replica.EntryExternalizable entryExternalizable,
final ChronicleMap chronicleMap)
throws IOException;
}
src/main/java/net/openhft/chronicle/map/TcpReplicator.java
+1 -1
View File
@@ -41,7 +41,7 @@ import static net.openhft.chronicle.map.StatelessChronicleMap.EventId.HEARTBEAT;
/**
* Used with a {@see net.openhft.map.ReplicatedSharedHashMap} to send data between the maps using a
* socket connection <p/> {@see net.openhft.map.OutSocketReplicator}
* socket connection {@see net.openhft.map.OutSocketReplicator}
*
* @author Rob Austin.
*/
src/main/java/net/openhft/chronicle/map/ThrottlingConfig.java
+1 -1
View File
@@ -108,7 +108,7 @@ public class ThrottlingConfig {
/**
* Returns the throttle bucketing interval in the given time units. <p/> <p>Default throttle bucketing
* Returns the throttle bucketing interval in the given time units. <p>Default throttle bucketing
* interval is 100 millis.
*
* @param unit the time unit of the interval
src/main/java/net/openhft/chronicle/map/VanillaChronicleMap.java
+5 -5
View File
@@ -715,10 +715,10 @@ class VanillaChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
}
/**
* Used to acquire an object of type V from the Segment. <p/> {@code usingValue} is reused to read the
* value if key is present in this Segment, if key is absent in this Segment: <p/> <ol><li>If {@code
* Used to acquire an object of type V from the Segment. {@code usingValue} is reused to read the
* value if key is present in this Segment, if key is absent in this Segment: <ol><li>If {@code
* create == false}, just {@code null} is returned (except when event listener provides a value "on
* get missing" - then it is put into this Segment for the key).</li> <p/> <li>If {@code create ==
* get missing" - then it is put into this Segment for the key).</li> <li>If {@code create ==
* true}, {@code usingValue} or a newly created instance of value class, if {@code usingValue ==
* null}, is put into this Segment for the key.</li></ol>
*
@@ -999,7 +999,7 @@ class VanillaChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
/**
* Removes a key (or key-value pair) from the Segment.
* <p/>
*
* <p>The entry will only be removed if {@code expectedValue} equals to {@code null}
* or the value previously corresponding to the specified key.
*
@@ -1061,7 +1061,7 @@ class VanillaChronicleMap<K, KI, MKI extends MetaBytesInterop<K, KI>,
}
/**
* Replaces the specified value for the key with the given value. <p/> {@code newValue} is set only if
* Replaces the specified value for the key with the given value. {@code newValue} is set only if
* the existing value corresponding to the specified key is equal to {@code expectedValue} or {@code
* expectedValue == null}.
*