mirror of
https://github.com/OpenHFT/Chronicle-Map.git
synced 2021-09-13 01:26:12 +00:00
HCOLL-81 renamed ChronicleMap to ChronicleMapOnHeapUpdatableBuilder as Peter wanted the OffHeapUpdated Builder to be the default ChronicleMapBuilder.
This commit is contained in:
@@ -16,64 +16,31 @@
|
||||
|
||||
package net.openhft.chronicle.map;
|
||||
|
||||
import net.openhft.chronicle.hash.ChronicleHashBuilder;
|
||||
import net.openhft.chronicle.hash.serialization.*;
|
||||
import net.openhft.lang.io.Bytes;
|
||||
import net.openhft.lang.io.serialization.BytesMarshallable;
|
||||
import net.openhft.lang.io.serialization.BytesMarshaller;
|
||||
import net.openhft.lang.io.serialization.ObjectFactory;
|
||||
import net.openhft.lang.io.serialization.ObjectSerializer;
|
||||
import net.openhft.lang.model.Byteable;
|
||||
import net.openhft.lang.model.DataValueClasses;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
|
||||
import java.io.Externalizable;
|
||||
import java.io.Serializable;
|
||||
|
||||
|
||||
/**
|
||||
* {@code ChronicleMapBuilder} is intended to be used to configure {@link ChronicleMap}s with
|
||||
* non-{@link Byteable} values, which don't point to off-heap memory directly, including primitives
|
||||
* ({@link Long}, {@link Double}, etc.), {@link String}s and {@link CharSequence}s, values
|
||||
* implementing {@link BytesMarshallable}, {@link Externalizable} or {@link Serializable} interface,
|
||||
* or any other values for which {@linkplain #valueMarshaller(BytesMarshaller) custom marshaller}
|
||||
* is provided.
|
||||
*
|
||||
* <p>Use static {@link #of(Class, Class) of(Key.class, Value.class)} method to obtain
|
||||
* a {@code ChronicleMapBuilder} instance.
|
||||
*
|
||||
* @param <K> key type of the maps, created by this builder
|
||||
* @param <V> value type of the maps, created by this builder
|
||||
* @see OffHeapUpdatableChronicleMapBuilder
|
||||
* @see AbstractChronicleMapBuilder
|
||||
* @see ChronicleHashBuilder
|
||||
*/
|
||||
public final class ChronicleMapBuilder<K, V>
|
||||
extends AbstractChronicleMapBuilder<K, V, ChronicleMapBuilder<K, V>> {
|
||||
|
||||
/**
|
||||
* Returns a new {@code ChronicleMapBuilder} instance which is able to {@linkplain #create()
|
||||
* create} maps with the specified key and value classes.
|
||||
*
|
||||
* <p>{@code ChronicleMapBuilder} analyzes provided key and value classes and automatically
|
||||
* chooses the most specific and effective serializer which it is aware about. Read
|
||||
* <a href="https://github.com/OpenHFT/Chronicle-Map#serialization">the section about
|
||||
* serialization in Chronicle Map manual</a> for more information.
|
||||
*
|
||||
* @param keyClass class object used to infer key type and discover it's properties
|
||||
* via reflection
|
||||
* @param valueClass class object used to infer value type and discover it's properties
|
||||
* via reflection
|
||||
* @param <K> key type of the maps, created by the returned builder
|
||||
* @param <V> value type of the maps, created by the returned builder
|
||||
* @return a new builder for the given key and value classes
|
||||
*/
|
||||
public static <K, V> ChronicleMapBuilder<K, V> of(
|
||||
@NotNull Class<K> keyClass, @NotNull Class<V> valueClass) {
|
||||
if (keyClass.isInterface() && keyClass != CharSequence.class) {
|
||||
keyClass = DataValueClasses.directClassFor(keyClass);
|
||||
}
|
||||
if (valueClass.isInterface()) {
|
||||
valueClass = DataValueClasses.directClassFor(valueClass);
|
||||
} else if (!offHeapReference(valueClass)) {
|
||||
throw new IllegalArgumentException(
|
||||
"Value class should be either Byteable subclass or interface," +
|
||||
"allowing direct Byteable implementation generation");
|
||||
}
|
||||
return new ChronicleMapBuilder<K, V>(keyClass, valueClass);
|
||||
}
|
||||
|
||||
ChronicleMapBuilder(Class<K> keyClass, Class<V> valueClass) {
|
||||
super(keyClass, valueClass);
|
||||
prepareValueBytesOnAcquire(new ZeroOutValueBytes<K, V>(valueSize()));
|
||||
}
|
||||
|
||||
@Override
|
||||
@@ -82,121 +49,52 @@ public final class ChronicleMapBuilder<K, V>
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
* {@inheritDoc} With respect to {@linkplain #entryAndValueAlignment(Alignment) alignment}.
|
||||
*
|
||||
* @see #constantKeySizeBySample(Object)
|
||||
* @see #valueSize(int)
|
||||
* @see #entrySize(int)
|
||||
* <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,
|
||||
* and entry alignment is set to {@link Alignment#OF_4_BYTES}, the actual entry size will be 32
|
||||
* (30 aligned to 4 bytes).
|
||||
*
|
||||
* @see #entryAndValueAlignment(Alignment)
|
||||
* @see #entries(long)
|
||||
*/
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> keySize(int keySize) {
|
||||
return super.keySize(keySize);
|
||||
public ChronicleMapBuilder<K, V> entrySize(int entrySize) {
|
||||
return super.entrySize(entrySize);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
* 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.
|
||||
*
|
||||
* @see #keySize(int)
|
||||
* @see #constantValueSizeBySample(Object)
|
||||
* <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>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>Default is {@link Alignment#OF_4_BYTES} for Byteable values.
|
||||
*
|
||||
* @param alignment the new alignment of the maps constructed by this builder
|
||||
* @return this {@code ChronicleMapOnHeapUpdatableBuilder} back
|
||||
*/
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> constantKeySizeBySample(K sampleKey) {
|
||||
return super.constantKeySizeBySample(sampleKey);
|
||||
public ChronicleMapBuilder<K, V> entryAndValueAlignment(Alignment alignment) {
|
||||
return super.entryAndValueAlignment(alignment);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* {@inheritDoc} Also, it overrides any previous {@link #prepareValueBytesOnAcquire}
|
||||
* configuration to this {@code ChronicleMapBuilder}.
|
||||
*
|
||||
* <p>If value is a boxed primitive type, i. e. if value size is known statically,
|
||||
* it is automatically accounted and shouldn't be specified by user.
|
||||
*
|
||||
* <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
|
||||
* directly.
|
||||
*
|
||||
* @param valueSize number of bytes, taken by serialized form of values
|
||||
* @return this {@code ChronicleMapBuilder} back
|
||||
* @see #constantValueSizeBySample(Object)
|
||||
* @see #keySize(int)
|
||||
* @see #entrySize(int)
|
||||
*/
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> valueSize(int valueSize) {
|
||||
return super.valueSize(valueSize);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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>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>If value size varies, method {@link #valueSize(int)} or {@link #entrySize(int)} should be
|
||||
* called instead of this one.
|
||||
*
|
||||
* @param sampleValue the sample value
|
||||
* @return this builder back
|
||||
* @see #valueSize(int)
|
||||
* @see #constantKeySizeBySample(Object)
|
||||
*/
|
||||
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> constantValueSizeBySample(
|
||||
@NotNull V sampleValue) {
|
||||
return super.constantValueSizeBySample(sampleValue);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*
|
||||
* <p>Example: <pre>{@code Map<Key, Value> map =
|
||||
* ChronicleMapBuilder.of(Key.class, Value.class)
|
||||
* .entries(1_000_000)
|
||||
* .keySize(50).valueSize(200)
|
||||
* // this class hasn't implemented yet, just for example
|
||||
* .objectSerializer(new KryoObjectSerializer())
|
||||
* .create();}</pre>
|
||||
*
|
||||
* <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 #valueMarshaller(BytesMarshaller) value} marshallers are not configured.
|
||||
*/
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> objectSerializer(
|
||||
@NotNull ObjectSerializer objectSerializer) {
|
||||
return super.objectSerializer(objectSerializer);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*
|
||||
* <p>If {@linkplain #valueMarshaller(BytesMarshaller) custom value marshaller} is configured,
|
||||
* this configuration is unused, because it is incapsulated in {@link
|
||||
* BytesMarshaller#read(Bytes)} method (without provided instance to read the data into),
|
||||
* i. e. it's is the user-side responsibility. Actually this is just a convenience method
|
||||
* supporting value marshaller configurations, made initially during {@link #of(Class, Class)}
|
||||
* call, if the value class is {@link BytesMarshallable} or {@link Externalizable} subclass.
|
||||
*
|
||||
* @throws IllegalStateException if custom value marshaller is specified or value class is not
|
||||
* either {@code BytesMarshallable} or {@code Externalizable}
|
||||
*/
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> valueDeserializationFactory(
|
||||
@NotNull ObjectFactory<V> valueDeserializationFactory) {
|
||||
return super.valueDeserializationFactory(valueDeserializationFactory);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*
|
||||
* <p>By default, the default value is set to {@code null}.
|
||||
* <p>By default, the default value is not specified, default {@linkplain
|
||||
* #prepareValueBytesOnAcquire prepare value bytes routine} is specified instead.
|
||||
*
|
||||
* @see #defaultValueProvider(DefaultValueProvider)
|
||||
* @see #prepareValueBytesOnAcquire(PrepareValueBytes)
|
||||
*/
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> defaultValue(V defaultValue) {
|
||||
@@ -204,12 +102,14 @@ public final class ChronicleMapBuilder<K, V>
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
* {@inheritDoc} Also, it overrides any previous {@link #prepareValueBytesOnAcquire}
|
||||
* configuration to this {@code ChronicleMapBuilder}.
|
||||
*
|
||||
* <p>By default, default value provider is not specified, {@link #defaultValue(Object) default
|
||||
* value} is specified instead.
|
||||
* <p>By default, the default value provider is not specified, default {@linkplain
|
||||
* #prepareValueBytesOnAcquire prepare value bytes routine} is specified instead.
|
||||
*
|
||||
* @see #defaultValue(Object)
|
||||
* @see #prepareValueBytesOnAcquire(PrepareValueBytes)
|
||||
*/
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> defaultValueProvider(
|
||||
@@ -218,67 +118,23 @@ public final class ChronicleMapBuilder<K, V>
|
||||
}
|
||||
|
||||
/**
|
||||
* Configures the {@code BytesMarshaller} used to serialize/deserialize values to/from off-heap
|
||||
* memory in maps, created by this builder. See
|
||||
* <a href="https://github.com/OpenHFT/Chronicle-Map#serialization">the
|
||||
* section about serialization in ChronicleMap manual</a> for more information.
|
||||
* Configures the procedure which is called on the bytes, which later the returned value is
|
||||
* pointing to, if the key is absent, on {@link ChronicleMap#acquireUsing(Object, Object)
|
||||
* acquireUsing()} call on maps, created by this builder. See {@link PrepareValueBytes} for
|
||||
* more information.
|
||||
*
|
||||
* @param valueMarshaller the marshaller used to serialize values
|
||||
* <p>The default preparation callback zeroes out the value bytes.
|
||||
*
|
||||
* @param prepareValueBytes what to do with the value bytes before assigning them into the
|
||||
* {@link Byteable} value to return from {@code acquireUsing()} call
|
||||
* @return this builder back
|
||||
* @see #valueMarshallers(BytesWriter, BytesReader)
|
||||
* @see OffHeapUpdatableChronicleMapBuilder
|
||||
* @see #objectSerializer(ObjectSerializer)
|
||||
* @see PrepareValueBytes
|
||||
* @see #defaultValue(Object)
|
||||
* @see #defaultValueProvider(DefaultValueProvider)
|
||||
*/
|
||||
public ChronicleMapBuilder<K, V> valueMarshaller(
|
||||
@NotNull BytesMarshaller<V> valueMarshaller) {
|
||||
valueBuilder.marshaller(valueMarshaller);
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Configures the marshallers, used to serialize/deserialize values to/from off-heap
|
||||
* memory in maps, created by this builder. See
|
||||
* <a href="https://github.com/OpenHFT/Chronicle-Map#serialization">the section about
|
||||
* serialization in ChronicleMap manual</a> for more information.
|
||||
*
|
||||
* <p>Configuring marshalling this way results to a little bit more compact in-memory layout
|
||||
* of the map, comparing to a single interface configuration:
|
||||
* {@link #valueMarshaller(BytesMarshaller)}.
|
||||
*
|
||||
* <p>Passing {@link BytesInterop} instead of plain {@link BytesWriter} is, of cause, possible,
|
||||
* but currently pointless for values.
|
||||
*
|
||||
* @param valueWriter the new value object → {@link Bytes} writer (interop) strategy
|
||||
* @param valueReader the new {@link Bytes} → value object reader strategy
|
||||
* @return this builder back
|
||||
* @see #valueMarshaller(BytesMarshaller)
|
||||
*/
|
||||
public ChronicleMapBuilder<K, V> valueMarshallers(
|
||||
@NotNull BytesWriter<V> valueWriter, @NotNull BytesReader<V> valueReader) {
|
||||
valueBuilder.writer(valueWriter);
|
||||
valueBuilder.reader(valueReader);
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Configures the marshaller used to serialize actual value sizes to off-heap memory in maps,
|
||||
* created by this builder.
|
||||
*
|
||||
* <p>Default value size marshaller is so-called {@linkplain SizeMarshallers#stopBit()
|
||||
* stop bit encoding marshalling}. If {@linkplain #constantValueSizeBySample(Object) constant
|
||||
* value size} is configured, or defaulted if the value type is always constant and {@code
|
||||
* ChronicleHashBuilder} implementation knows about it, this configuration takes no effect,
|
||||
* because a special {@link SizeMarshaller} implementation, which doesn't actually do any
|
||||
* marshalling, and just returns the known constant size on {@link SizeMarshaller#readSize(
|
||||
* Bytes)} calls, is used instead of any {@code SizeMarshaller} configured using this method.
|
||||
*
|
||||
* @param valueSizeMarshaller the new marshaller, used to serialize actual value sizes to
|
||||
* off-heap memory
|
||||
* @return this builder back
|
||||
*/
|
||||
public ChronicleMapBuilder<K, V> valueSizeMarshaller(
|
||||
@NotNull SizeMarshaller valueSizeMarshaller) {
|
||||
valueBuilder.sizeMarshaller(valueSizeMarshaller);
|
||||
return this;
|
||||
@Override
|
||||
public ChronicleMapBuilder<K, V> prepareValueBytesOnAcquire(
|
||||
@NotNull PrepareValueBytes<K, V> prepareValueBytes) {
|
||||
return super.prepareValueBytesOnAcquire(prepareValueBytes);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user