From 6816810b9055d74f0f65e8bd81ad12ae5777f6ae Mon Sep 17 00:00:00 2001
From: Rob Austin {@code AbstractChronicleMapBuilder} and it's subclasses are mutable, see a note in {@link
- * ChronicleHashBuilder} interface documentation. Later in this documentation,
- * "ChronicleMap" means "ChronicleMaps, created by {@code AbstractChronicleMapBuilder}", unless
- * specified different, because theoretically someone might provide {@code ChronicleMap}
- * implementations with completely different properties. {@code ChronicleMap}
- * ("ChronicleMaps, created by {@code AbstractChronicleMapBuilder}") currently doesn't support
- * resizing. That is why you should always configure {@linkplain #entries(long) number of
- * entries} you are going to insert into the created map at most. See {@link #entries(long)}
- * method documentation for more information on this. {@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 on this. {@code
* ChronicleMap
- * one of concrete {@code AbstractChronicleMapBuilder} subclasses, {@link ChronicleMapBuilder} or
- * {@link OffHeapUpdatableChronicleMapBuilder}, could be prepared and used to create many similar
+ * one of concrete {@code AbstractChronicleMapBuilder} subclasses, {@link ChronicleMapBuilder} or {@link
+ * OffHeapUpdatableChronicleMapBuilder}, could be prepared and used to create many similar
* maps: {@code
* OffHeapUpdatableChronicleMapBuilder
Later in this documentation, "ChronicleMap" means + * "ChronicleMaps, created by {@code AbstractChronicleMapBuilder}", unless specified different, because + * theoretically someone might provide {@code ChronicleMap} implementations with completely different + * properties.
{@code ChronicleMap} ("ChronicleMaps, created by {@code AbstractChronicleMapBuilder}") + * currently doesn't support resizing. That is why you should always configure {@linkplain + * #entries(long) number of entries} you are going to insert into the created map at most. See {@link + * #entries(long)} method documentation for more information on this.
{@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 on this.
* * @paramIf 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.
+ * recommended always to configure {@linkplain #keySize(int) key size} and {@linkplain #valueSize(int) + * value size}, if they couldn't be derived statically.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.
* * @see #entries(long) */ @@ -468,20 +467,18 @@ public abstract class AbstractChronicleMapBuilderBy default, of cause, {@code ChronicleMap} - * conforms the general {@code Map} contract and returns the previous mapped value on {@code - * put()} calls.
+ *{@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.
By default, of cause, {@code ChronicleMap} conforms the general {@code Map} contract + * and returns the previous mapped value on {@code put()} calls.
* * @param putReturnsNull {@code true} if you want {@link ChronicleMap#put(Object, Object) - * ChronicleMap.put()} to not return the value that was replaced but - * instead return {@code null} + * ChronicleMap.put()} to not return the value that was replaced but instead return + * {@code null} * @return an instance of the map builder back * @see #removeReturnsNull(boolean) */ @@ -495,17 +492,17 @@ public abstract class AbstractChronicleMapBuilder{@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 something you probably + * don't use.
* * @param removeReturnsNull {@code true} if you want {@link ChronicleMap#remove(Object) - * ChronicleMap.remove()} to not return the value of the removed entry - * but instead return {@code null} + * ChronicleMap.remove()} to not return the value of the removed entry but + * instead return {@code null} * @return an instance of the map builder back * @see #putReturnsNull(boolean) */ @@ -650,19 +647,18 @@ public abstract class AbstractChronicleMapBuilderDefault value deserialization factory is {@link NewInstanceObjectFactory}, which creates a new value + * instance using {@link Class#newInstance()} default constructor. You could provide an {@link + * AllocateInstanceObjectFactory}, which uses {@code Unsafe.allocateInstance(Class)} (you might want to do + * this for better performance or if you don't want to initialize fields), or a factory which calls a + * value class constructor with some arguments, or a factory which internally delegates to instance pool + * or {@link ThreadLocal}, to reduce allocations.
* - * @param valueDeserializationFactory the value factory used to produce instances to deserialize - * data in + * @param valueDeserializationFactory the value factory used to produce instances to deserialize data in * @return this builder back */ public B valueDeserializationFactory(@NotNull ObjectFactoryThis configuration overrides any previous {@link #defaultValue(Object)} configuration to this {@code + * AbstractChronicleMapBuilder}.
* * @param defaultValueProvider the strategy to obtain a default value by the absent key * @return this builder object back @@ -754,6 +750,13 @@ public abstract class AbstractChronicleMapBuilder(Note that 10 is chosen as key size in bytes despite strings in Java are UTF-16 encoded - * (and each character takes 2 bytes on-heap), because default off-heap {@link String} encoding - * is UTF-8 in {@code ChronicleSet}.) + *
(Note that 10 is chosen as key size in bytes despite strings in Java are UTF-16 encoded (and each
+ * character takes 2 bytes on-heap), because default off-heap {@link String} encoding is UTF-8 in {@code
+ * ChronicleSet}.)
*
* @see #constantKeySizeBySample(Object)
* @see #entrySize(int)
@@ -136,13 +139,13 @@ public class ChronicleSetBuilder In fully default case you can expect entry size to be about 120-130 bytes. But it is
- * strongly recommended always to configure {@linkplain #keySize(int) key size}, if they
- * couldn't be derived statically.
+ * In fully default case you can expect entry size to be about 120-130 bytes. But it is strongly
+ * recommended always to configure {@linkplain #keySize(int) key size}, if they couldn't be derived
+ * statically.
*
* 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 a few bytes required by implementations.
+ * {@linkplain #metaDataBytes(int) meta data bytes}, plus {@linkplain #keySize(int) key size}, plus a few
+ * bytes required by implementations.
*/
@Override
public ChronicleSetBuilder Actually this is just a convenience method supporting key marshaller configurations, made
- * initially during {@link #of(Class)} call. Because if you {@linkplain
- * #keyMarshaller(BytesMarshaller) configure} own custom key marshaller, this method doesn't
- * take any effect on the maps constructed by this builder.
+ * Actually this is just a convenience method supporting key marshaller configurations, made initially
+ * during {@link #of(Class)} call. Because if you {@linkplain #keyMarshaller(BytesMarshaller) configure}
+ * own custom key marshaller, this method doesn't take any effect on the maps constructed by this
+ * builder.
*
* @see #of(Class)
*/
@@ -277,6 +280,12 @@ public class ChronicleSetBuilder