K
- key type of the maps, created by this builderV
- value type of the maps, created by this builderpublic final class ChronicleMapBuilder<K,V> extends AbstractChronicleMapBuilder<K,V,ChronicleMapBuilder<K,V>>
ChronicleMapBuilder
is intended to be used to configure ChronicleMap
s with
non-Byteable
values, which don't point to off-heap memory directly, including primitives
(Long
, Double
, etc.), String
s and CharSequence
s, values
implementing BytesMarshallable
, Externalizable
or Serializable
interface,
or any other values for which custom marshaller
is provided.
Use static of(Key.class, Value.class)
method to obtain
a ChronicleMapBuilder
instance.
Modifier and Type | Method and Description |
---|---|
ChronicleMapBuilder<K,V> |
constantKeySizeBySample(K sampleKey)
Configures the constant number of bytes, taken by serialized form of keys, put into hash
containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
constantValueSizeBySample(V sampleValue)
Configures the constant number of bytes, taken by serialized form of values, put into maps,
created by this builder.
|
ChronicleMapBuilder<K,V> |
defaultValue(V defaultValue)
Specifies the value to be put for each key queried in
acquireUsing()
method, if the key is absent in the map, created by this builder. |
ChronicleMapBuilder<K,V> |
defaultValueProvider(DefaultValueProvider<K,V> defaultValueProvider)
Specifies the function to obtain a value for the key during
acquireUsing() calls, if the key is absent in the map, created by this builder. |
ChronicleMapBuilder<K,V> |
keySize(int keySize)
Configures the optimal number of bytes, taken by serialized form of keys, put into hash
containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
objectSerializer(ObjectSerializer objectSerializer)
Configures the serializer used to serialize/deserialize data to/from off-heap memory, when
specified class doesn't implement a specific serialization interface like
Externalizable or BytesMarshallable (for example, if data is loosely typed and just
Object is specified as the data class), or nullable data, and if custom marshaller is
not configured, in hash containers, created by
this builder. |
static <K,V> ChronicleMapBuilder<K,V> |
of(Class<K> keyClass,
Class<V> valueClass)
Returns a new
ChronicleMapBuilder instance which is able to create maps with the specified key and value classes. |
ChronicleMapBuilder<K,V> |
valueDeserializationFactory(ObjectFactory<V> valueDeserializationFactory)
Configures factory which is used to create a new value instance, if value class is either
Byteable , BytesMarshallable or Externalizable subclass in maps, created by this
builder. |
ChronicleMapBuilder<K,V> |
valueMarshaller(BytesMarshaller<V> valueMarshaller)
Configures the
BytesMarshaller used to serialize/deserialize values to/from off-heap
memory in maps, created by this builder. |
ChronicleMapBuilder<K,V> |
valueMarshallers(BytesWriter<V> valueWriter,
BytesReader<V> valueReader)
Configures the marshallers, used to serialize/deserialize values to/from off-heap
memory in maps, created by this builder.
|
ChronicleMapBuilder<K,V> |
valueSize(int valueSize)
Configures the optimal number of bytes, taken by serialized form of values, put into maps,
created by this builder.
|
ChronicleMapBuilder<K,V> |
valueSizeMarshaller(SizeMarshaller valueSizeMarshaller)
Configures the marshaller used to serialize actual value sizes to off-heap memory in maps,
created by this builder.
|
actualEntriesPerSegment, actualSegments, bytesMarshallerFactory, clone, create, createPersistedTo, entries, entrySize, equals, errorListener, eventListener, hashCode, immutableKeys, instance, keyDeserializationFactory, keyMarshaller, keyMarshallers, keySizeMarshaller, lockTimeOut, metaDataBytes, minSegments, offHeapReference, putReturnsNull, removeReturnsNull, replication, replication, replication, statelessClient, timeProvider, toString
public static <K,V> ChronicleMapBuilder<K,V> of(@NotNull Class<K> keyClass, @NotNull Class<V> valueClass)
ChronicleMapBuilder
instance which is able to create maps with the specified key and value classes.
ChronicleMapBuilder
analyzes provided key and value classes and automatically
chooses the most specific and effective serializer which it is aware about. Read
the section about
serialization in Chronicle Map manual for more information.
K
- key type of the maps, created by the returned builderV
- value type of the maps, created by the returned builderkeyClass
- class object used to infer key type and discover it's properties
via reflectionvalueClass
- class object used to infer value type and discover it's properties
via reflectionpublic ChronicleMapBuilder<K,V> keySize(int keySize)
ChronicleHashBuilder.constantKeySizeBySample(Object)
method instead of this one.
If key size varies moderately, specify the size higher than average, but lower than the maximum possible, to minimize average memory overuse. If key size varies in a wide range, it's better to use entry size in "chunk" mode and configure it directly.
Example: if keys in your map(s) are English words in String
form, keys size 10
(a bit more than average English word length) would be a good choice:
ChronicleMap<String, LongValue> wordFrequencies = OffHeapUpdatableChronicleMapBuilder
.of(String.class, LongValue.class)
.entries(50000)
.keySize(10)
// shouldn't specify valueSize(), because it is statically known
.create();
(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 String
encoding is UTF-8 in ChronicleMap
.)keySize
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
keySize
in class AbstractChronicleMapBuilder<K,V,ChronicleMapBuilder<K,V>>
keySize
- number of bytes, taken by serialized form of keysconstantKeySizeBySample(Object)
,
valueSize(int)
,
AbstractChronicleMapBuilder.entrySize(int)
public ChronicleMapBuilder<K,V> constantKeySizeBySample(K sampleKey)
sampleKey
, all
keys should take the same number of bytes in serialized form, as this sample object.
If keys are of boxed primitive type or Byteable
subclass, i. e. if key size is
known statically, it is automatically accounted and this method shouldn't be called.
If key size varies, method ChronicleHashBuilder.keySize(int)
or ChronicleHashBuilder.entrySize(int)
should be
called instead of this one.
For example, if your keys are Git commit hashes:
Map<byte[], String> gitCommitMessagesByHash =
ChronicleMapBuilder.of(byte[].class, String.class)
.constantKeySizeBySample(new byte[20])
.create();
constantKeySizeBySample
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
constantKeySizeBySample
in class AbstractChronicleMapBuilder<K,V,ChronicleMapBuilder<K,V>>
sampleKey
- the sample keykeySize(int)
,
constantValueSizeBySample(Object)
public ChronicleMapBuilder<K,V> valueSize(int valueSize)
constantValueSizeBySample(Object)
method instead of this one.
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.
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 entry size in "chunk" mode and configure it directly.
valueSize
- number of bytes, taken by serialized form of valuesChronicleMapBuilder
backconstantValueSizeBySample(Object)
,
keySize(int)
,
AbstractChronicleMapBuilder.entrySize(int)
public ChronicleMapBuilder<K,V> constantValueSizeBySample(@NotNull V sampleValue)
sampleValue
, all values should
take the same number of bytes in serialized form, as this sample object.
If values are of boxed primitive type or Byteable
subclass, i. e. if value size is
known statically, it is automatically accounted and this method shouldn't be called.
If value size varies, method valueSize(int)
or AbstractChronicleMapBuilder.entrySize(int)
should be
called instead of this one.
sampleValue
- the sample valuevalueSize(int)
,
constantKeySizeBySample(Object)
public ChronicleMapBuilder<K,V> objectSerializer(@NotNull ObjectSerializer objectSerializer)
Externalizable
or BytesMarshallable
(for example, if data is loosely typed and just
Object
is specified as the data class), or nullable data, and if custom marshaller is
not configured, in hash containers, created by
this builder. Please read ObjectSerializer
docs for more info and available options.
Default serializer is BytesMarshallableSerializer
, configured with the specified
or default BytesMarshallerFactory
.
Example:
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();
This serializer is used to serialize both keys and values, if they both require this: loosely typed, nullable, and custom key and value marshallers are not configured.
objectSerializer
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
objectSerializer
in class AbstractChronicleMapBuilder<K,V,ChronicleMapBuilder<K,V>>
objectSerializer
- the serializer used to serialize loosely typed or nullable data if
custom marshaller is not configuredChronicleHashBuilder.bytesMarshallerFactory(BytesMarshallerFactory)
,
ChronicleHashBuilder.keyMarshaller(BytesMarshaller)
public ChronicleMapBuilder<K,V> valueDeserializationFactory(@NotNull ObjectFactory<V> valueDeserializationFactory)
Byteable
, BytesMarshallable
or Externalizable
subclass in maps, created by this
builder.
Default value deserialization factory is NewInstanceObjectFactory
, which creates a new value
instance using Class.newInstance()
default constructor. You could provide an AllocateInstanceObjectFactory
, which uses 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 ThreadLocal
, to reduce allocations.
If custom value marshaller is configured,
this configuration is unused, because it is incapsulated in 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 of(Class, Class)
call, if the value class is BytesMarshallable
or Externalizable
subclass.
valueDeserializationFactory
in class AbstractChronicleMapBuilder<K,V,ChronicleMapBuilder<K,V>>
valueDeserializationFactory
- the value factory used to produce instances to deserialize data inIllegalStateException
- if custom value marshaller is specified or value class is not
either BytesMarshallable
or Externalizable
public ChronicleMapBuilder<K,V> defaultValue(V defaultValue)
acquireUsing()
method, if the key is absent in the map, created by this builder.
This configuration overrides any previous AbstractChronicleMapBuilder.defaultValueProvider(DefaultValueProvider)
configuration to this AbstractChronicleMapBuilder
.
By default, the default value is set to null
.
defaultValue
in class AbstractChronicleMapBuilder<K,V,ChronicleMapBuilder<K,V>>
defaultValue
- the default value to be put to the map for absent keys during acquireUsing()
callsdefaultValueProvider(DefaultValueProvider)
public ChronicleMapBuilder<K,V> defaultValueProvider(@NotNull DefaultValueProvider<K,V> defaultValueProvider)
acquireUsing()
calls, if the key is absent in the map, created by this builder.
This configuration overrides any previous AbstractChronicleMapBuilder.defaultValue(Object)
configuration to this AbstractChronicleMapBuilder
.
By default, default value provider is not specified, default
value
is specified instead.
defaultValueProvider
in class AbstractChronicleMapBuilder<K,V,ChronicleMapBuilder<K,V>>
defaultValueProvider
- the strategy to obtain a default value by the absent keydefaultValue(Object)
public ChronicleMapBuilder<K,V> valueMarshaller(@NotNull BytesMarshaller<V> valueMarshaller)
BytesMarshaller
used to serialize/deserialize values to/from off-heap
memory in maps, created by this builder. See
the
section about serialization in ChronicleMap manual for more information.valueMarshaller
- the marshaller used to serialize valuesvalueMarshallers(BytesWriter, BytesReader)
,
OffHeapUpdatableChronicleMapBuilder
,
objectSerializer(ObjectSerializer)
public ChronicleMapBuilder<K,V> valueMarshallers(@NotNull BytesWriter<V> valueWriter, @NotNull BytesReader<V> valueReader)
Configuring marshalling this way results to a little bit more compact in-memory layout
of the map, comparing to a single interface configuration:
valueMarshaller(BytesMarshaller)
.
Passing BytesInterop
instead of plain BytesWriter
is, of cause, possible,
but currently pointless for values.
valueWriter
- the new value object → Bytes
writer (interop) strategyvalueReader
- the new Bytes
→ value object reader strategyvalueMarshaller(BytesMarshaller)
public ChronicleMapBuilder<K,V> valueSizeMarshaller(@NotNull SizeMarshaller valueSizeMarshaller)
Default value size marshaller is so-called stop bit encoding marshalling. If constant
value size is configured, or defaulted if the value type is always constant and ChronicleHashBuilder
implementation knows about it, this configuration takes no effect,
because a special SizeMarshaller
implementation, which doesn't actually do any
marshalling, and just returns the known constant size on SizeMarshaller.readSize(
Bytes)
calls, is used instead of any SizeMarshaller
configured using this method.
valueSizeMarshaller
- the new marshaller, used to serialize actual value sizes to
off-heap memoryCopyright © 2014. All rights reserved.