ChronicleHashBuilder (OpenHFT/Chronicle-Map 2.1.15 API)

Type Parameters:
K - the type of keys in hash containers, created by this builder
C - the container type, created by this builder, i. e. ChronicleMap or ChronicleSet
B - the concrete builder type, i. e. ChronicleMapBuilder or ChronicleSetBuilder

All Superinterfaces:

Cloneable

All Known Implementing Classes:

ChronicleMapBuilder, ChronicleSetBuilder
```
public interface ChronicleHashBuilder<K,C extends ChronicleHash,B extends ChronicleHashBuilder<K,C,B>>
extends Cloneable
```
This interface defines the meaning of configurations, common to ChronicleMapBuilder and ChronicleSetBuilder, i. e. Chronicle hash container configurations.
ChronicleHashBuilder is mutable. Configuration methods mutate the builder and return the builder itself back to support chaining pattern, rather than the builder copies with the corresponding configuration changed. To make an independent configuration, clone() the builder.
There are some "low-level" configurations in this builder, that require deep understanding of the Chronicle implementation design to be properly used. Know what you do. These configurations are picked up strictly as-is, without extra round-ups, adjustments, etc.

Method Summary

Methods
Modifier and Type	Method and Description
`B`	`actualChunkSize(int actualChunkSize)` Configures the size in bytes of allocation unit of hash container instances, created by this builder.
`B`	`actualChunksPerSegment(long actualChunksPerSegment)` Configures the actual number of chunks, that will be reserved for any single segment of the hash containers, created by this builder.
`B`	`actualSegments(int actualSegments)` Configures the actual number of segments in the hash containers, created by this builder.
`B`	`averageKeySize(double averageKeySize)` Configures the average number of bytes, taken by serialized form of keys, put into hash containers, created by this builder.
`B`	`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.
`B`	`clone()` Clones this builder.
`B`	`constantKeySizeBySample(K sampleKey)` Configures the constant number of bytes, taken by serialized form of keys, put into hash containers, created by this builder.
`C`	`create()` Creates a new hash container, storing it's data in off-heap memory, not mapped to any file.
`C`	`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.
`B`	`entries(long entries)` Configures the maximum number of entries, that could be inserted into the hash containers, created by this builder.
`B`	`entriesPerSegment(long entriesPerSegment)` Configures the actual maximum number entries, that could be inserted into any single segment of the hash containers, created by this builder.
`B`	`errorListener(ChronicleHashErrorListener errorListener)`
`B`	`immutableKeys()` Specifies that key objects, queried with the hash containers, created by this builder, are inherently immutable.
`ChronicleHashInstanceBuilder<C>`	`instance()`
`B`	`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.
`B`	`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.
`B`	`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.
`B`	`keySizeMarshaller(SizeMarshaller keySizeMarshaller)` Configures the marshaller used to serialize actual key sizes to off-heap memory in hash containers, created by this builder.
`B`	`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.
`B`	`maxChunksPerEntry(int maxChunksPerEntry)` Configures how many chunks a single entry, inserted into `ChronicleHash`es, created by this builder, could take.
`B`	`metaDataBytes(int metaDataBytes)`
`B`	`minSegments(int minSegments)` Set minimum number of segments in hash containers, constructed by this builder.
`B`	`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.
`B`	`replication(byte identifier)`
`B`	`replication(byte identifier, TcpTransportAndNetworkConfig tcpTransportAndNetwork)` Shortcut for `replication(SimpleReplication.builder() .tcpTransportAndNetwork(tcpTransportAndNetwork).createWithId(identifier))`.
`B`	`replication(SingleChronicleHashReplication replication)` Configures replication of the hash containers, created by this builder.
`B`	`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).

- Method Detail
  - clone
```
B clone()
```
    Clones this builder. Useful for configuration persisting, because ChronicleHashBuilders are mutable and changed on each configuration method call. Original and cloned builders are independent.
    
    Returns:
    a new clone of this builder
  - minSegments
