{@code
* ChronicleMap map = ChronicleMapBuilder
* .of(Key.class, Value.class)
* .entries(100500)
* // ... other configurations
* .create();}
- * 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 builder = OffHeapUpdatableChronicleMapBuilder
* .of(Key.class, Value.class)
@@ -69,22 +69,18 @@ import static net.openhft.chronicle.map.Objects.builderEquals;
* ChronicleMap map2 = builder.create();}
* i. e. created {@code ChronicleMap} instances don't depend on the builder.
*
- * {@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 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.
* * @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 + *
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.
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) @@ -457,19 +455,20 @@ 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} + * @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} * @return an instance of the map builder back * @see #removeReturnsNull(boolean) */ @@ -483,16 +482,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} + * @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} * @return an instance of the map builder back * @see #putReturnsNull(boolean) */ @@ -667,18 +667,19 @@ 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 #defaultValueProvider(DefaultValueProvider)} + * configuration to this {@code AbstractChronicleMapBuilder}.
* - * @param defaultValue the default value to be put to the map for absent keys during {@code acquireUsing()} calls + * @param defaultValue the default value to be put to the map for absent keys during {@code + * acquireUsing()} calls * @return this builder object back */ public B defaultValue(V defaultValue) { @@ -716,12 +717,11 @@ public abstract class AbstractChronicleMapBuilderThis 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 @@ -831,19 +831,9 @@ public abstract class AbstractChronicleMapBuilder