net.openhft.chronicle.hash

Interface ChronicleHashBuilder<K,H extends ChronicleHash<K,?,?,?>,B extends ChronicleHashBuilder<K,H,B>>

Type Parameters:

K - the type of keys in hash containers, created by this builder

H - 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,H extends ChronicleHash<K,?,?,?>,B extends ChronicleHashBuilder<K,H,B>>
extends Cloneable

Base interface for ChronicleMapBuilder and ChronicleSetBuilder, i. e. defines 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.

ChronicleHashBuilder instances are not safe for concurrent use from multiple threads, if at least one of the threads mutates the ChronicleHashBuilder's state.

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 applied as-is, without extra round-ups, adjustments, etc.

Method Summary

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	actualChunksPerSegmentTier(long actualChunksPerSegmentTier) Configures the actual number of chunks, that will be reserved for any single segment tier 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	aligned64BitMemoryOperationsAtomic(boolean aligned64BitMemoryOperationsAtomic) Specifies whether on the current combination of platform, OS and Jvm aligned 8-byte reads and writes are atomic or not.
B	allowSegmentTiering(boolean allowSegmentTiering) In addition to maxBloatFactor(1.0), that does not guarantee that segments won't tier (due to bad hash distribution or natural variance), configuring allowSegmentTiering(false) makes Chronicle Hashes, created by this builder, to throw IllegalStateException immediately when some segment overflows.
B	averageKey(K averageKey) Configures the average number of bytes, taken by serialized form of keys, put into hash containers, created by this builder, by serializing the given averageKey using the configured keys marshallers.
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	checksumEntries(boolean checksumEntries) Configures whether hash containers, created by this builder, should compute and store entry checksums.
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.
H	create() Creates a new hash container from this builder, storing it's data in off-heap memory, not mapped to any file.
H	createOrRecoverPersistedTo(File file) Recovers and opens the hash container, persisted to the specified file, or creates a new one from this builder, if the file doesn't exist yet, and maps its off-heap memory to the file.
H	createPersistedTo(File file) Opens a hash container residing the specified file, or creates a new one from this builder, if the file doesn't yet exist and maps its off-heap memory to the file.
B	entries(long entries) Configures the target number of entries, that is going 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.
<M extends BytesReader<K> & BytesWriter<? super K>> B	keyMarshaller(M marshaller) Shortcut for keyMarshallers(marshaller, marshaller).
<M extends SizedReader<K> & SizedWriter<? super K>> B	keyMarshaller(M sizedMarshaller) Shortcut for keyMarshallers(sizedMarshaller, sizedMarshaller).
B	keyMarshallers(BytesReader<K> keyReader, BytesWriter<? super K> keyWriter) Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in hash containers, created by this builder.
B	keyMarshallers(SizedReader<K> keyReader, SizedWriter<? super K> keyWriter) Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in hash containers, created by this builder.
B	keyReaderAndDataAccess(SizedReader<K> keyReader, DataAccess<K> keyDataAccess) Configures the DataAccess and SizedReader used to serialize and deserialize keys to and 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	maxBloatFactor(double maxBloatFactor) Configures the maximum number of times, the hash containers, created by this builder, are allowed to grow in size beyond the configured target number of entries.
B	maxChunksPerEntry(int maxChunksPerEntry) Configures how many chunks a single entry, inserted into ChronicleHashes, created by this builder, could take.
B	minSegments(int minSegments) Set minimum number of segments in hash containers, constructed by this builder.
B	nonTieredSegmentsPercentile(double nonTieredSegmentsPercentile) Configures probabilistic fraction of segments, which shouldn't become tiered, if Chronicle Hash size is entries(long), assuming hash code distribution of the keys, inserted into configured Chronicle Hash, is good.
Object	privateAPI() Deprecated. don't use private API in the client code
H	recoverPersistedTo(File file, boolean sameBuilderConfig) Recovers and opens the hash container, persisted to the specified file.

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. However, in many cases averageKey(Object) might be easier to use and more reliable. 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, a value interface or Byteable subclass, i. e. if key size is known statically, it is automatically accounted and shouldn't be specified by user.

Calling this method clears any previous constantKeySizeBySample(Object) and averageKey(Object) configurations.

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:

