org.onosproject.store.service.EventuallyConsistentMapBuilder Maven / Gradle / Ivy
/*
* Copyright 2015 Open Networking Laboratory
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.onosproject.store.service;
import org.onlab.util.KryoNamespace;
import org.onosproject.cluster.NodeId;
import org.onosproject.store.Timestamp;
import java.util.Collection;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;
import java.util.function.BiFunction;
/**
* Builder for eventually consistent maps.
*
* @param type for map keys
* @param type for map values
*/
public interface EventuallyConsistentMapBuilder {
/**
* Sets the name of the map.
*
* Each map is identified by a string map name. EventuallyConsistentMapImpl
* objects in different JVMs that use the same map name will form a
* distributed map across JVMs (provided the cluster service is aware of
* both nodes).
*
*
* Note: This is a mandatory parameter.
*
*
* @param name name of the map
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withName(String name);
/**
* Sets a serializer builder that can be used to create a serializer that
* can serialize both the keys and values put into the map. The serializer
* builder should be pre-populated with any classes that will be put into
* the map.
*
* Note: This is a mandatory parameter.
*
*
* @param serializerBuilder serializer builder
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withSerializer(
KryoNamespace.Builder serializerBuilder);
/**
* Sets the function to use for generating timestamps for map updates.
*
* The client must provide an {@code BiFunction}
* which can generate timestamps for a given key. The function is free
* to generate timestamps however it wishes, however these timestamps will
* be used to serialize updates to the map so they must be strict enough
* to ensure updates are properly ordered for the use case (i.e. in some
* cases wallclock time will suffice, whereas in other cases logical time
* will be necessary).
*
*
* Note: This is a mandatory parameter.
*
*
* @param timestampProvider provides a new timestamp
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withTimestampProvider(
BiFunction timestampProvider);
/**
* Sets the executor to use for processing events coming in from peers.
*
* @param executor event executor
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withEventExecutor(
ExecutorService executor);
/**
* Sets the executor to use for sending events to peers.
*
* @param executor event executor
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withCommunicationExecutor(
ExecutorService executor);
/**
* Sets the executor to use for background anti-entropy tasks.
*
* @param executor event executor
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withBackgroundExecutor(
ScheduledExecutorService executor);
/**
* Sets a function that can determine which peers to replicate updates to.
*
* The default function replicates to all nodes.
*
*
* @param peerUpdateFunction function that takes a K, V input and returns
* a collection of NodeIds to replicate the event
* to
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withPeerUpdateFunction(
BiFunction> peerUpdateFunction);
/**
* Prevents this map from writing tombstones of items that have been
* removed. This may result in zombie items reappearing after they have
* been removed.
*
* The default behavior is tombstones are enabled.
*
*
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withTombstonesDisabled();
/**
* Configures how often to run the anti-entropy background task.
*
* The default anti-entropy period is 5 seconds.
*
*
* @param period anti-entropy period
* @param unit time unit for the period
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withAntiEntropyPeriod(
long period, TimeUnit unit);
/**
* Configure anti-entropy to converge faster at the cost of doing more work
* for each anti-entropy cycle. Suited to maps with low update rate where
* convergence time is more important than throughput.
*
* The default behavior is to do less anti-entropy work at the cost of
* slower convergence.
*
*
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withFasterConvergence();
/**
* Configure the map to persist data to disk.
*
* The default behavior is no persistence
*
*
* @return this EventuallyConsistentMapBuilder
*/
EventuallyConsistentMapBuilder withPersistence();
/**
* Builds an eventually consistent map based on the configuration options
* supplied to this builder.
*
* @return new eventually consistent map
* @throws java.lang.RuntimeException if a mandatory parameter is missing
*/
EventuallyConsistentMap build();
}