E - element type of the sets, created by this builderpublic final class ChronicleSetBuilder<E> extends Object implements ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>
ChronicleSetBuilder manages the whole set of ChronicleSet configurations, could
be used as a classic builder and/or factory.
ChronicleMapBuilder is mutable, see a note in ChronicleHashBuilder interface documentation.
ChronicleSet,
ChronicleMapBuilder| Modifier and Type | Method and Description |
|---|---|
ChronicleSetBuilder<E> |
actualChunkSize(int actualChunkSize)
Configures the size in bytes of allocation unit of hash container instances, created by this
builder.
|
ChronicleSetBuilder<E> |
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.
|
ChronicleSetBuilder<E> |
actualSegments(int actualSegments)
Configures the actual number of segments in the hash containers, created by this builder.
|
ChronicleSetBuilder<E> |
averageKeySize(double averageKeySize)
Configures the average number of bytes, taken by serialized form of keys, put into hash
containers, created by this builder.
|
ChronicleSetBuilder<E> |
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. |
ChronicleSetBuilder<E> |
clone()
Clones this builder.
|
ChronicleSetBuilder<E> |
constantKeySizeBySample(E sampleKey)
Configures the constant number of bytes, taken by serialized form of keys, put into hash
containers, created by this builder.
|
ChronicleSet<E> |
create()
Creates a new hash container, storing it's data in off-heap memory, not mapped to any file.
|
ChronicleSet<E> |
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.
|
ChronicleSetBuilder<E> |
entries(long entries)
Configures the maximum number of entries, that could be inserted into the hash containers,
created by this builder.
|
ChronicleSetBuilder<E> |
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.
|
boolean |
equals(Object o) |
ChronicleSetBuilder<E> |
errorListener(ChronicleHashErrorListener errorListener) |
int |
hashCode() |
ChronicleSetBuilder<E> |
immutableKeys()
Specifies that key objects, queried with the hash containers, created by this builder, are
inherently immutable.
|
ChronicleHashInstanceBuilder<ChronicleSet<E>> |
instance() |
ChronicleSetBuilder<E> |
keyDeserializationFactory(ObjectFactory<E> 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. |
ChronicleSetBuilder<E> |
keyMarshaller(BytesMarshaller<? super E> keyMarshaller)
Configures the
BytesMarshaller used to serialize/deserialize keys to/from off-heap
memory in hash containers, created by this builder. |
ChronicleSetBuilder<E> |
keyMarshallers(BytesWriter<E> keyWriter,
BytesReader<E> keyReader)
Configures the marshallers, used to serialize/deserialize keys to/from off-heap memory in
hash containers, created by this builder.
|
ChronicleSetBuilder<E> |
keySizeMarshaller(SizeMarshaller keySizeMarshaller)
Configures the marshaller used to serialize actual key sizes to off-heap memory in hash
containers, created by this builder.
|
ChronicleSetBuilder<E> |
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.
|
ChronicleSetBuilder<E> |
maxChunksPerEntry(int maxChunksPerEntry)
Configures how many chunks a single entry, inserted into
ChronicleHashes, created
by this builder, could take. |
ChronicleSetBuilder<E> |
metaDataBytes(int metaDataBytes) |
ChronicleSetBuilder<E> |
minSegments(int minSegments)
Set minimum number of segments in hash containers, constructed by this builder.
|
ChronicleSetBuilder<E> |
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> ChronicleSetBuilder<K> |
of(Class<K> keyClass) |
ChronicleSetBuilder<E> |
replication(byte identifier) |
ChronicleSetBuilder<E> |
replication(byte identifier,
TcpTransportAndNetworkConfig tcpTransportAndNetwork)
Shortcut for
replication(SimpleReplication.builder() .tcpTransportAndNetwork(tcpTransportAndNetwork).createWithId(identifier)). |
ChronicleSetBuilder<E> |
replication(SingleChronicleHashReplication replication)
Configures replication of the hash containers, created by this builder.
|
ChronicleSetBuilder<E> |
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() |
public static <K> ChronicleSetBuilder<K> of(Class<K> keyClass)
public ChronicleSetBuilder<E> clone()
ChronicleHashBuilderChronicleHashBuilders are mutable and changed on each configuration method call. Original
and cloned builders are independent.clone in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>clone in class Objectpublic ChronicleSetBuilder<E> actualSegments(int actualSegments)
ChronicleHashBuilderChronicleHashBuilder.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.
actualSegments in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>actualSegments - the actual number of segments in hash containers, created by
this builderChronicleHashBuilder.minSegments(int),
ChronicleHashBuilder.entriesPerSegment(long)public ChronicleSetBuilder<E> minSegments(int minSegments)
ChronicleHashBuilderConcurrentHashMap.minSegments in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>minSegments - the minimum number of segments in containers, constructed by this builderpublic ChronicleSetBuilder<E> entriesPerSegment(long entriesPerSegment)
ChronicleHashBuilderChronicleHashBuilder.entries(long) configuration.
This is a low-level configuration.
entriesPerSegment in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>entriesPerSegment - the actual maximum number entries per segment in the
hash containers, created by this builderChronicleHashBuilder.entries(long),
ChronicleHashBuilder.actualSegments(int)public ChronicleSetBuilder<E> actualChunksPerSegment(long actualChunksPerSegment)
ChronicleHashBuilderChronicleHashBuilder.entriesPerSegment(long). Makes sense only if ChronicleHashBuilder.actualChunkSize(int),
ChronicleHashBuilder.actualSegments(int) and ChronicleHashBuilder.entriesPerSegment(long) are also configured
manually.actualChunksPerSegment in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>actualChunksPerSegment - the actual number of segments, reserved per segment in the
hash containers, created by this builderpublic ChronicleSetBuilder<E> averageKeySize(double averageKeySize)
ChronicleHashBuilder.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.
Example: if keys in your set(s) are English words in String form, average English
word length is 5.1, configure average key size of 6:
ChronicleSet<String> uniqueWords = ChronicleSetBuilder.of(String.class)
.entries(50000)
.averageKeySize(6)
.create();(Note that 6 is chosen as average 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 ChronicleSet.)
averageKeySize in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>averageKeySize - constantKeySizeBySample(Object),
actualChunkSize(int)public ChronicleSetBuilder<E> constantKeySizeBySample(E 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.averageKeySize(double) should be called instead of
this one.
For example, if your keys are Git commit hashes:
Set<byte[]> gitCommitsOfInterest = ChronicleSetBuilder.of(byte[].class)
.constantKeySizeBySample(new byte[20])
.create();constantKeySizeBySample in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>sampleKey - the sample keyChronicleHashBuilder.averageKeySize(double)public ChronicleSetBuilder<E> actualChunkSize(int actualChunkSize)
ChronicleHashBuilderChronicleMap 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.
actualChunkSize in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>actualChunkSize - the "chunk size" in bytesChronicleHashBuilder.entries(long),
ChronicleHashBuilder.maxChunksPerEntry(int)public ChronicleSetBuilder<E> maxChunksPerEntry(int maxChunksPerEntry)
ChronicleHashBuilderChronicleHashes, 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 ChronicleHashBuilder.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.maxChunksPerEntry in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>maxChunksPerEntry - how many chunks a single entry could span at mostChronicleHashBuilder.actualChunkSize(int)public ChronicleSetBuilder<E> entries(long entries)
ChronicleHashBuilderIllegalStateException
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).
entries in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>entries - maximum size of the maps or sets, created by this builderpublic ChronicleSetBuilder<E> lockTimeOut(long lockTimeOut, TimeUnit unit)
ChronicleHashBuilderChronicleHashErrorListener.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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>lockTimeOut - new lock timeout for segments of containers created by this builder, in
the given time unitsunit - time unit of the given lock timeoutpublic ChronicleSetBuilder<E> errorListener(ChronicleHashErrorListener errorListener)
errorListener in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>public ChronicleSetBuilder<E> metaDataBytes(int metaDataBytes)
metaDataBytes in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>public ChronicleSetBuilder<E> timeProvider(TimeProvider timeProvider)
ChronicleHashBuilderDefault time provider is TimeProvider.SYSTEM.
timeProvider in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>timeProvider - a new time provider for replication needsChronicleHashBuilder.replication(SingleChronicleHashReplication)public ChronicleSetBuilder<E> bytesMarshallerFactory(BytesMarshallerFactory bytesMarshallerFactory)
ChronicleHashBuilderBytesMarshallerFactory 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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>bytesMarshallerFactory - the marshaller factory to be used with the default ObjectSerializer, i. e. BytesMarshallableSerializerChronicleHashBuilder.objectSerializer(ObjectSerializer)public ChronicleSetBuilder<E> 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:
Set<Key> set = ChronicleSetBuilder.of(Key.class)
.entries(1_000_000)
.keySize(100)
// this class hasn't implemented yet, just for example
.objectSerializer(new KryoObjectSerializer())
.create();objectSerializer in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>objectSerializer - the serializer used to serialize loosely typed or nullable data if
custom marshaller is not configuredChronicleHashBuilder.bytesMarshallerFactory(BytesMarshallerFactory),
ChronicleHashBuilder.keyMarshaller(BytesMarshaller)public ChronicleSetBuilder<E> keyMarshaller(@NotNull BytesMarshaller<? super E> keyMarshaller)
ChronicleHashBuilderBytesMarshaller 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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>keyMarshaller - the marshaller used to serialize keysChronicleHashBuilder.keyMarshallers(BytesWriter, BytesReader),
ChronicleHashBuilder.objectSerializer(ObjectSerializer)public ChronicleSetBuilder<E> keyMarshallers(@NotNull BytesWriter<E> keyWriter, @NotNull BytesReader<E> keyReader)
ChronicleHashBuilderConfiguring 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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>keyWriter - the new key object → Bytes writer (interop) strategykeyReader - the new Bytes → key object reader strategyChronicleHashBuilder.keyMarshaller(BytesMarshaller)public ChronicleSetBuilder<E> keySizeMarshaller(@NotNull SizeMarshaller keySizeMarshaller)
ChronicleHashBuilderDefault 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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>keySizeMarshaller - the new marshaller, used to serialize actual key sizes to off-heap
memorypublic ChronicleSetBuilder<E> keyDeserializationFactory(@NotNull ObjectFactory<E> keyDeserializationFactory)
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.
Actually this is just a convenience method supporting key marshaller configurations, made
initially during of(Class) call. Because if you configure own custom key marshaller, this method doesn't
take any effect on the maps constructed by this builder.
keyDeserializationFactory in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>keyDeserializationFactory - the key factory used to produce instances to deserialize
data inof(Class)public ChronicleSetBuilder<E> immutableKeys()
ChronicleHashBuilderChronicleMap 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.
immutableKeys in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>public ChronicleSetBuilder<E> replication(SingleChronicleHashReplication replication)
ChronicleHashBuilderBy 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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>replication - the replication configChronicleHashInstanceBuilder.replicated(SingleChronicleHashReplication),
ChronicleHashBuilder.replication(byte, TcpTransportAndNetworkConfig)public ChronicleSetBuilder<E> replication(byte identifier, TcpTransportAndNetworkConfig tcpTransportAndNetwork)
ChronicleHashBuilderreplication(SimpleReplication.builder() .tcpTransportAndNetwork(tcpTransportAndNetwork).createWithId(identifier)).replication in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>identifier - the network-wide identifier of the containers, created by this
buildertcpTransportAndNetwork - configuration of tcp connection and networkChronicleHashBuilder.replication(SingleChronicleHashReplication),
ChronicleHashInstanceBuilder.replicated(byte, TcpTransportAndNetworkConfig)public ChronicleSetBuilder<E> replication(byte identifier)
replication in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>public ChronicleHashInstanceBuilder<ChronicleSet<E>> instance()
instance in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>public ChronicleSet<E> create()
ChronicleHashBuilderChronicleHash.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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>ChronicleHashBuilder.createPersistedTo(File),
ChronicleHashBuilder.instance()public ChronicleSet<E> createPersistedTo(File file) throws IOException
ChronicleHashBuilderMultiple 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<E,ChronicleSet<E>,ChronicleSetBuilder<E>>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(),
ChronicleHashInstanceBuilder.persistedTo(File)Copyright © 2015. All rights reserved.