averageKey(Object), constantKeySizeBySample(Object), actualChunkSize(int)

averageKey

B averageKey(K averageKey)

Configures the average number of bytes, taken by serialized form of keys, put into hash containers, created by this builder, by serializing the given averageKey using the configured keys marshallers. In some cases, averageKeySize(double) might be easier to use, than constructing the "average key". 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.

Calling this method clears any previous constantKeySizeBySample(Object) and averageKeySize(double) configurations.

Parameters:

averageKey - the average (by footprint in serialized form) key, is going to be put into the hash containers, created by this builder

Returns:

this builder back

Throws:

NullPointerException - if the given averageKey is null

See Also:

averageKeySize(double), 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.

Calling this method clears any previous averageKey(Object) and averageKeySize(double) configurations.

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 = ChronicleMapBuilder
     .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 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 target number of entries, that is going be inserted into the hash containers, created by this builder. If maxBloatFactor(double) is configured to 1.0 (and this is by default), this number of entries is also the maximum. If you try to insert more entries, than the configured maxBloatFactor, multiplied by the given number of entries, IllegalStateException might be thrown.

This configuration should represent the expected maximum number of entries in a stable state, maxBloatFactor - the maximum bloat up coefficient, during exceptional bursts.

To be more precise - try to configure the entries so, that the created hash container is going to serve about 99% requests being less or equal than this number of entries in size.

You shouldn't put additional margin over the actual target 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.

The default target number of entries is 2^20 (~ 1 million).

Parameters:

entries - the target size of the maps or sets, created by this builder

Returns:

this builder back

Throws:

IllegalArgumentException - if the given entries number is non-positive

See Also:

maxBloatFactor(double)

maxBloatFactor

B maxBloatFactor(double maxBloatFactor)

Configures the maximum number of times, the hash containers, created by this builder, are allowed to grow in size beyond the configured target number of entries.

entries(long) should represent the expected maximum number of entries in a stable state, maxBloatFactor - the maximum bloat up coefficient, during exceptional bursts.

This configuration should be used for self-checking. Even if you configure impossibly large maxBloatFactor, the created ChronicleHash, of cause, will be still operational, and even won't allocate any extra resources before they are actually needed. But when the ChronicleHash grows beyond the configured entries(long), it could start to serve requests progressively slower. If you insert new entries into ChronicleHash infinitely, due to a bug in your business logic code, or the ChronicleHash configuration, and if you configure the ChronicleHash to grow infinitely, you will have a terribly slow and fat, but operational application, instead of a fail with IllegalStateException, which will quickly show you, that there is a bug in you application.

The default maximum bloat factor factor is 1.0 - i. e. "no bloat is expected".

It is strongly advised not to configure maxBloatFactor to more than 10.0, almost certainly, you either should configure ChronicleHashes completely differently, or this data store doesn't fit to your case.

Parameters:

maxBloatFactor - the maximum number ot times, the created hash container is supposed to bloat up beyond the entries(long)

Returns:

this builder back

Throws:

IllegalArgumentException - if the given maxBloatFactor is NaN, lesser than 1.0 or greater than 1000.0 (one thousand)

See Also:

entries(long)

allowSegmentTiering

B allowSegmentTiering(boolean allowSegmentTiering)

In addition to maxBloatFactor(1.0), that does not guarantee that segments won't tier (due to bad hash distribution or natural variance), configuring allowSegmentTiering(false) makes Chronicle Hashes, created by this builder, to throw IllegalStateException immediately when some segment overflows.

Useful exactly for testing hash distribution and variance of segment filling.

Default is true, segments are allowed to tier.

When configured to false, maxBloatFactor(double) configuration becomes irrelevant, because effectively no bloat is allowed.

Parameters:

allowSegmentTiering - if true, when a segment overflows a next tier is allocated to accommodate new entries

Returns:

this builder back

nonTieredSegmentsPercentile

B nonTieredSegmentsPercentile(double nonTieredSegmentsPercentile)

Configures probabilistic fraction of segments, which shouldn't become tiered, if Chronicle Hash size is entries(long), assuming hash code distribution of the keys, inserted into configured Chronicle Hash, is good.