```
B minSegments(int minSegments)
```
    Set minimum number of segments in hash containers, constructed by this builder. See concurrencyLevel in ConcurrentHashMap.
    
    Parameters:
    minSegments - the minimum number of segments in containers, constructed by this builder
    
    Returns:
    this builder object back
  - averageKeySize
```
B averageKeySize(double averageKeySize)
```
    Configures the average number of bytes, taken by serialized form of keys, put into hash containers, created by this builder. If key size is always the same, call constantKeySizeBySample(Object) method instead of this one.
    ChronicleHashBuilder implementation heuristically chooses the actual chunk size based on this configuration, that, however, might result to quite high internal fragmentation, i. e. losses because only integral number of chunks could be allocated for the entry. If you want to avoid this, you should manually configure the actual chunk size in addition to this average key size configuration, which is anyway needed.
    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.
    
    Parameters:
    averageKeySize - the average number of bytes, taken by serialized form of keys
    
    Returns:
    this builder back
    
    Throws:
    
    IllegalStateException - if key size is known statically and shouldn't be configured by user
    
    IllegalArgumentException - if the given keySize is non-positive
    See Also:
    constantKeySizeBySample(Object), actualChunkSize(int)
  - constantKeySizeBySample
```
B constantKeySizeBySample(K sampleKey)
```
    Configures the constant number of bytes, taken by serialized form of keys, put into hash containers, created by this builder. This is done by providing the 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 averageKeySize(double) should be called instead of this one.
    
    Parameters:
    sampleKey - the sample key
    
    Returns:
    this builder back
    See Also:
    averageKeySize(double)
  - actualChunkSize
```
B actualChunkSize(int actualChunkSize)
```
    Configures the size in bytes of allocation unit of hash container instances, created by this builder.
    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 chunk size is the minimum allocation portion in the hash containers, created by this builder. E. g. if chunk 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. This is called internal fragmentation.
    To minimize memory overuse and improve speed, you should pay decent attention to this configuration. Alternatively, you can just trust the heuristics and doesn't configure the chunk size.
    Specify chunk size so that most entries would take from 5 to several dozens of chunks. However, remember that operations with entries that span several chunks are a bit slower, than with entries which take a single chunk. Particularly avoid entries to take more than 64 chunks.
    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 chunk size of 30 * (8 bytes for each id) = 240 bytes would be a good choice:
```
Map<Long, long[]> socialGraph = ChronicleMapOnHeapUpdatableBuilder
     .of(Long.class, long[].class)
     .entries(1_000_000_000L)
     .averageValueSize(150 * 8) // 150 is average adjacency list size
     .actualChunkSize(30 * 8) // average 5-6 chunks per entry
     .create();
```
    This is a low-level configuration. The configured number of bytes is strictly used as-is, without anything like round-up to the multiple of 8 or 16, or any other adjustment.
    Parameters:
    actualChunkSize - the "chunk size" in bytes
    
    Returns:
    this builder back
    See Also:
    entries(long), maxChunksPerEntry(int)
  - maxChunksPerEntry
```
B maxChunksPerEntry(int maxChunksPerEntry)
```
    Configures how many chunks a single entry, inserted into ChronicleHashes, created by this builder, could take. If you try to insert larger entry, IllegalStateException is fired. This is useful as self-check, that you configured chunk size right and you keys (and values, in ChronicleMap case) take expected number of bytes. For example, if constantKeySizeBySample(Object) is configured or key size is statically known to be constant (boxed primitives, data value generated implementations, Byteables, etc.), and the same for value objects in ChronicleMap case, max chunks per entry is configured to 1, to ensure keys and values are actually constantly-sized.
    
    Parameters:
    maxChunksPerEntry - how many chunks a single entry could span at most
    
    Returns:
    this builder back
    
    Throws:
    
    IllegalArgumentException - if the given maxChunksPerEntry is lesser than 1 or greater than 64
    See Also:
    actualChunkSize(int)
  - entries
