K
- key type of the maps, produced by this builderV
- value type of the maps, produced by this builderpublic final class ChronicleMapBuilder<K,V> extends Object implements Cloneable, ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>, Serializable
ChronicleMapBuilder
manages ChronicleMap
configurations; could be used as a
classic builder and/or factory. This means that in addition to the standard builder usage
pattern: ChronicleMap<Key, Value> map = ChronicleMapOnHeapUpdatableBuilder
.of(Key.class, Value.class)
.entries(100500)
// ... other configurations
.create();
it could be prepared and used to create many similar maps: ChronicleMapBuilder<Key, Value> builder = ChronicleMapBuilder
.of(Key.class, Value.class)
.entries(100500);
<p>
ChronicleMap<Key, Value> map1 = builder.create();
ChronicleMap<Key, Value> map2 = builder.create();
i. e. created ChronicleMap
instances don't depend on the builder.
ChronicleMapBuilder
is mutable, see a note in ChronicleHashBuilder
interface
documentation.
Later in this documentation, "ChronicleMap" means "ChronicleMaps, created
by ChronicleMapBuilder
", unless specified different, because theoretically someone might
provide ChronicleMap
implementations with completely different properties.
ChronicleMap
("ChronicleMaps, created by ChronicleMapBuilder
") currently doesn't support
resizing. That is why you should always configure number of
entries you are going to insert into the created map at most. See entries(long)
method documentation for more information on this.
ChronicleMap
allocates memory
by equally sized chunks. This size is called entry size, you are
strongly recommended to configure it to achieve least memory consumption and best speed. See
entrySize(int)
method documentation for more information on this.
ChronicleMap
,
ChronicleSetBuilder
,
Serialized FormModifier and Type | Method and Description |
---|---|
ChronicleMapBuilder<K,V> |
actualEntriesPerSegment(long actualEntriesPerSegment) |
ChronicleMapBuilder<K,V> |
actualSegments(int actualSegments) |
ChronicleMapBuilder<K,V> |
bytesEventListener(BytesMapEventListener eventListener) |
ChronicleMapBuilder<K,V> |
bytesMarshallerFactory(BytesMarshallerFactory bytesMarshallerFactory)
Configures a
BytesMarshallerFactory to be used with BytesMarshallableSerializer , which is a default ObjectSerializer ,
to serialize/deserialize data to/from off-heap memory in hash containers, created by this
builder. |
ChronicleMapBuilder<K,V> |
clone()
Clones this builder.
|
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.
|
ChronicleMap<K,V> |
create()
Creates a new hash container, storing it's data in off-heap memory, not mapped to any file.
|
ChronicleMap<K,V> |
createPersistedTo(File file)
Opens a hash container residing the specified file, or creates a new one if the file not yet
exists and maps its off-heap memory to the file.
|
ChronicleMap<K,V> |
createStatelessClient(InetSocketAddress serverAddress) |
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> |
entries(long entries)
Package-private for tests
|
ChronicleMapBuilder<K,V> |
entryAndValueAlignment(Alignment alignment)
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.
|
ChronicleMapBuilder<K,V> |
entrySize(int entrySize)
Configures the size in bytes of allocation unit of hash container instances, created by this
builder.
|
boolean |
equals(Object o) |
ChronicleMapBuilder<K,V> |
errorListener(ChronicleHashErrorListener errorListener) |
ChronicleMapBuilder<K,V> |
eventListener(MapEventListener<K,V> eventListener) |
int |
hashCode() |
ChronicleMapBuilder<K,V> |
immutableKeys()
Specifies that key objects, queried with the hash containers, created by this builder, are
inherently immutable.
|
ChronicleHashInstanceConfig<ChronicleMap<K,V>> |
instance() |
ChronicleMapBuilder<K,V> |
keyDeserializationFactory(ObjectFactory<K> keyDeserializationFactory)
Configures factory which is used to create a new key instance, if key class is either
Byteable , BytesMarshallable or Externalizable subclass, or key type is
eligible for data value generation, or configured custom key reader implements DeserializationFactoryConfigurableBytesReader , in maps, created by this builder. |
ChronicleMapBuilder<K,V> |
keyMarshaller(BytesMarshaller<? super K> keyMarshaller)
Configures the
BytesMarshaller used to serialize/deserialize keys to/from off-heap
memory in hash containers, created by this builder. |
ChronicleMapBuilder<K,V> |
keyMarshallers(BytesWriter<K> keyWriter,
BytesReader<K> keyReader)
Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in
hash containers, 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> |
keySizeMarshaller(SizeMarshaller keySizeMarshaller)
Configures the marshaller used to serialize actual key sizes to off-heap memory in hash
containers, created by this builder.
|
ChronicleMapBuilder<K,V> |
lockTimeOut(long lockTimeOut,
TimeUnit unit)
Configures timeout of locking on segments of hash
containers, created by this builder, when performing any queries, as well as bulk operations
like iteration.
|
ChronicleMapBuilder<K,V> |
maxEntryOversizeFactor(int maxEntryOversizeFactor)
Configures how much the actual entry size is allowed to be larger than configured or derived
entry size.
|
ChronicleMapBuilder<K,V> |
metaDataBytes(int metaDataBytes) |
ChronicleMapBuilder<K,V> |
minSegments(int minSegments)
Set minimum number of segments in hash containers, constructed 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> |
prepareDefaultValueBytes(PrepareValueBytes<K,V> prepareValueBytes)
Configures the procedure which is called on the bytes, which later the returned value is
pointing to or deserialized from, if the key is absent, on
acquireUsing() call on maps, created by this builder. |
ChronicleMapBuilder<K,V> |
pushTo(InetSocketAddress... addresses) |
ChronicleMapBuilder<K,V> |
putReturnsNull(boolean putReturnsNull)
Configures if the maps created by this builder should return
null instead of previous
mapped values on ChornicleMap.put(key, value) calls. |
ChronicleMapBuilder<K,V> |
removeReturnsNull(boolean removeReturnsNull)
Configures if the maps created by this builder should return
null instead of the last
mapped value on ChronicleMap.remove(key) calls. |
ChronicleMapBuilder<K,V> |
replication(byte identifier) |
ChronicleMapBuilder<K,V> |
replication(byte identifier,
TcpTransportAndNetworkConfig tcpTransportAndNetwork)
Shortcut for
replication(SimpleReplication.builder() .tcpTransportAndNetwork(tcpTransportAndNetwork).createWithId(identifier)) . |
ChronicleMapBuilder<K,V> |
replication(SingleChronicleHashReplication replication)
Configures replication of the hash containers, created by this builder.
|
StatelessClientConfig<ChronicleMap<K,V>> |
statelessClient(InetSocketAddress remoteAddress) |
ChronicleMapBuilder<K,V> |
timeProvider(TimeProvider timeProvider)
Configures a time provider, used by hash containers, created by this builder, for needs of
replication consensus protocol (conflicting data updates resolution).
|
String |
toString() |
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, or value type
is eligible for data value generation, or configured custom value reader is an instance of
DeserializationFactoryConfigurableBytesReader , in maps, created by this builder. |
ChronicleMapBuilder<K,V> |
valueMarshaller(BytesMarshaller<? super 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.
|
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.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> pushTo(InetSocketAddress... addresses)
public ChronicleMapBuilder<K,V> clone()
ChronicleHashBuilder
ChronicleHashBuilder
s are mutable and changed on each configuration method call. Original
and cloned builders are independent.clone
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
clone
in class Object
public 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.
If key is a boxed primitive type or Byteable
subclass, i. e. if key size is known
statically, it is automatically accounted and shouldn't be specified by user.
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 = ChronicleMapBuilder
.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
- number of bytes, taken by serialized form of keysIllegalStateException
- if key size is known statically and shouldn't be configured
by userIllegalArgumentException
- if the given keySize
is non-positiveconstantKeySizeBySample(Object)
,
valueSize(int)
,
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])
.immutableKeys()
.create();
constantKeySizeBySample
in interface ChronicleHashBuilder<K,ChronicleMap<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 values are of boxed
primitive type or Byteable
subclass, 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 valuesIllegalStateException
- if value size is known statically and shouldn't be
configured by userIllegalArgumentException
- if the given valueSize
is non-positiveconstantValueSizeBySample(Object)
,
keySize(int)
,
entrySize(int)
public ChronicleMapBuilder<K,V> constantValueSizeBySample(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 entrySize(int)
should be called
instead of this one.
sampleValue
- the sample valuevalueSize(int)
,
constantKeySizeBySample(Object)
public ChronicleMapBuilder<K,V> entrySize(int entrySize)
ChronicleMap
and ChronicleSet
store their data off-heap, so it is required
to serialize key (and values, in ChronicleMap
case) (unless they are direct Byteable
instances). Serialized key bytes (+ serialized value bytes, in ChronicleMap
case) + some metadata bytes comprise "entry space", which ChronicleMap
or ChronicleSet
should allocate. So entry size is a minimum allocation portion in the
hash containers, created by this builder. E. g. if entry size is 100, the created container
could only allocate 100, 200, 300... bytes for an entry. If say 150 bytes of entry space are
required by the entry, 200 bytes will be allocated, 150 used and 50 wasted. To minimize
memory overuse and improve speed, you should pay decent attention to this configuration.
There are three major patterns of this configuration usage:
ChronicleMap
case) sizes are constant. Configure them via ChronicleHashBuilder.constantKeySizeBySample(Object)
and constantValueSizeBySample(Object)
methods, and you will experience no memory waste at all.ChronicleMap
case) varies moderately. Specify them using corresponding methods, or
specify entry size directly by calling this method, by sizes somewhere between average and
maximum possible. The idea is to have most (90% or more) entries to fit a single "entry size"
with moderate memory waste (10-20% on average), rest 10% or less of entries should take 2
"entry sizes", thus with ~50% memory overuse.ChronicleMap
case) varies in a wide range. Then it's best to use entry size configuration in
chunk mode. Specify entry size so that most entries should take from 5 to several
dozens of "chunks". With this approach, average memory waste should be very low.
However, remember that
ChronicleHashBuilder.maxEntryOversizeFactor(int)
, of max
64 chunks. IllegalArgumentException
is thrown on attempt to insert too large entry,
compared to the configured or computed entry size.Example: if values in your ChronicleMap
are adjacency lists of some social graph,
where nodes are represented as long
ids, and adjacency lists are serialized in
efficient manner, for example as long[]
arrays. Typical number of connections is
100-300, maximum is 3000. In this case entry size of
50 * (8 bytes for each id) = 400 bytes would be a good choice:
Map<Long, long[]> socialGraph = ChronicleMapOnHeapUpdatableBuilder
.of(Long.class, long[].class)
// given that graph should have of 1 billion nodes, and 150 average adjacency list size
// => values takes 3 chuncks on average
.entries(1_000_000_000L * (150 / 50))
.entrySize(50 * 8)
.create();
It is minimum possible (because 3000 friends / 50 friends = 60 is close to 64 "max chunks by
single entry" limit, and ensures moderate average memory overuse (not more than 20%).
In fully default case you can expect entry size to be about 256 bytes. But it is strongly recommended always to configure key size and 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 meta data bytes, plus key size, plus value size, plus a few bytes required by implementations, with respect to alignment.
Note that
the actual entrySize will be aligned by the configured entry and value alignment. I. e. if you set entry size to
30, and entry alignment is set to Alignment.OF_4_BYTES
, the actual entry size will be
32 (30 aligned to 4 bytes).
entrySize
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
entrySize
- the "chunk size" in bytesIllegalStateException
- is sizes of both keys and values of maps created by this
builder are statically known, hence entry size shouldn't be
configured by userentryAndValueAlignment(Alignment)
,
entries(long)
,
maxEntryOversizeFactor(int)
public ChronicleMapBuilder<K,V> maxEntryOversizeFactor(int maxEntryOversizeFactor)
ChronicleHashBuilder
maxEntryOversizeFactor
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
maxEntryOversizeFactor
- number of times the actual entry size could oversize the
configured "entry size" (chunk size, actually)public ChronicleMapBuilder<K,V> entryAndValueAlignment(Alignment alignment)
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.
Note that
entry size will be aligned according to this alignment. I. e. if
you set entrySize(20)
and Alignment.OF_8_BYTES
, actual entry size will be 24
(20 aligned to 8 bytes).
If values couldn't reference off-heap memory (i. e. it is not
Byteable
or "data value generated"), alignment configuration makes no sense and
forbidden.
Default is Alignment.NO_ALIGNMENT
if values couldn't reference
off-heap memory, otherwise chosen heuristically (configure explicitly for being sure and to
compare performance in your case).
alignment
- the new alignment of the maps constructed by this builderChronicleMapOnHeapUpdatableBuilder
backIllegalStateException
- if values of maps, created by this builder, couldn't reference
off-heap memorypublic ChronicleMapBuilder<K,V> entries(long entries)
entries
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
entries
- maximum size of the created maps, in memory allocation units, so-called "entry
size"ChronicleHashBuilder.entrySize(int)
public ChronicleMapBuilder<K,V> actualEntriesPerSegment(long actualEntriesPerSegment)
actualEntriesPerSegment
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMapBuilder<K,V> minSegments(int minSegments)
ChronicleHashBuilder
ConcurrentHashMap
.minSegments
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
minSegments
- the minimum number of segments in containers, constructed by this builderpublic ChronicleMapBuilder<K,V> actualSegments(int actualSegments)
actualSegments
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMapBuilder<K,V> lockTimeOut(long lockTimeOut, TimeUnit unit)
ChronicleHashBuilder
ChronicleHashErrorListener.onLockTimeout(long)
is
called, and then thread tries to obtain the segment lock one more time, and so in a loop,
until thread is interrupted. However, you can configure error listener to throw an exception on the first
(or n-th) lock acquisition fail.
Default lock time out is 2 seconds.
lockTimeOut
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
lockTimeOut
- new lock timeout for segments of containers created by this builder, in
the given time unitsunit
- time unit of the given lock timeoutpublic ChronicleMapBuilder<K,V> errorListener(ChronicleHashErrorListener errorListener)
errorListener
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMapBuilder<K,V> putReturnsNull(boolean putReturnsNull)
null
instead of previous
mapped values on ChornicleMap.put(key, value)
calls.
Map.put()
returns the previous value, functionality
which is rarely used but fairly cheap for 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, ChronicleMap
conforms the general Map
contract and returns the previous mapped value
on put()
calls.
putReturnsNull
- true
if you want ChronicleMap.put()
to not return the value that was replaced but
instead return null
removeReturnsNull(boolean)
public ChronicleMapBuilder<K,V> removeReturnsNull(boolean removeReturnsNull)
null
instead of the last
mapped value on ChronicleMap.remove(key)
calls.
Map.remove()
returns the previous value, functionality which is
rarely used but fairly cheap for 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, ChronicleMap
conforms
the general Map
contract and returns the mapped value on remove()
calls.
removeReturnsNull
- true
if you want ChronicleMap.remove()
to not return the value of the removed entry
but instead return null
putReturnsNull(boolean)
public ChronicleMapBuilder<K,V> metaDataBytes(int metaDataBytes)
metaDataBytes
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMapBuilder<K,V> timeProvider(TimeProvider timeProvider)
ChronicleHashBuilder
Default time provider is TimeProvider.SYSTEM
.
timeProvider
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
timeProvider
- a new time provider for replication needsChronicleHashBuilder.replication(SingleChronicleHashReplication)
public ChronicleMapBuilder<K,V> bytesMarshallerFactory(BytesMarshallerFactory bytesMarshallerFactory)
ChronicleHashBuilder
BytesMarshallerFactory
to be used with BytesMarshallableSerializer
, which is a default ObjectSerializer
,
to serialize/deserialize data to/from off-heap memory in hash containers, created by this
builder.
Default BytesMarshallerFactory
is an instance of VanillaBytesMarshallerFactory
. This is a convenience configuration method, it has no effect
on the resulting hash containers, if custom data
marshallers are configured, data types extends one of specific serialization interfaces,
recognized by this builder (e. g. Externalizable
or BytesMarshallable
), or
ObjectSerializer
is configured.
bytesMarshallerFactory
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
bytesMarshallerFactory
- the marshaller factory to be used with the default ObjectSerializer
, i. e. BytesMarshallableSerializer
ChronicleHashBuilder.objectSerializer(ObjectSerializer)
public ChronicleMapBuilder<K,V> objectSerializer(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
- 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> keyMarshaller(@NotNull BytesMarshaller<? super K> keyMarshaller)
ChronicleHashBuilder
BytesMarshaller
used to serialize/deserialize keys to/from off-heap
memory in hash containers, created by this builder. See the
section about serialization in ChronicleMap manual for more information.keyMarshaller
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
keyMarshaller
- the marshaller used to serialize keysChronicleHashBuilder.keyMarshallers(BytesWriter, BytesReader)
,
ChronicleHashBuilder.objectSerializer(ObjectSerializer)
public ChronicleMapBuilder<K,V> keyMarshallers(@NotNull BytesWriter<K> keyWriter, @NotNull BytesReader<K> keyReader)
ChronicleHashBuilder
Configuring marshalling this way results to a little bit more compact in-memory layout of
the map, comparing to a single interface configuration: ChronicleHashBuilder.keyMarshaller(BytesMarshaller)
.
Passing BytesInterop
(which is a subinterface of BytesWriter
) as the first
argument is supported, and even more advantageous from performance perspective.
keyMarshallers
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
keyWriter
- the new key object → Bytes
writer (interop) strategykeyReader
- the new Bytes
→ key object reader strategyChronicleHashBuilder.keyMarshaller(BytesMarshaller)
public ChronicleMapBuilder<K,V> keySizeMarshaller(@NotNull SizeMarshaller keySizeMarshaller)
ChronicleHashBuilder
Default key size marshaller is so-called stop bit
encoding marshalling. If constant key size is
configured, or defaulted if the key 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.
keySizeMarshaller
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
keySizeMarshaller
- the new marshaller, used to serialize actual key sizes to off-heap
memorypublic ChronicleMapBuilder<K,V> keyDeserializationFactory(@NotNull ObjectFactory<K> keyDeserializationFactory)
ChronicleHashBuilder
Byteable
, BytesMarshallable
or Externalizable
subclass, or key type is
eligible for data value generation, or configured custom key reader implements DeserializationFactoryConfigurableBytesReader
, in maps, created by this builder.
Default key deserialization factory is NewInstanceObjectFactory
, which creates a
new key 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 key class constructor with some arguments, or a factory which
internally delegates to instance pool or ThreadLocal
, to reduce allocations.
keyDeserializationFactory
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
keyDeserializationFactory
- the key factory used to produce instances to deserialize
data inIllegalStateException
- if it is not possible to apply deserialization factory to
key deserializers, currently configured for this buildervalueDeserializationFactory(ObjectFactory)
public ChronicleMapBuilder<K,V> immutableKeys()
ChronicleHashBuilder
ChronicleMap
or ChronicleSet
are not required
to be immutable, as in ordinary Map
or Set
implementations, because they are
serialized off-heap. However, ChronicleMap
and ChronicleSet
implementations
can benefit from the knowledge that keys are not mutated between queries.
By default, ChronicleHashBuilder
s detects immutability automatically only for very
few standard JDK types (for example, for String
), it is not recommended to rely on
ChronicleHashBuilder
to be smart enough about this.
immutableKeys
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMapBuilder<K,V> valueMarshaller(@NotNull BytesMarshaller<? super 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)
,
objectSerializer(ObjectSerializer)
,
keyMarshaller(BytesMarshaller)
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)
,
valueSizeMarshaller(SizeMarshaller)
,
keyMarshallers(BytesWriter, BytesReader)
public ChronicleMapBuilder<K,V> valueSizeMarshaller(@NotNull SizeMarshaller valueSizeMarshaller)
Default value size marshaller is so-called stop bit encoding marshalling, unless constantValueSizeBySample(Object)
or the builder statically knows the value size is
constant -- SizeMarshallers.constant(long)
or equivalents are used by default in
these cases.
valueSizeMarshaller
- the new marshaller, used to serialize actual value sizes to
off-heap memorykeySizeMarshaller(SizeMarshaller)
public ChronicleMapBuilder<K,V> valueDeserializationFactory(@NotNull ObjectFactory<V> valueDeserializationFactory)
Byteable
, BytesMarshallable
or Externalizable
subclass, or value type
is eligible for data value generation, or configured custom value reader is an instance of
DeserializationFactoryConfigurableBytesReader
, 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.
valueDeserializationFactory
- the value factory used to produce instances to deserialize
data inIllegalStateException
- if it is not possible to apply deserialization factory to value
deserializers, currently configured for this builderkeyDeserializationFactory(ObjectFactory)
public ChronicleMapBuilder<K,V> eventListener(MapEventListener<K,V> eventListener)
public ChronicleMapBuilder<K,V> bytesEventListener(BytesMapEventListener eventListener)
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 defaultValueProvider(DefaultValueProvider)
and
prepareDefaultValueBytes(PrepareValueBytes)
configurations to this builder.
defaultValue
- the default value to be put to the map for absent keys during acquireUsing()
callsdefaultValueProvider(DefaultValueProvider)
,
prepareDefaultValueBytes(PrepareValueBytes)
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 defaultValue(Object)
and prepareDefaultValueBytes(PrepareValueBytes)
configurations to this builder.
defaultValueProvider
- the strategy to obtain a default value by the absent keydefaultValue(Object)
,
prepareDefaultValueBytes(PrepareValueBytes)
public ChronicleMapBuilder<K,V> prepareDefaultValueBytes(@NotNull PrepareValueBytes<K,V> prepareValueBytes)
acquireUsing()
call on maps, created by this builder. See PrepareValueBytes
for more
information.
This method of value initialization on acquireUsing()
calls is
allowed only if value size is constant. Otherwise you should use either defaultValue(Object)
or defaultValueProvider(DefaultValueProvider)
methods.
This configuration overrides any previous defaultValue(Object)
and defaultValueProvider(DefaultValueProvider)
configurations to this builder.
The default preparation callback zeroes out the value bytes.
prepareValueBytes
- what to do with the value bytes before assigning them into the
Byteable
value or deserializing the value from, to return
from acquireUsing()
callIllegalStateException
- is value size is not constantPrepareValueBytes
,
defaultValue(Object)
,
defaultValueProvider(DefaultValueProvider)
public ChronicleMapBuilder<K,V> replication(SingleChronicleHashReplication replication)
ChronicleHashBuilder
By default, hash containers, created by this builder doesn't replicate their data.
This method call overrides all previous replication configurations of this builder, made
either by this method or ChronicleHashBuilder.replication(byte, TcpTransportAndNetworkConfig)
shortcut
method.
replication
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
replication
- the replication configChronicleHashInstanceConfig.replicated(SingleChronicleHashReplication)
,
ChronicleHashBuilder.replication(byte, TcpTransportAndNetworkConfig)
public ChronicleMapBuilder<K,V> replication(byte identifier)
replication
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMapBuilder<K,V> replication(byte identifier, TcpTransportAndNetworkConfig tcpTransportAndNetwork)
ChronicleHashBuilder
replication(SimpleReplication.builder() .tcpTransportAndNetwork(tcpTransportAndNetwork).createWithId(identifier))
.replication
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
identifier
- the network-wide identifier of the containers, created by this
buildertcpTransportAndNetwork
- configuration of tcp connection and networkChronicleHashBuilder.replication(SingleChronicleHashReplication)
,
ChronicleHashInstanceConfig.replicated(byte, TcpTransportAndNetworkConfig)
public ChronicleHashInstanceConfig<ChronicleMap<K,V>> instance()
instance
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMap<K,V> createStatelessClient(InetSocketAddress serverAddress) throws IOException
createStatelessClient
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
IOException
public ChronicleMap<K,V> createPersistedTo(File file) throws IOException
ChronicleHashBuilder
Multiple containers could give access to the same data simultaneously, either inside a single JVM or across processes. Access is synchronized correctly across all instances, i. e. hash container mapping the data from the first JVM isn't able to modify the data, concurrently accessed from the second JVM by another hash container instance, mapping the same data.
On container's close()
the data isn't removed, it remains on
disk and available to be opened again (given the same file name) or during different JVM
run.
This method is shortcut for instance().persistedTo(file).create()
.
createPersistedTo
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
file
- the file with existing hash container or a desired location of a new off-heap
persisted hash containerIOException
- if any IO error, related to off-heap memory allocation or file mapping,
or establishing replication connections, occursChronicleHash.file()
,
ChronicleHash.close()
,
ChronicleHashBuilder.create()
,
ChronicleHashInstanceConfig.persistedTo(File)
public StatelessClientConfig<ChronicleMap<K,V>> statelessClient(InetSocketAddress remoteAddress)
statelessClient
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
public ChronicleMap<K,V> create()
ChronicleHashBuilder
ChronicleHash.close()
called on the returned container, or after the container
object is collected during GC, or on JVM shutdown the off-heap memory used by the returned
container is freed.
This method is a shortcut for instance().create()
.
create
in interface ChronicleHashBuilder<K,ChronicleMap<K,V>,ChronicleMapBuilder<K,V>>
ChronicleHashBuilder.createPersistedTo(File)
,
ChronicleHashBuilder.instance()
Copyright © 2014. All rights reserved.