Package org.infinispan.container.impl

Interface EntryFactory

All Known Implementing Classes:
EntryFactoryImpl
public interface EntryFactory
A factory for constructing MVCCEntry instances for use in the InvocationContext. Implementations of this interface would typically wrap an internal CacheEntry with an MVCCEntry.

Expected wrapping patterns

EntryWrappingInterceptor checks CacheTopology.getReadConsistentHash() and if this node is an owner of the key, it loads the entry from DataContainer. On the way back through interceptor stack, the entry is committed from EntryWrappingInterceptor through ClusteringDependentLogic which checks CacheTopology.getWriteConsistentHash().

Entry being wrapped is a prerequisite for the command to run and therefore commit the entry, but it's not up to EntryWrappingInterceptor to make sure the entry is always wrapped - all the interceptors below can expect is (key is in readCH) => (entry is wrapped). The entry may be wrapped by EWI or other interceptors later, e.g. (but not limited to) when:

  • entry is in L1
  • entry is fetched from remote node
  • the cache is transactional and command should be executed on origin (but it does not need previous value - it is then wrapped as null entry)
It is the distribution interceptor that enforces that (entry is read/written by command) => (entry is wrapped), by fetching the remote value, limiting the set of keys in given command (narrowing it) or not executing the command locally at all.

If the entry should be read locally but it's not found in DC, the entry will be wrapped by EntryWrappingInterceptor (either as NullCacheEntry for reads or other appropriate type for writes). Such entry returns false on CacheEntry.skipLookup() as it's value is unsure (subsequent interceptors can retrieve the new value from the cache store or remote node and call wrapExternalEntry(org.infinispan.context.InvocationContext, java.lang.Object, org.infinispan.container.entries.CacheEntry, boolean, boolean) to update the context.

With repeatable reads, the value that is context must not be overwritten by value out of the transaction (only commands in this transaction can change the context entry. That's why EntryWrappingInterceptor calls CacheEntry.setSkipLookup(boolean) from the return handler for every command.

When a command is retried and repeatable reads are not used, the entry is removed from the context completely and wrapped again by EntryWrappingInterceptor. When repeatable reads are in use, RepeatableReadEntry entry keeps the value before the command was executed and the context is reset to this value.

This summarizes expected behaviour of interceptors loading from persistence layer:

  • entry == null: don't load the entry because this node is not a read owner
  • entry.skipLookup == false: attempt to load the entry
  • entry.skipLookup == true: don't load the entry because it was already published
Distribution interceptor should behave as follows:
  • entry == null: If this is a write command, check writeCH and if this node is
    • primary owner: that should not happen as command.topologyId is outdated (the topology is checked before executing the command and OutdatedTopologyException is thrown)
    • backup owner and VisitableCommand.loadType() is OWNER: retrieve the value from remote node
    • backup owner that does not need previous value: wrap null
    • non-owner: don't execute the command (or narrow the set of keys in it)
    If this is a read-only command:
    • If this is the origin, fetch the entry from remote node
    • If this is not the origin, the command must have different topologyId and we retry
  • entry != null: don't do any remote retrieval because the value is known

In local mode, the data can be always read and written, so there is no risk that a command won't have the entry wrapped.

Since:
4.0
Author:
Manik Surtani (manik@jboss.org), Galder Zamarreño, Mircea.Markus@jboss.com

  • Method Details

    • expirationCheckDelay

      static CompletionStage<Void> expirationCheckDelay(CompletionStage<Void> currentStage, CompletableFuture<Void> initialStage)
      Use to synchronize multiple wrapEntryForReading(InvocationContext, Object, int, boolean, boolean, CompletionStage) or wrapEntryForWriting(InvocationContext, Object, int, boolean, boolean, CompletionStage) calls.

      The basic pattern is:

      
 CompletableFuture<Void> initialStage = new CompletableFuture<>();
 CompletionStage<Void> currentStage = initialStage;
 for (Object key : ...) {
    currentStage = entryFactory.wrapEntryForWriting(..., currentStage);
 }
 return asyncInvokeNext(ctx, command, expirationCheckDelay(currentStage, initialStage));

      The effect expirationCheckDelay(currentStage, initialStage) call is equivalent to completing the initialStage and returning currentStage, but it optimizes the common case where currentStage and initialStage are the same.

    • wrapEntryForReading

      CompletionStage<Void> wrapEntryForReading(InvocationContext ctx, Object key, int segment, boolean isOwner, boolean hasLock, CompletionStage<Void> previousStage)
      Wraps an entry for reading. Usually this is just a raw CacheEntry but certain combinations of isolation levels and the presence of an ongoing JTA transaction may force this to be a proper, wrapped MVCCEntry. The entry is also typically placed in the invocation context.
      Parameters:
      ctx - current invocation context
      key - key to look up and wrap
      segment - segment for the key
      isOwner - true if this node is current owner in readCH (or we ignore CH)
      hasLock - true if the invoker already has the lock for this key
      previousStage - if wrapping can't be performed synchronously, only access the invocation context from another thread after this stage is complete
      Returns:
      stage that when complete the value should be in the context

    • wrapEntryForWriting

      CompletionStage<Void> wrapEntryForWriting(InvocationContext ctx, Object key, int segment, boolean isOwner, boolean isRead, CompletionStage<Void> previousStage)
      Insert an entry that exists in the data container into the context. Doesn't do anything if the key was already wrapped.

      The returned stage will always be complete if isOwner is false.

      Parameters:
      ctx - current invocation context
      key - key to look up and wrap
      segment - segment for the key
      isOwner - true if this node is current owner in readCH (or we ignore CH)
      isRead - true if this operation is expected to read the value of the entry
      previousStage - if wrapping can't be performed synchronously, only access the invocation context from another thread after this stage is complete
      Since:
      8.1

    • wrapEntryForWritingSkipExpiration

      void wrapEntryForWritingSkipExpiration(InvocationContext ctx, Object key, int segment, boolean isOwner)
      Insert an entry that exists in the data container into the context, even if it is expired Doesn't do anything if the key was already wrapped
      Parameters:
      ctx - current invocation context
      key - key to look up and wrap
      segment - segment for the key
      isOwner - is the local node a read owner?

    • wrapExternalEntry

      void wrapExternalEntry(InvocationContext ctx, Object key, CacheEntry externalEntry, boolean isRead, boolean isWrite)
      Insert an external entry (e.g. loaded from a cache loader or from a remote node) into the context.
      Parameters:
      ctx - current invocation context
      key - key to look up and wrap
      externalEntry - the value to be inserted into context
      isRead - true if this operation is expected to read the value of the entry
      isWrite - if this is executed within a write command
      Since:
      8.1