The last caveat means that the configured percentile and affects segment size relying on Poisson distribution law, if inserted entries (keys) fall into all segments randomly. If e. g. the keys, inserted into the Chronicle Hash, are purposely selected to collide by a certain range of hash code bits, so that they all fall into the same segment (a DOS attacker might do this), this segment is obviously going to be tiered.

This configuration affects the actual number of segments, if entries(long) and entriesPerSegment(long) or actualChunksPerSegmentTier(long) are configured. It affects the actual number of entries per segment/chunks per segment tier, if entries(long) and actualSegments(int) are configured. If all 4 configurations, mentioned in this paragraph, are specified, nonTieredSegmentsPercentile doesn't make any effect.

Default value is 0.99999, i. e. if hash code distribution of the keys is good, only one segment of 100K is tiered on average. If your segment size is small and you want to improve memory footprint of Chronicle Hash (probably compromising latency percentiles), you might want to configure more "relaxed" value, e. g. 0.99.

Parameters:

nonTieredSegmentsPercentile - Fraction of segments which shouldn't be tiered

Returns:

this builder back

Throws:

IllegalArgumentException - if nonTieredSegmentsPercentile is out of (0.5, 1.0) range (both bounds are excluded)

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)

actualChunksPerSegmentTier

B actualChunksPerSegmentTier(long actualChunksPerSegmentTier)

Configures the actual number of chunks, that will be reserved for any single segment tier 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:

actualChunksPerSegmentTier - the actual number of chunks, reserved per segment tier 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)

keyReaderAndDataAccess

B keyReaderAndDataAccess(SizedReader<K> keyReader,
                         @NotNull
                         DataAccess<K> keyDataAccess)

Configures the DataAccess and SizedReader used to serialize and deserialize keys to and from off-heap memory in hash containers, created by this builder.

Parameters:

keyReader - the new bytes → key object reader strategy

keyDataAccess - the new strategy of accessing the keys' bytes for writing

Returns:

this builder back

See Also:

keyMarshallers(SizedReader, SizedWriter)

keyMarshallers

B keyMarshallers(@NotNull
                 BytesReader<K> keyReader,
                 @NotNull
                 BytesWriter<? super K> keyWriter)

Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in hash containers, created by this builder.

Parameters:

keyReader - the new bytes → key object reader strategy

keyWriter - the new key object → bytes writer strategy

Returns:

this builder back

See Also:

keyReaderAndDataAccess(SizedReader, DataAccess)

keyMarshaller

<M extends BytesReader<K> & BytesWriter<? super K>> B keyMarshaller(@NotNull
                                                                    M marshaller)

Shortcut for keyMarshallers(marshaller, marshaller).

keyMarshallers

B keyMarshallers(@NotNull
                 SizedReader<K> keyReader,
                 @NotNull
                 SizedWriter<? super K> keyWriter)

Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in hash containers, created by this builder.

Parameters:

keyReader - the new bytes → key object reader strategy

keyWriter - the new key object → bytes writer strategy

Returns:

this builder back

See Also:

keyReaderAndDataAccess(SizedReader, DataAccess)

keyMarshaller

<M extends SizedReader<K> & SizedWriter<? super K>> B keyMarshaller(@NotNull
                                                                    M sizedMarshaller)

Shortcut for keyMarshallers(sizedMarshaller, sizedMarshaller).

Parameters:

sizedMarshaller - implementation of both SizedReader and SizedWriter interfaces

Returns:

this builder back

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

aligned64BitMemoryOperationsAtomic

B aligned64BitMemoryOperationsAtomic(boolean aligned64BitMemoryOperationsAtomic)

Specifies whether on the current combination of platform, OS and Jvm aligned 8-byte reads and writes are atomic or not. By default, Chronicle tries to determine this itself, but if it fails it pessimistically assumes that 64-bit memory operations are not atomic.

Parameters:

aligned64BitMemoryOperationsAtomic - true if aligned 8-byte memory operations are atomic

Returns:

this builder back

checksumEntries

B checksumEntries(boolean checksumEntries)

Configures whether hash containers, created by this builder, should compute and store entry checksums. It is used to detect data corruption during recovery after crashes. See the Entry Checksums section in the Chronicle Map tutorial for more information.