```
B entries(long entries)
```
    Configures the maximum number of entries, that could be inserted into the hash containers, created by this builder. If you try to insert more data, IllegalStateException might be thrown, because currently ChronicleMap and ChronicleSet don't support resizing.
    You shouldn't put additional margin over the actual maximum number of entries. This bad practice was popularized by HashMap.HashMap(int) and HashSet.HashSet(int) constructors, which accept capacity, that should be multiplied by load factor to obtain the actual maximum expected number of entries. ChronicleMap and ChronicleSet don't have a notion of load factor.
    Default maximum entries is 2^20 (~ 1 million).
    
    Parameters:
    entries - maximum size of the maps or sets, created by this builder
    
    Returns:
    this builder back
  - entriesPerSegment
```
B entriesPerSegment(long entriesPerSegment)
```
    Configures the actual maximum number entries, that could be inserted into any single segment of the hash containers, created by this builder. Configuring both the actual number of entries per segment and actual segments replaces a single entries(long) configuration.
    This is a low-level configuration.
    
    Parameters:
    entriesPerSegment - the actual maximum number entries per segment in the hash containers, created by this builder
    
    Returns:
    this builder back
    See Also:
    entries(long), actualSegments(int)
  - actualChunksPerSegment
```
B actualChunksPerSegment(long actualChunksPerSegment)
```
    Configures the actual number of chunks, that will be reserved for any single segment of the hash containers, created by this builder. This configuration is a lower-level version of entriesPerSegment(long). Makes sense only if actualChunkSize(int), actualSegments(int) and entriesPerSegment(long) are also configured manually.
    
    Parameters:
    actualChunksPerSegment - the actual number of segments, reserved per segment in the hash containers, created by this builder
    
    Returns:
    this builder back
  - actualSegments
```
B actualSegments(int actualSegments)
```
    Configures the actual number of segments in the hash containers, created by this builder. With actual number of segments, this configuration replaces a single entries(long) call.
    This is a low-level configuration. The configured number is used as-is, without anything like round-up to the closest power of 2.
    
    Parameters:
    actualSegments - the actual number of segments in hash containers, created by this builder
    
    Returns:
    this builder back
    See Also:
    minSegments(int), entriesPerSegment(long)
  - lockTimeOut
```
B 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. If timeout expires, 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.
    
    Parameters:
    lockTimeOut - new lock timeout for segments of containers created by this builder, in the given time units
    unit - time unit of the given lock timeout
    
    Returns:
    this builder back
  - errorListener
```
B errorListener(ChronicleHashErrorListener errorListener)
```
  - metaDataBytes
```
B metaDataBytes(int metaDataBytes)
```
  - timeProvider
```
B 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).
    Default time provider is TimeProvider.SYSTEM.
    
    Parameters:
    timeProvider - a new time provider for replication needs
    
    Returns:
    this builder back
    See Also:
    replication(SingleChronicleHashReplication)
  - bytesMarshallerFactory
```
B 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.
    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.
    
    Parameters:
    bytesMarshallerFactory - the marshaller factory to be used with the default ObjectSerializer, i. e. BytesMarshallableSerializer
    
    Returns:
    this builder back
    See Also:
    objectSerializer(ObjectSerializer)
  - objectSerializer
```
B 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. Please read ObjectSerializer docs for more info and available options.
    Default serializer is BytesMarshallableSerializer, configured with the specified or default BytesMarshallerFactory.
    
    Parameters:
    objectSerializer - the serializer used to serialize loosely typed or nullable data if custom marshaller is not configured
    
    Returns:
    this builder back
    See Also:
    bytesMarshallerFactory(BytesMarshallerFactory), keyMarshaller(BytesMarshaller)
  - keyMarshaller
```
B keyMarshaller(@NotNull
              BytesMarshaller<? super K> keyMarshaller)
```
    Configures the 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.
    
    Parameters:
    keyMarshaller - the marshaller used to serialize keys
    
    Returns:
    this builder back
    See Also:
    keyMarshallers(BytesWriter, BytesReader), objectSerializer(ObjectSerializer)
  - keyMarshallers
