mirror of
https://github.com/OpenHFT/Chronicle-Map.git
synced 2021-09-13 01:26:12 +00:00
Some Javadocs for replication stuff [dc]
This commit is contained in:
@@ -16,10 +16,46 @@
|
||||
|
||||
package net.openhft.chronicle.hash.replication;
|
||||
|
||||
import net.openhft.chronicle.hash.ChronicleHash;
|
||||
import net.openhft.chronicle.hash.ChronicleHashBuilder;
|
||||
import net.openhft.chronicle.hash.ChronicleHashInstanceConfig;
|
||||
import net.openhft.chronicle.map.ChronicleMap;
|
||||
import net.openhft.chronicle.set.ChronicleSet;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
|
||||
/**
|
||||
* This class holds all configurations of
|
||||
* <a href="https://github.com/OpenHFT/Chronicle-Map#multiple-chronicle-maps---network-distributed">
|
||||
* multicontainer replication</a>, which is usable, when you want to replicate several {@linkplain
|
||||
* ChronicleHash ChronicleHashes} ({@linkplain ChronicleMap maps}, {@linkplain ChronicleSet sets},
|
||||
* etc.) between same servers. {@code ReplicationHub} allows to share TCP/UDP connection, sockets,
|
||||
* buffers, worker threads for that, considerably reducing resources usage and increasing cumulative
|
||||
* (for all replicated containers) replication throughput. See
|
||||
* <a href="https://github.com/OpenHFT/Chronicle-Map#multiple-chronicle-maps---network-distributed">
|
||||
* the corresponding section in ChronicleMap manual</a> for more information.
|
||||
*
|
||||
* <p>Create instances of this class using this pattern: <pre>{@code
|
||||
* ReplicationHub hub = ReplicationHub.builder()
|
||||
* .tcpTransportAndNetwork(tcpConfig)
|
||||
* // more configurations...
|
||||
* .createWithId(identifierOfThisServerWithinTheChronicleReplicationNetwork);}</pre>
|
||||
* Then, given you prepared a {@link ChronicleHashBuilder builder} to create a {@link ChronicleHash
|
||||
* }, configure it's replication via channel of this hub like this: <pre>{@code
|
||||
* ChronicleMap myMap = builder.instance()
|
||||
* .replicatedViaChannel(hub.createChannel(myMapChannelId))
|
||||
* .persistedTo(myMapFile) // optional, for this example
|
||||
* .create();}</pre>
|
||||
*
|
||||
* @see ChronicleHashInstanceConfig#replicatedViaChannel(ReplicationChannel)
|
||||
* @see ReplicationChannel
|
||||
*/
|
||||
public final class ReplicationHub extends AbstractReplication {
|
||||
|
||||
/**
|
||||
* Creates and returns a new {@link ReplicationHub.Builder}.
|
||||
*
|
||||
* @return a new {@link ReplicationHub.Builder}
|
||||
*/
|
||||
@NotNull
|
||||
public static Builder builder() {
|
||||
return new Builder();
|
||||
@@ -34,14 +70,48 @@ public final class ReplicationHub extends AbstractReplication {
|
||||
channels = new ReplicationChannel[builder.maxNumberOfChronicles];
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the maximum {@linkplain ChronicleHashBuilder#entrySize(int) entry size} of {@link
|
||||
* ChronicleHash}es, replicated by this {@code ReplicationHub}, could have. {@code
|
||||
* RuntimeException} is thrown on attempt to replicate with this {@code ReplicationHub}
|
||||
* a {@code ChronicleHash} with larger entry size.
|
||||
*
|
||||
* @return the maximum entry size
|
||||
* @see Builder#maxEntrySize(int)
|
||||
*/
|
||||
public int maxEntrySize() {
|
||||
return maxEntrySize;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the maximum number of channels could be {@linkplain #createChannel(short) created}
|
||||
* for this {@code ReplicationHub}.
|
||||
*
|
||||
* @return the maximum number of channels
|
||||
* @see Builder#maxNumberOfChannels()
|
||||
* @see #createChannel(short)
|
||||
*/
|
||||
public int maxNumberOfChannels() {
|
||||
return channels.length;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a new {@link ReplicationChannel} in this {@code ReplicationHub} with the given
|
||||
* identifier. Identifier shouldn't be lesser than zero and greater or equal to
|
||||
* {@code maxNumberOfChannels() - 1}. On a {@code ReplicationHub} instance,
|
||||
* {@code ReplicationChannel} could be created only once for each possible {@code channelId}
|
||||
* value.
|
||||
*
|
||||
* @param channelId the identifier of the channel. Should be equal for replicated containers
|
||||
* on different nodes (servers)
|
||||
* @return a new {@code ReplicationChannel} instance, in fact just incapsulating the given
|
||||
* {@code channelId} for this {@code ReplicationHub}
|
||||
* @throws IllegalArgumentException if the specified {@code channelId} is out of<br>
|
||||
* <code>[0, {@link #maxNumberOfChannels()})</code> range
|
||||
* @throws IllegalStateException if {@code ReplicationChannel} with the specified
|
||||
* {@code channelId} has already been acquired on this {@code ReplicationHub}
|
||||
* @see ReplicationChannel
|
||||
*/
|
||||
public synchronized ReplicationChannel createChannel(short channelId) {
|
||||
if (channelId < 0)
|
||||
throw new IllegalArgumentException("channelId should be positive");
|
||||
@@ -49,25 +119,50 @@ public final class ReplicationHub extends AbstractReplication {
|
||||
throw new IllegalArgumentException("maxNumberOfChannels is configured (or defaulted) " +
|
||||
"to " + maxNumberOfChannels() + ", channelId=" + channelId + " is requested");
|
||||
if (channels[channelId] != null)
|
||||
throw new IllegalArgumentException("The requested channelId=" + channelId +
|
||||
throw new IllegalStateException("The requested channelId=" + channelId +
|
||||
" is already in use");
|
||||
ReplicationChannel channel = new ReplicationChannel(this, channelId);
|
||||
channels[channelId] = channel;
|
||||
return channel;
|
||||
}
|
||||
|
||||
/**
|
||||
* Builder of {@link ReplicationHub}s.
|
||||
*/
|
||||
public static final class Builder extends AbstractReplication.Builder<ReplicationHub, Builder> {
|
||||
private int maxEntrySize = 1024;
|
||||
private int maxNumberOfChronicles = 128;
|
||||
|
||||
private Builder() {}
|
||||
|
||||
/**
|
||||
* Configures the maximum {@linkplain ChronicleHashBuilder#entrySize(int) entry size} of
|
||||
* {@link ChronicleHash}es, replicated via {@code ReplicationHub}s, created by this builder.
|
||||
*
|
||||
* <p>Default value is {@code 1024}.
|
||||
*
|
||||
* @param maxEntrySize {@link ReplicationHub#maxEntrySize()} of {@link ReplicationHub}s,
|
||||
* created by this builder
|
||||
* @return this builder object back, for chaining
|
||||
* @see ReplicationHub#maxEntrySize()
|
||||
*/
|
||||
@NotNull
|
||||
public Builder maxEntrySize(int maxEntrySize) {
|
||||
this.maxEntrySize = maxEntrySize;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Configures the maximum number of channels could be {@linkplain #createChannel(short)
|
||||
* created for {@code ReplicationHub}s, created by this builder.
|
||||
*
|
||||
* <p>Default value is {@code 128}.
|
||||
*
|
||||
* @param maxNumberOfChannels {@link ReplicationHub#maxNumberOfChannels()} of
|
||||
* {@link ReplicationHub}s, created by this builder
|
||||
* @return this builder object back, for chaining
|
||||
* @see ReplicationHub#maxNumberOfChannels()
|
||||
*/
|
||||
@NotNull
|
||||
public Builder maxNumberOfChannels(int maxNumberOfChannels) {
|
||||
this.maxNumberOfChronicles = maxNumberOfChannels;
|
||||
|
||||
Reference in New Issue
Block a user