By default, persisted hash containers, created by ChronicleMapBuilder do compute and store entry checksums, but hash containers, created in the process memory via create() - don't.

Parameters:

checksumEntries - if entry checksums should be computed and stored

Returns:

this builder back

See Also:

ChecksumEntry, recoverPersistedTo(File, boolean)

create

H create()

Creates a new hash container from this builder, 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.

Returns:

a new off-heap hash container

See Also:

createPersistedTo(File)

createPersistedTo

H createPersistedTo(File file)
             throws IOException

Opens a hash container residing the specified file, or creates a new one from this builder, if the file doesn't yet exist 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(), createOrRecoverPersistedTo(File), recoverPersistedTo(File, boolean)

createOrRecoverPersistedTo

H createOrRecoverPersistedTo(File file)
                      throws IOException

Recovers and opens the hash container, persisted to the specified file, or creates a new one from this builder, if the file doesn't exist yet, and maps its off-heap memory to the file. In other words, this methods behaves like createPersistedTo(File), if the given file doesn't exist, and recoverPersistedTo(file, true), if the file exists.

Parameters:

file - the persistence file for existing of future hash container

Returns:

a ChronicleHash instance, mapped to the given instance

Throws:

IOException - if any IO error occurs on reading data from the file, or related to off-heap memory allocation or file mapping, or establishing replication connections. Probably the file is corrupted on OS level, and should be recovered on that level first, before calling this procedure.

ChronicleHashRecoveryFailedException - if recovery is impossible

See Also:

createPersistedTo(File), recoverPersistedTo(File, boolean)

recoverPersistedTo

H recoverPersistedTo(File file,
                     boolean sameBuilderConfig)
              throws IOException

Recovers and opens the hash container, persisted to the specified file. This method should be used to open a persisted Chronicle Map after an accessor process crash (that might leave some locks "acquired" therefore some segments inaccessible), or an accessor process external termination (that, in addition to inaccessible segments, might lead to leaks in the Chronicle Hash memory), or a sudden power loss, or a file corruption (that, in addition to the already mentioned consequences, might lead to data corruption, i. e. presence of entries which were never put into the Chronicle Hash).

This method, unlike createPersistedTo(File) or createOrRecoverPersistedTo(File) methods, expects that the mapping file already exists. "Recovery" of the hash container is changing the memory of the data structure so that after the recovery the hash container is in some correct state: with "clean" locks, coherent entry counters, not containing provably corrupt entries, etc. If checksumEntries(true) is configured for the chronicle hash container, recovery procedure checks for each entry that the checksums is correct, otherwise it assumes the entry is corrupt and deletes it from the Chronicle Hash. See the Recovery section in the Chronicle Map tutorial for more information.

At the moment this method is called and executed, no other thread or process should be mapping to the given file, and trying to access the given file.

It is strongly recommended to configure this builder with the same configurations, as the builder, that created the given file for the first time, and pass true as the sameBuilderConfig argument (another requirement is running the same version of the Chronicle Map library). Otherwise, if the header of the given persisted Chronicle Hash file is corrupted, this method is likely to be unable to recover and throw ChronicleHashRecoveryFailedException, or even worse, to corrupt the file further. Fortunately, the header should never be corrupted on an "ordinary" process crash/termination or power loss, only on direct file corruption.

Parameters:

file - a hash container was mapped to the given file

sameBuilderConfig - if this builder is configured with the same configurations, as the builder, which created the file (the persisted Chronicle Hash instance) for the first time, and with the same version of the Chronicle Map library. In this case, the header of the file is overridden (with presumably the same configurations), protecting from ChronicleHashRecoveryFailedException, if the header is corrupted.

Returns:

a recovered Chronicle Hash instance, mapped to the given file

Throws:

FileNotFoundException - if the file doesn't exist

IOException - if any IO error occurs on reading data from the file, or related to off-heap memory allocation or file mapping, or establishing replication connections. Probably the file is corrupted on OS level, and should be recovered on that level first, before calling this procedure.

ChronicleHashRecoveryFailedException - if recovery is impossible

See Also:

createOrRecoverPersistedTo(File), createPersistedTo(File)

privateAPI

@Deprecated
Object privateAPI()

Deprecated. don't use private API in the client code