org.tools4j.nobark.queue.ConflationQueueBuilder Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of tools4j-nobark Show documentation
Show all versions of tools4j-nobark Show documentation
A library with low latency zero gc data structures and utilities.
The newest version!
/**
* The MIT License (MIT)
*
* Copyright (c) 2019 nobark (tools4j), Marco Terzer, Anton Anufriev
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package org.tools4j.nobark.queue;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.Queue;
import java.util.function.Supplier;
/**
* Builder for the different types of conflation queues serving as alternative to the queue constructors; a builder is
* returned by the static methods of this interface.
*
* @param the type of the conflation key
* @param the type of elements in the queue
*/
public interface ConflationQueueBuilder {
/**
* Creates an initial builder; use this method only when conflation keys are not known in advance
*
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ConflationQueueBuilder builder() {
return new ConflationQueueBuilderImpl.DefaultBuilder<>();
}
/**
* Creates an initial builder; use this method only when conflation keys are not known in advance.
*
* @param keyType the type of the conflation key, used only to infer the generic type of the builder
* @param valueType the type of elements in the queue, used only to infer the generic type of the builder
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ConflationQueueBuilder builder(@SuppressWarnings("unused") final Class keyType,
@SuppressWarnings("unused") final Class valueType) {
return new ConflationQueueBuilderImpl.DefaultBuilder<>();
}
/**
* Creates an initial builder; use this method only when conflation keys are not known in advance. If multiple
* producers are used, the map returned by the given map factory should be thread-safe.
*
* @param entryMapFactory the factory to create the map that manages entries per conflation key
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ConflationQueueBuilder builder(final Supplier> entryMapFactory) {
return new ConflationQueueBuilderImpl.EntryMapFactoryBuilder<>(entryMapFactory);
}
/**
* Creates an initial builder; use this method only when conflation keys are not known in advance. If multiple
* producers are used, the map returned by the given map factory should be thread-safe.
*
* @param keyType the type of the conflation key, used only to infer the generic type of the builder
* @param valueType the type of elements in the queue, used only to infer the generic type of the builder
* @param entryMapFactory the factory to create the map that manages entries per conflation key
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ConflationQueueBuilder builder(@SuppressWarnings("unused") final Class keyType,
@SuppressWarnings("unused") final Class valueType,
final Supplier> entryMapFactory) {
return new ConflationQueueBuilderImpl.EntryMapFactoryBuilder<>(entryMapFactory);
}
/**
* Creates an initial builder given all conflation keys (exhaustive!).
*
* @param allConflationKeys an exhaustive list of all conflation keys that will ever be used for the queue
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
@SafeVarargs
static ConflationQueueBuilder declareAllConflationKeys(final K... allConflationKeys) {
//NOTE: this creates garbage
return declareAllConflationKeys(Arrays.asList(allConflationKeys));
}
/**
* Creates an initial builder given all conflation keys (exhaustive!).
*
* @param allConflationKeys an exhaustive list of all conflation keys that will ever be used for the queue
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ConflationQueueBuilder declareAllConflationKeys(final List allConflationKeys) {
return new ConflationQueueBuilderImpl.DeclaredKeysBuilder<>(allConflationKeys);
}
/**
* Creates an initial builder given all conflation keys (exhaustive!).
*
* @param allConflationKeys an exhaustive list of all conflation keys that will ever be used for the queue
* @param valueType the type of elements in the queue, used only to infer the generic type of the builder
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ConflationQueueBuilder declareAllConflationKeys(final List allConflationKeys,
@SuppressWarnings("unused") final Class valueType) {
return new ConflationQueueBuilderImpl.DeclaredKeysBuilder<>(allConflationKeys);
}
/**
* Creates an initial builder given the enum conflation key class.
*
* @param keyType the type of the conflation key
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ,V> ConflationQueueBuilder forEnumConflationKey(final Class keyType) {
return new ConflationQueueBuilderImpl.EnumKeyBuilder<>(keyType);
}
/**
* Creates an initial builder given the enum conflation key class.
*
* @param keyType the type of the conflation key
* @param valueType the type of elements in the queue, used only to infer the generic type of the builder
* @param the type of the conflation key
* @param the type of elements in the queue
* @return a new builder
*/
static ,V> ConflationQueueBuilder forEnumConflationKey(final Class keyType,
@SuppressWarnings("unused") final Class valueType) {
return new ConflationQueueBuilderImpl.EnumKeyBuilder<>(keyType);
}
/**
* Register a listener as created by the specified supplier when creating queue appenders. The created listeners
* must be thread safe for multi-producer queues, e.g. consider using
* {@link AppenderListener#threadLocalSupplier(Supplier)}.
*
* @param listenerSupplier a listener supplier acting as listener factory
* @return the builder
*/
ConflationQueueBuilder withAppenderListener(Supplier> listenerSupplier);
/**
* Register a listener as created by the specified supplier when creating queue pollers. The created listeners
* must be thread safe for multi-consumer queues, e.g. consider using
* {@link PollerListener#threadLocalSupplier(Supplier)}.
*
* @param listenerSupplier a listener supplier acting as listener factory
* @return the builder
*/
ConflationQueueBuilder withPollerListener(Supplier> listenerSupplier);
/**
* Switch builder mode to create a conflation queue that allows exchanging of elements between the consumer and the
* producer, that is, the builder will now create a {@link ExchangeConflationQueue}.
*
* @return a builder for an {@link ExchangeConflationQueue}, more specifically an {@link EvictConflationQueue}
* @see ExchangeConflationQueue
* @see EvictConflationQueue
* @see #withMerging(Merger)
*/
ExchangeConflationQueueBuilder withExchangeValueSupport();
/**
* Switch builder mode to create a conflation queue that supports merging of old and new values when conflation
* occurs, that is, the builder will now create a {@link MergeConflationQueue}.
*
* @param merger merge strategy to use when conflation occurs
* @return a builder for an {@link ExchangeConflationQueue}, more specifically a {@link MergeConflationQueue}
* @see ExchangeConflationQueue
* @see MergeConflationQueue
* @see #withExchangeValueSupport()
*/
ExchangeConflationQueueBuilder withMerging(Merger merger);
/**
* Builds and returns a new conflation queue instance using the given queue factory for the backing queue. The
* backing queue determines whether single or multiple producers and consumers are supported.
*
* @param queueFactory the factory to create the backing queue
* @return a new conflation queue instance
*/
ConflationQueue build(Supplier> queueFactory);
/**
* Builder for {@link ExchangeConflationQueue} subtypes.
*
* @param the type of the conflation key
* @param the type of elements in the queue
*/
interface ExchangeConflationQueueBuilder {
/**
* Register a listener as created by the specified supplier when creating queue appenders. The created listeners
* must be thread safe for multi-producer queues, e.g. consider using
* {@link AppenderListener#threadLocalSupplier(Supplier)}.
*
* @param listenerSupplier a listener supplier acting as listener factory
* @return the builder
*/
ExchangeConflationQueueBuilder withAppenderListener(Supplier> listenerSupplier);
/**
* Register a listener as created by the specified supplier when creating queue pollers. The created listeners
* must be thread safe for multi-consumer queues, e.g. consider using
* {@link PollerListener#threadLocalSupplier(Supplier)}.
*
* @param listenerSupplier a listener supplier acting as listener factory
* @return the builder
*/
ExchangeConflationQueueBuilder withPollerListener(Supplier> listenerSupplier);
/**
* Builds and returns a new exchange conflation queue instance using the given queue factory for the backing
* queue. The backing queue determines whether single or multiple producers and consumers are supported.
*
* @param queueFactory the factory to create the backing queue
* @return a new exchange conflation queue instance
*/
ExchangeConflationQueue build(Supplier> queueFactory);
}
}