E - element type of the sets, created by this builderpublic 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> |
actualEntriesPerSegment(long actualEntriesPerSegment) |
ChronicleSetBuilder<E> |
actualSegments(int actualSegments) |
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> |
channel(ChannelProvider.ChronicleChannel chronicleChannel)
Configures replication of the hash containers, created by this builder, via so called
"channels".
|
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.
|
ChronicleSetBuilder<E> |
disableReplication()
Specifies that hash containers, created by this builder, shouldn't replicate their data over
network.
|
ChronicleSetBuilder<E> |
entries(long entries)
Configures the maximum number of "entry size chunks", which
could be taken by the maximum number of entries, inserted into the hash containers, created
by this builder.
|
ChronicleSetBuilder<E> |
entrySize(int entrySize)
Configures the size in bytes of allocation unit of hash container instances, created by this
builder.
|
boolean |
equals(Object o) |
ChronicleSetBuilder<E> |
errorListener(ChronicleHashErrorListener errorListener) |
ChronicleSetBuilder<E> |
file(File file)
Specifies that hash containers us the specified file, if create is called and this is not set
the map will be created in off-heap memory, and changes will not be persisted to disk.
|
int |
hashCode() |
ChronicleSetBuilder<E> |
immutableKeys()
Specifies that key objects, queried with the hash containers, created by this builder, are
inherently immutable.
|
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 in maps,
created by this builder. |
ChronicleSetBuilder<E> |
keyMarshaller(BytesMarshaller<E> keyMarshaller)
Configures the
BytesMarshaller used to serialize/deserialize keys to/from off-heap
memory in hash containers, created by this builder. |
ChronicleSetBuilder<E> |
keySize(int keySize)
Configures the optimal number of bytes, taken by serialized form of keys, put into 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> |
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> |
replicators(byte identifier,
ReplicationConfig... replicators)
Configures replication of the hash containers, created by this builder (via independent
replicators).
|
ChronicleSetBuilder<E> |
stateless(StatelessBuilder statelessBuilder)
Specifies that hash containers, created by this builder, should be a stateless
implementation, this stateless implementation will be referred to as a stateless client as it
will not hold any of its own data locally, the stateless client will perform Remote Procedure
Calls ( RPC ) to another
ChronicleMap or ChronicleSet which we will refer to
as the server. |
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)
actualSegments in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>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> actualEntriesPerSegment(long actualEntriesPerSegment)
actualEntriesPerSegment in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>public ChronicleSetBuilder<E> keySize(int keySize)
ChronicleHashBuilder.constantKeySizeBySample(Object) method instead of this one.
If key size varies moderately, specify the size higher than average, but lower than the maximum possible, to minimize average memory overuse. If key size varies in a wide range, it's better to use entry size in "chunk" mode and configure it directly.
Example: if keys in your set(s) are English words in String form, keys size 10
(a bit more than average English word length) would be a good choice:
ChronicleSet<String> uniqueWords = ChronicleSetBuilder.of(String.class)
.entries(50000)
.keySize(10)
.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 ChronicleSet.)
keySize in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>keySize - number of bytes, taken by serialized form of keysconstantKeySizeBySample(Object),
entrySize(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.keySize(int) or ChronicleHashBuilder.entrySize(int) 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 keykeySize(int)public ChronicleSetBuilder<E> 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 ChronicleMapBuilder.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
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 = ChronicleMapBuilder
.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();In fully default case you can expect entry size to be about 120-130 bytes. But it is strongly recommended always to configure key 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 a few bytes required by implementations.
entrySize in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>entrySize - the "chunk size" in bytesChronicleHashBuilder.entries(long)public ChronicleSetBuilder<E> entries(long entries)
ChronicleHashBuilderIllegalStateException might be
thrown, because currently ChronicleMap and ChronicleSet doesn't support
resizing.
ChronicleMap case) is constant, this number
is equal to the maximum number of entries (because each entry takes exactly one "entry size"
memory unit).ChronicleMap case) size varies
moderately, you should pass to this method the maximum number of entries + 5-25%, depending
on your data properties and configured key/value/entry sizes.ChronicleHashBuilder.entrySize(int) method.You shouldn't put additional margin over the number, computed according the rules above.
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 actual maximum expected number of entries. ChronicleMap and
ChronicleSet don't have a notion of load factor.
Default value is 2^20 (~ 1 million).
entries in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>entries - maximum size of the created maps, in memory allocation units, so-called "entry
size"ChronicleHashBuilder.entrySize(int)public 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> replicators(byte identifier, ReplicationConfig... replicators)
ChronicleHashBuilderAnother way to establish replication is ChronicleHashBuilder.channel(ChannelProvider.ChronicleChannel)
method.
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.channel(ChannelProvider.ChronicleChannel) method.
replicators in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>identifier - the new identifier of the containers,
created by this builderreplicators - several replicators, used to sync the data across replicating nodes
independentlyChronicleHashBuilder.channel(ChannelProvider.ChronicleChannel),
ChronicleHashBuilder.disableReplication()public ChronicleSetBuilder<E> channel(ChannelProvider.ChronicleChannel chronicleChannel)
ChronicleHashBuilderAnother way to establish replication if ChronicleHashBuilder.replicators(byte, ReplicationConfig[])
method.
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 means of this method or ChronicleHashBuilder.replicators(byte, ReplicationConfig[]) method
calls.
channel in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>chronicleChannel - the channel responsible for gathering updates of hash containers,
created by this builder, and replicating them over networkChronicleHashBuilder.replicators(byte, ReplicationConfig[]),
ChronicleHashBuilder.disableReplication()public ChronicleSetBuilder<E> disableReplication()
ChronicleHashBuilderChronicleHashBuilder.replicators(byte, ReplicationConfig[]) or ChronicleHashBuilder.channel(ChannelProvider.ChronicleChannel)
method call.
By default replication is not configured, so this method is useful only to ensure that hash containers, created by some inherited or passed builder, wouldn't replicate. I. e. in rare cases.
disableReplication in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>ChronicleHashBuilder.replicators(byte, ReplicationConfig[]),
ChronicleHashBuilder.channel(ChannelProvider.ChronicleChannel)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.replicators(byte, ReplicationConfig[]),
ChronicleHashBuilder.channel(ChannelProvider.ChronicleChannel)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<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.objectSerializer(ObjectSerializer)public ChronicleSetBuilder<E> keyDeserializationFactory(@NotNull ObjectFactory<E> keyDeserializationFactory)
Byteable, BytesMarshallable or Externalizable subclass in maps,
created by this builder. If custom key
marshaller is configured, this configuration is unused, because it is incapsulated in
BytesMarshaller.read(Bytes) method (without provided instance to read the data into),
i. e. it's is the user-side responsibility.
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> stateless(StatelessBuilder statelessBuilder)
ChronicleHashBuilderChronicleMap or ChronicleSet which we will refer to
as the server. The server will hold all your data, the server can not it’s self be a
stateless client. Your stateless client must be connected to the server via TCP/IP. The
stateless client will delegate all your method calls to the remote sever. The stateless
client operations will block, in other words the stateless client will wait for the server to
send a response before continuing to the next operation. The stateless client could be
consider to be a ClientProxy to ChronicleMap or ChronicleSet running on
another hoststateless in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>statelessBuilder - Stateless Client Config, null demotes no statelessBuilderpublic ChronicleSetBuilder<E> file(File file) throws IOException
ChronicleHashBuilderfile 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 the file cannot be created and read.ChronicleHash.file(),
ChronicleHash.close()public ChronicleSet<E> create() throws IOException
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.create in interface ChronicleHashBuilder<E,ChronicleSet<E>,ChronicleSetBuilder<E>>IOException - if any IO error relates to off-heap memory allocation occursChronicleHashBuilder.create()Copyright © 2014. All rights reserved.