```
B keyMarshallers(@NotNull
               BytesWriter<K> keyWriter,
               @NotNull
               BytesReader<K> keyReader)
```
    Configures the marshallers, 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.
    Configuring marshalling this way results to a little bit more compact in-memory layout of the map, comparing to a single interface configuration: keyMarshaller(BytesMarshaller).
    Passing BytesInterop (which is a subinterface of BytesWriter) as the first argument is supported, and even more advantageous from performance perspective.
    
    Parameters:
    keyWriter - the new key object → Bytes writer (interop) strategy
    keyReader - the new Bytes → key object reader strategy
    
    Returns:
    this builder back
    See Also:
    keyMarshaller(BytesMarshaller)
  - keySizeMarshaller
```
B keySizeMarshaller(@NotNull
                  SizeMarshaller keySizeMarshaller)
```
    Configures the marshaller used to serialize actual key sizes to off-heap memory in hash containers, created by this builder.
    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.
    
    Parameters:
    keySizeMarshaller - the new marshaller, used to serialize actual key sizes to off-heap memory
    
    Returns:
    this builder back
  - keyDeserializationFactory
```
B keyDeserializationFactory(@NotNull
                          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.
    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.
    
    Parameters:
    keyDeserializationFactory - the key factory used to produce instances to deserialize data in
    
    Returns:
    this builder back
    
    Throws:
    
    IllegalStateException - if it is not possible to apply deserialization factory to key deserializers, currently configured for this builder
  - immutableKeys
```
B immutableKeys()
```
    Specifies that key objects, queried with the hash containers, created by this builder, are inherently immutable. Keys in 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, ChronicleHashBuilders 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.
    
    Returns:
    this builder back
  - replication
```
B replication(SingleChronicleHashReplication replication)
```
    Configures replication of the hash containers, created by this builder. See the section about replication in ChronicleMap manual for more information.
    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 replication(byte, TcpTransportAndNetworkConfig) shortcut method.
    
    Parameters:
    replication - the replication config
    
    Returns:
    this builder back
    See Also:
    ChronicleHashInstanceBuilder.replicated(SingleChronicleHashReplication), replication(byte, TcpTransportAndNetworkConfig)
  - replication
```
B replication(byte identifier,
            TcpTransportAndNetworkConfig tcpTransportAndNetwork)
```
    Shortcut for replication(SimpleReplication.builder() .tcpTransportAndNetwork(tcpTransportAndNetwork).createWithId(identifier)).
    
    Parameters:
    identifier - the network-wide identifier of the containers, created by this builder
    tcpTransportAndNetwork - configuration of tcp connection and network
    
    Returns:
    this builder back
    See Also:
    replication(SingleChronicleHashReplication), ChronicleHashInstanceBuilder.replicated(byte, TcpTransportAndNetworkConfig)
  - replication
```
B replication(byte identifier)
```
  - instance
```
ChronicleHashInstanceBuilder<C> instance()
```
  - create
```
C create()
```
    Creates a new hash container, storing it's data in off-heap memory, not mapped to any file. On 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().
    
    Returns:
    a new off-heap hash container
    See Also:
    createPersistedTo(File), instance()
  - createPersistedTo
```
C createPersistedTo(File file)
                                          throws IOException
```
    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. All changes to the map are persisted to disk (this is an operating system guarantee) independently from JVM process lifecycle.
    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().
    
    Parameters:
    file - the file with existing hash container or a desired location of a new off-heap persisted hash container
    
    Returns:
    a hash container mapped to the given file
    
    Throws:
    
    IOException - if any IO error, related to off-heap memory allocation or file mapping, or establishing replication connections, occurs
    See Also:
    ChronicleHash.file(), ChronicleHash.close(), create(), ChronicleHashInstanceBuilder.persistedTo(File)

Interface ChronicleHashBuilder<K,C extends ChronicleHash,B extends ChronicleHashBuilder<K,C,B>>

Method Summary

Method Detail

clone

minSegments

averageKeySize

constantKeySizeBySample

actualChunkSize

maxChunksPerEntry

entries

entriesPerSegment

actualChunksPerSegment

actualSegments

lockTimeOut

errorListener

metaDataBytes

timeProvider

bytesMarshallerFactory

objectSerializer

keyMarshaller

keyMarshallers

keySizeMarshaller

keyDeserializationFactory

immutableKeys

replication

replication

replication

instance

create

createPersistedTo