Package org.infinispan.persistence.jdbc.common.impl

Class BaseJdbcStore<K,V,C extends AbstractJdbcStoreConfiguration>

java.lang.Object
org.infinispan.persistence.jdbc.common.impl.BaseJdbcStore<K,V,C>
All Implemented Interfaces:
NonBlockingStore<K,V>
Direct Known Subclasses:
AbstractSchemaJdbcStore, JdbcStringBasedStore
public abstract class BaseJdbcStore<K,V,C extends AbstractJdbcStoreConfiguration> extends Object implements NonBlockingStore<K,V>

  • Field Details

  • Constructor Details

    • BaseJdbcStore

      public BaseJdbcStore()

  • Method Details

    • characteristics

      public Set<NonBlockingStore.Characteristic> characteristics()
      Description copied from interface: NonBlockingStore
      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 the data in the store can be handled.

      Refer to NonBlockingStore.Characteristic and its values for descriptions of each characteristic for stores.

      Specified by:
      characteristics in interface NonBlockingStore<K,V>
      Returns:
      the set of characteristics that this store supports.

    • createTableOperations

      protected abstract TableOperations<K,V> createTableOperations(InitializationContext ctx, C config) throws SQLException
      Extension point to allow for initializing and creating a table operations object. All variables in the BaseJdbcStore will be initialized except for tableOperations when this is invoked.
      Parameters:
      ctx - store context
      config - configuration of the store
      Returns:
      the table operations to use for future calls
      Throws:
      SQLException - if any database exception occurs during creation

    • start

      public CompletionStage<Void> start(InitializationContext ctx)
      Description copied from interface: NonBlockingStore
      The first method to invoke so that the store can be configured and additional steps, such as connecting through a socket or opening file descriptors, are 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 not to be invoked concurrently with other operations. This means other methods are not 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 NonBlockingStore.stop() has been invoked and allowed for its stage to complete.

      Specified by:
      start in interface NonBlockingStore<K,V>
      Parameters:
      ctx - initialization context used to initialize this store.
      Returns:
      a stage that, when complete, indicates that this store has started successfully.

    • extraStopSteps

      protected void extraStopSteps()
      Method to extend to add additional steps when the store is shutting down. This is invoked before the connectionFactory is shut down and should not do so.

    • stop

      public CompletionStage<Void> stop()
      Description copied from interface: NonBlockingStore
      This method is invoked when the cache is being shutdown. It is expected that all resources related to the store are freed when the returned stage is complete.

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

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

      Specified by:
      stop in interface NonBlockingStore<K,V>
      Returns:
      a stage that, when complete, indicates that this store has stopped.

    • isAvailable

      public CompletionStage<Boolean> isAvailable()
      Description copied from interface: NonBlockingStore
      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 polled periodically to update the status of stores if their availability changes. This method is not invoked concurrently with itself. In other words, this method is not invoked until after the previous stage has completed. However, this method is invoked concurrently with other operations, except for NonBlockingStore.start(InitializationContext) and NonBlockingStore.stop().

      If a store is configured to be StoreConfiguration.async() and the store becomes unavailable, then it is 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 thrown.

      Specified by:
      isAvailable in interface NonBlockingStore<K,V>
      Returns:
      stage that, when complete, indicates if the store is available.

    • load

      public CompletionStage<MarshallableEntry<K,V>> load(int segment, Object key)
      Description copied from interface: NonBlockingStore
      Returns a stage that will contain the value loaded from the store. If a MarshallableEntry needs to be created here, InitializationContext.getMarshallableEntryFactory() and InitializationContext.getByteBufferFactory() should be used.

      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 expired entries.
      NonBlockingStore.Characteristic.SEGMENTABLE When this is not set or segmentation is disabled in the configuration, the 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.

      Specified by:
      load in interface NonBlockingStore<K,V>
      Parameters:
      segment - the segment for the given key if segmentation is enabled, otherwise 0.
      key - key of the entry to load.
      Returns:
      a stage that, when complete, contains the store value or null if not present.

    • write

      public CompletionStage<Void> write(int segment, MarshallableEntry<? extends K,? extends V> entry)
      Description copied from interface: NonBlockingStore
      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 and segmentation is not disabled in the configuration, 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.

      Specified by:
      write in interface NonBlockingStore<K,V>
      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 indicates that the store has written the value.

    • delete

      public CompletionStage<Boolean> delete(int segment, Object key)
      Description copied from interface: NonBlockingStore
      Removes the entry for given key and segment from the store and optionally report if 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 or segmentation is disabled in the configuration, the 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.

      Specified by:
      delete in interface NonBlockingStore<K,V>
      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 completes with TRUE if the key existed in the store, FALSE if the key did not exist in the store, or null if the store does not report this information.

    • clear

      public CompletionStage<Void> clear()
      Description copied from interface: NonBlockingStore
      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.

      Specified by:
      clear in interface NonBlockingStore<K,V>
      Returns:
      a stage that, when complete, indicates that the store has been cleared.

    • batch

      public CompletionStage<Void> batch(int publisherCount, org.reactivestreams.Publisher<NonBlockingStore.SegmentedPublisher<Object>> removePublisher, org.reactivestreams.Publisher<NonBlockingStore.SegmentedPublisher<MarshallableEntry<K,V>>> writePublisher)
      Description copied from interface: NonBlockingStore
      Writes and removes the entries provided by the Publishers into the store. Both are provided in the same method so that a batch may be performed as a single atomic operation if desired, although it is up to the store to manage its batching. If needed a store may generate batches of a configured size by using the StoreConfiguration.maxBatchSize() setting.

      Each of the Publishers 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.

      WARNING: For performance reasons neither Publisher will emit any NonBlockingStore.SegmentedPublishers until both write and remove Publishers are subscribed to. These Publishers should also be only subscribed once.

      Summary of Characteristics Effects

      Characteristic Effect
      NonBlockingStore.Characteristic.READ_ONLY This method will never be invoked.
      NonBlockingStore.Characteristic.SEGMENTABLE If not set or segmentation is disabled in the configuration, the publisherCount parameter has a value of 1, which means there is 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.

      Specified by:
      batch in interface NonBlockingStore<K,V>
      Parameters:
      publisherCount - the maximum number of SegmentPublishers either publisher will publish
      removePublisher - publishes what keys should be removed from the store
      writePublisher - publishes the entries to write to the store
      Returns:
      a stage that when complete signals that the store has written the values

    • prepareWithModifications

      public CompletionStage<Void> prepareWithModifications(jakarta.transaction.Transaction tx, int publisherCount, org.reactivestreams.Publisher<NonBlockingStore.SegmentedPublisher<Object>> removePublisher, org.reactivestreams.Publisher<NonBlockingStore.SegmentedPublisher<MarshallableEntry<K,V>>> writePublisher)
      Description copied from interface: NonBlockingStore
      Write remove and put modifications to the store in the prepare phase, which should not yet persisted until the same transaction is committed via NonBlockingStore.commit(Transaction) or they are discarded if the transaction is rolled back via NonBlockingStore.rollback(Transaction).

      Each of the Publishers 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.

      WARNING: For performance reasons neither Publisher will emit any NonBlockingStore.SegmentedPublishers until both write and remove Publishers are subscribed to. These Publishers should also be only subscribed once.

      Summary of Characteristics Effects

      Characteristic Effect
      NonBlockingStore.Characteristic.TRANSACTIONAL This method is invoked only 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.

      Specified by:
      prepareWithModifications in interface NonBlockingStore<K,V>
      Parameters:
      tx - the current transactional context.
      publisherCount - the maximum number of SegmentPublishers either publisher will publish
      removePublisher - publishes what keys should be removed from the store
      writePublisher - publishes the entries to write to the store
      Returns:
      a stage that when complete signals that the store has written the values

    • commit

      public CompletionStage<Void> commit(jakarta.transaction.Transaction tx)
      Description copied from interface: NonBlockingStore
      Commit changes in the provided transaction to the underlying store.

      Summary of Characteristics Effects

      Characteristic Effect
      NonBlockingStore.Characteristic.TRANSACTIONAL This method is invoked only 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.

      Specified by:
      commit in interface NonBlockingStore<K,V>
      Parameters:
      tx - the current transactional context.
      Returns:
      a stage that, when completed, indicates that the transaction was committed.

    • rollback

      public CompletionStage<Void> rollback(jakarta.transaction.Transaction tx)
      Description copied from interface: NonBlockingStore
      Roll back the changes from the provided transaction to the underlying store.

      Summary of Characteristics Effects

      Characteristic Effect
      NonBlockingStore.Characteristic.TRANSACTIONAL This method is invoked only 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.

      Specified by:
      rollback in interface NonBlockingStore<K,V>
      Parameters:
      tx - the current transactional context.
      Returns:
      a stage that, when completed, indicates that the transaction was rolled back.

    • getTxConnection

      protected Connection getTxConnection(jakarta.transaction.Transaction tx)

    • destroyTxConnection

      protected void destroyTxConnection(jakarta.transaction.Transaction tx)

    • publishEntries

      public org.reactivestreams.Publisher<MarshallableEntry<K,V>> publishEntries(IntSet segments, Predicate<? super K> filter, boolean includeValues)
      Description copied from interface: NonBlockingStore
      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 be 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 or segmentation is disabled in the configuration, the segment parameter may be ignored.
      Specified by:
      publishEntries in interface NonBlockingStore<K,V>
      Parameters:
      segments - a set of segments to filter entries by. This will always be non-null.
      filter - a filter to filter the keys by. If this is null then no additional filtering should be done after segments.
      Returns:
      a publisher that provides the keys from the store.

    • publishKeys

      public org.reactivestreams.Publisher<K> publishKeys(IntSet segments, Predicate<? super K> filter)
      Description copied from interface: NonBlockingStore
      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 be 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 or segmentation is disabled in the configuration, the segment parameter may be ignored.

      Specified by:
      publishKeys in interface NonBlockingStore<K,V>
      Parameters:
      segments - a set of segments to filter keys by. This will always be non-null.
      filter - a filter to filter the keys by. If this is null then no additional filtering should be done after segments.
      Returns:
      a publisher that provides the keys from the store.

    • size

      public CompletionStage<Long> size(IntSet segments)
      Description copied from interface: NonBlockingStore
      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 or segmentation is disabled in the configuration, the 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.

      Specified by:
      size in interface NonBlockingStore<K,V>
      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

      public CompletionStage<Long> approximateSize(IntSet segments)
      Description copied from interface: NonBlockingStore
      Returns an estimation of the amount of entries that map to the given segments in the store. This is similar to NonBlockingStore.size(IntSet) except that it is not strict about the returned size. For instance, this method might ignore if an entry is expired or if the store has some underlying optimizations to eventually have a consistent size.

      The implementations should be O(1). If a size approximation cannot be returned without iterating over all the entries in the store, the implementation should return -1L.

      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 the store does not have this characteristic or segmentation is disabled in the configuration, the segment parameter is always IntSets.immutableRangeSet(numSegments).

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

      Specified by:
      approximateSize in interface NonBlockingStore<K,V>
      Parameters:
      segments - the segments for which the entries are counted.
      Returns:
      a stage that, when complete, contains the approximate count of the entries in the given segments, or -1L if an approximate count cannot be provided.