Package org.infinispan.persistence.spi

Interface NonBlockingStore<K,​V>

  • Type Parameters:
    K - key value type
    V - value value type
    All Known Subinterfaces:
    ExternalNonBlockingStore<K,​V>
    @Experimental
public interface NonBlockingStore<K,​V>
    The contract for defining a way for a cache to interface with external source of data, such as a database, filesystem etc. As the name implies, all of the methods in this class must never block the invoking thread.

    The first method that will be invoked on this store will be the start(InitializationContext) to allow it to initialize and startup. Once the returned stage has completed the store is assumed to be in working state and is ready to handle operations. Infinispan guarantees the visibility of variables written during the start method, so there is no need to synchronize these manually, unless they are mutated in the normal operations of the store itself.

    After the store has started, Infinispan will utilise the characteristics() method to query the store's characteristics. It is highly recommended that this method never change the values it returns once the store has been started as these may or may not be cached. For more information on how the characteristics affect the store operations, please see NonBlockingStore.Characteristic and its various values.

    By default this interface only requires half a dozen or so methods to be implemented. However, there are more optional methods that may be implemented. If you implement such a method, please be sure to advertise the appropriate characteristic for that method, so Infinispan knows to invoke it. If Infinispan has been told a characteristic is available and the method is not overridden, an UnsupportedOperationException will be thrown when trying to invoke the appropriate method. Each NonBlockingStore.Characteristic defines what methods map to which characteristic.

    Although recommended, Segmentation support in a store implementation is not required. Segment parameters are provided for all methods where segment information would be required, for example load(int, Object) and {@link #publishEntries(IntSet, Predicate, boolean). When a store does not support segmentation, these parameters can simply be ignored by the implementation. As previously stated, it's recommended that segmentation is supported as an Infinispan cache can perform much more efficiently when segmentation is supported when performing bulk operations such as Cache.size() or Cache.entrySet().stream(). It also decreases state transfer duration when PersistenceConfiguration.fetchPersistentState() is enabled, as well as the time required to remove data by segments. To indicate that a store implementation supports segmentation, it's necessary that the NonBlockingStore.Characteristic.SEGMENTABLE characteristic is returned via the characteristics() method. A store implementation can tell if segmentation is enabled by checking the store configuration StoreConfiguration.segmented() available from the InitializationContext.

    A store implementation may have to interact with blocking APIs to perform their required operations, however we should never block the invoking thread, therefore Infinispan provides a utility helper for these operations. This is the BlockingManager and may be obtained by invoking InitializationContext.getBlockingManager() on the provided context in the start method. This utility class comes with an assortment of methods ranging from equivalent methods for more commonly used methods such as CompletableFuture.supplyAsync(Supplier, Executor) to a wrapper around a Publisher that ensures it is subscribed and obversed on the proper threads. The BlockingManager is special in that it guarantees the code that is blocking is ran on a blocking thread but any stages it produces are continued on a non blocking thread, which is very important to not leak blocking threads to the internal Infinispan system.

    Implementations of this store must be thread safe if concurrent operations are performed on it. The one exception is that start(InitializationContext) and stop() will not be invoked concurrently with other operations.

    Note that this interface is Experimental and its methods may change slightly over time until it has matured.

    Since:
    11.0
    Author:
    William Burns

    • Method Detail

      • start

        CompletionStage<Void> start​(InitializationContext ctx)
        The first method that will be invoked to allow the store to be configured and for any additional steps, such as connecting via a socket or opening file descriptors, to be performed.

        The provided InitializationContext contains many helpful objects, including the configuration of the cache and store, concurrency utilities such as BlockingManager or an executor reserved for non blocking operations only InitializationContext.getNonBlockingExecutor().

        This method is guaranteed to not be invoked concurrently with other operations. This means another method will not be invoked on this store until after the returned Stage completes.

        It is expected that an implementation should be able to "restart" by invoking start a second time if stop() has been invoked and allowed for its stage to complete.

        Parameters:
        ctx - initialization context used to initialize this store
        Returns:
        a stage that when complete signals that this store has been successfully started

      • stop

        CompletionStage<Void> stop()
        This method will be invoked when the cache is being shutdown. It is expected that all resources related to the store to be freed upon completion of the returned stage.

        This method is guaranteed to not be invoked concurrently with other operations. This also means another method will not be invoked on this store until after the returned Stage completes.

        It is expected that an implementation should be able to "restart" by invoking start(InitializationContext) a second time if stop has been invoked and allowed for its stage to complete.

        Returns:
        a stage that when complete signals that this store has been stopped

      • characteristics

        default Set<NonBlockingStore.Characteristic> characteristics()
        Returns a set of characteristics for this store and its elements. This method may be invoked multiple times to determine which methods of the store can be used and how its data can be handled.

        Please see NonBlockingStore.Characteristic and its values for a description of what each characteristic declares the store as supporting.

        Returns:
        the set of characteristics that this store supports

      • isAvailable

        default CompletionStage<Boolean> isAvailable()
        Returns a stage that when complete returns a boolean indicating whether the current store can be accessed for requests. This can be useful for store implementations that rely on an external source, such as a remote database, that may become unreachable. This can reduce sending requests to a store that is not available, as subsequent cache requests will result in a StoreUnavailableException being thrown until the store becomes available again.

        Store availability is is polled periodically to update a store's status if it's availability changes. This method will not be invoked concurrently with itself (ie. this method will not be invoked until after the previous stage has completed), but will be invoked concurrently with other operations, excluding start(InitializationContext) and stop().

        If a store is configured to be StoreConfiguration.async() and the store becomes unavailable, then it's possible for the cache operations to be accepted in the interim period between the loss of availability and the modification-queue becoming full. This allows for this store to be unavailable for short periods of time without a StoreUnavailableException being thrown, however if the store does not become available before the queue fills, then a StoreUnavailableException is eventually thrown.

        Returns:
        stage that when complete signals if the store is available

      • containsKey

        default CompletionStage<Boolean> containsKey​(int segment,
                                             Object key)
        Returns a stage that will contain whether the value can be found in the store.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.WRITE_ONLY This method will never be invoked
        NonBlockingStore.Characteristic.EXPIRATION When set this method must not return true if the entry was expired
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided segment parameter may be ignored

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        segment - the segment for the given key if segmentation is enabled otherwise 0
        key - key of the entry to check
        Returns:
        a stage that when complete contains a boolean stating if the value is contained in the store

      • write

        CompletionStage<Void> write​(int segment,
                            MarshallableEntry<? extends K,​? extends V> entry)
        Writes the entry to the store for the given segment returning a stage that completes normally when it is finished.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.READ_ONLY This method will never be invoked
        NonBlockingStore.Characteristic.EXPIRATION When set this method must store the expiration metadata
        NonBlockingStore.Characteristic.SEGMENTABLE When set this method must ensure the segment is stored with the entry

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        segment - the segment for the given key if segmentation is enabled otherwise 0
        entry - the entry to persist to the store
        Returns:
        a stage that when complete signals that the store has written the value

      • delete

        CompletionStage<Boolean> delete​(int segment,
                                Object key)
        Removes the entry for given key and segment from the store returning a stage that when completes normally contains whether the entry was actually removed or not.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.READ_ONLY This method will never be invoked
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided segment parameter may be ignored

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        segment - the segment for the given key if segmentation is enabled otherwise 0
        key - key of the entry to delete from the store
        Returns:
        a stage that when complete contains a boolean stating if the value was removed from the store

      • addSegments

        default CompletionStage<Void> addSegments​(IntSet segments)
        Invoked when a node becomes an owner of the given segments. Some store implementations may require initializing additional resources when a new segment is required. For example a store could store entries in a different file per segment.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.SHAREABLE If the store has this characteristic and is configured to be StoreConfiguration.shared(), this method will never be invoked
        NonBlockingStore.Characteristic.SEGMENTABLE This method is only invoked if the store has this characteristic

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        segments - the segments to add
        Returns:
        a stage that when complete signals that the segments have been added

      • removeSegments

        default CompletionStage<Void> removeSegments​(IntSet segments)
        Invoked when a node loses ownership of the given segments. A store must then remove any entries that map to the given segments and can remove any resources related to the given segments. For example a database store can delete rows of the given segment or a file based store may delete files related to the given segments.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.SHAREABLE If the store has this characteristic and is configured to be StoreConfiguration.shared(), this method will never be invoked
        NonBlockingStore.Characteristic.SEGMENTABLE This method is only invoked if the store has this characteristic

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        segments - the segments to remove
        Returns:
        a stage that when complete signals that the segments have been removed

      • clear

        CompletionStage<Void> clear()
        Clears all entries from the store.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.READ_ONLY This method will never be invoked

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Returns:
        a stage that when complete signals that the store has been cleared

      • bulkWrite

        default CompletionStage<Void> bulkWrite​(int publisherCount,
                                        org.reactivestreams.Publisher<NonBlockingStore.SegmentedPublisher<MarshallableEntry<K,​V>>> publisher)
        Writes the entries provided by the publisher into the underlying store. The Publisher will provide a NonBlockingStore.SegmentedPublisher for every segment in the batch, which contains at least one entry that maps to the segment for the SegmentPublisher.

        The publisher may publish up to publisherCount publishers where each publisher is separated by the segment each entry maps to. Failure to request at least publisherCount publishers from the Publisher may cause a deadlock. Many reactive tools have methods such as flatMap that take an argument of how many concurrent subscriptions it manages, which is perfectly matched with this argument.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.READ_ONLY This method will never be invoked
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided publisherCount parameter will be one and there will only be one SegmentedPublisher to subscribe to

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        publisherCount - how many SegmentedPublishers the provided Publisher may publish
        publisher - the publisher which will provide a SegmentedPublisher for each segment containing entries
        Returns:
        a stage that when complete signals that the store has written the values

      • bulkDelete

        default CompletionStage<Void> bulkDelete​(int publisherCount,
                                         org.reactivestreams.Publisher<NonBlockingStore.SegmentedPublisher<Object>> publisher)
        Removes the entries for the keys provided by the publisher into the underlying store. The Publisher will provide a NonBlockingStore.SegmentedPublisher, for every segment in the batch, which contains at least one key that maps to the segment for the SegmentPublisher.

        The publisher may publish up to publisherCount publishers where each publisher is separated by the segment each entry maps to. Failure to request at least publisherCount publishers from the Publisher may cause a deadlock. Many reactive tools have methods such as flatMap that take an argument of how many concurrent subscriptions it manages, which is perfectly matched with this argument.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.READ_ONLY This method will never be invoked
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided publisherCount parameter will be one and there will only be one SegmentedPublisher to subscribe to

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        publisherCount - how many SegmentedPublishers the provided Publisher may publish
        publisher - the publisher which will provide a SegmentedPublisher for each segment containing entries
        Returns:
        a stage that when complete signals that the store has deleted the values

      • size

        default CompletionStage<Long> size​(IntSet segments)
        Returns the amount of entries that map to the given segments in the store.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.BULK_READ This method is only invoked if the store has this characteristic
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided segments parameter may be ignored

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        segments - the segments for which the entries are counted
        Returns:
        a stage that when complete contains the count of how many entries are present for the given segments

      • approximateSize

        default CompletionStage<Long> approximateSize​(IntSet segments)
        Returns an estimation of the amount of entries that map to the given segments in the store. This is similar to size(IntSet) except that it may take some liberties in the returned size. That is it may ignore if an entry is expired or if the store has some underlying optimizations to eventually have a consistent size.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.BULK_READ This method is only invoked if the store has this characteristic
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided segments parameter may be ignored

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        segments - the segments for which the entries are counted
        Returns:
        a stage that when complete contains the count of how many entries are present for the given segments

      • publishEntries

        default org.reactivestreams.Publisher<MarshallableEntry<K,​V>> publishEntries​(IntSet segments,
                                                                                   Predicate<? super K> filter,
                                                                                   boolean includeValues)
        Publishes entries from this store that are in one of the provided segments and also pass the provided filter. The returned publisher must support being subscribed to any number of times. That is subsequent invocations of Publisher.subscribe(Subscriber) should provide independent views of the underlying entries to the Subscribers. Entries should not retrieved until a given Subscriber requests them via the Subscription.request(long) method.

        Subscribing to the returned Publisher should not block the invoking thread. It is the responsibility of the store implementation to ensure this occurs. If however the store must block to perform an operation it is recommended to wrap your Publisher before returning with the BlockingManager.blockingPublisher(Publisher) method and it will handle subscription and observation on the blocking and non blocking executors respectively.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.BULK_READ This method is only invoked if the store has this characteristic
        NonBlockingStore.Characteristic.EXPIRATION When set the returned publisher must not return expired entries
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided segments parameter may be ignored
        Parameters:
        segments - A set of segments to filter entries by. This will always be non null.
        filter - A filter to filter they keys by. If this is null then no additional filtering should be done after segments.
        Returns:
        a publisher that will provide the keys from the store

      • publishKeys

        default org.reactivestreams.Publisher<K> publishKeys​(IntSet segments,
                                                     Predicate<? super K> filter)
        Publishes keys from this store that are in one of the provided segments and also pass the provided filter. The returned publisher must support being subscribed to any number of times. That is subsequent invocations of Publisher.subscribe(Subscriber) should provide independent views of the underlying keys to the Subscribers. Keys should not retrieved until a given Subscriber requests them via the Subscription.request(long) method.

        Subscribing to the returned Publisher should not block the invoking thread. It is the responsibility of the store implementation to ensure this occurs. If however the store must block to perform an operation it is recommended to wrap your Publisher before returning with the BlockingManager.blockingPublisher(Publisher) method and it will handle subscription and observation on the blocking and non blocking executors respectively.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.BULK_READ This method is only invoked if the store has this characteristic
        NonBlockingStore.Characteristic.EXPIRATION When set the returned publisher must not return expired keys
        NonBlockingStore.Characteristic.SEGMENTABLE When this is not set the provided segments parameter may be ignored

        Parameters:
        segments - A set of segments to filter keys by. This will always be non null.
        filter - A filter to filter they keys by. If this is null then no additional filtering should be done after segments.
        Returns:
        a publisher that will provide the keys from the store

      • purgeExpired

        default org.reactivestreams.Publisher<MarshallableEntry<K,​V>> purgeExpired()
        Returns a Publisher that when subscribed to will remove any entries that have expired from the store and publishes them to returned Publisher.

        When the Publisher is subscribed to it is expected to do point in time expiration and should not return a Publisher that has infinite entries or never completes.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.EXPIRATION This method is only invoked if the store has this characteristic

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Returns:
        a Publisher that publishes the entries that are expired at the time of subscription

      • prepareWithModifications

        @Experimental
default CompletionStage<Void> prepareWithModifications​(Transaction transaction,
                                                       org.infinispan.persistence.support.BatchModification batchModification)
        Write modifications to the store in the prepare phase, which are not yet persisted until the same transaction is committed via commit(Transaction) or they are discarded if the transaction is rolled back via rollback(Transaction).

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.TRANSACTIONAL This method is only invoked if the store has this characteristic

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        This method will most likely change as the BatchModification does not contain the segment information required for the store to map the entries to.

        Parameters:
        transaction - the current transactional context.
        batchModification - an object containing the write/remove operations required for this transaction.

      • commit

        default CompletionStage<Void> commit​(Transaction transaction)
        Commit the provided transaction's changes to the underlying store.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.TRANSACTIONAL This method is only invoked if the store has this characteristic

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        transaction - the current transactional context.
        Returns:
        a stage that when completed signals that the transaction was committed

      • rollback

        default CompletionStage<Void> rollback​(Transaction transaction)
        Rollback the provided transaction's changes to the underlying store.

        Summary of Characteristics Effects

        Characteristic Effect
        NonBlockingStore.Characteristic.TRANSACTIONAL This method is only invoked if the store has this characteristic

        If a problem is encountered, it is recommended to wrap any created/caught Throwable in a PersistenceException and the stage be completed exceptionally.

        Parameters:
        transaction - the current transactional context.
        Returns:
        a stage that when completed signals that the transaction was rolled back

      • ignoreCommandWithFlags

        @Experimental
default boolean ignoreCommandWithFlags​(long commandFlags)
        Some stores may not want to perform operations based on if a command has certain flags. This method is currently only used for testing single write operations. This method may be removed at any time as it is experimental, it is not recommended for end users to implement it.
        Parameters:
        commandFlags - the flags attributed to the command when performing the operation
        Returns:
        whether the operation should occur