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 Summary

Modifier and Type	Method and Description
void	wrapEntryForExpired(InvocationContext ctx, Object key, int segment) 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
CompletionStage<Void>	wrapEntryForReading(InvocationContext ctx, Object key, int segment, boolean isOwner, boolean hasLock) Wraps an entry for reading.
CompletionStage<Void>	wrapEntryForWriting(InvocationContext ctx, Object key, int segment, boolean isOwner, boolean isRead) Insert an entry that exists in the data container into the context.
void	wrapExternalEntry(InvocationContext ctx, Object key, CacheEntry externalEntry, boolean isRead, boolean isWrite) Insert an external entry (e.g.

Method Detail

wrapEntryForReading

CompletionStage<Void> wrapEntryForReading(InvocationContext ctx,
                                          Object key,
                                          int segment,
                                          boolean isOwner,
                                          boolean hasLock)

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

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)

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

Since:

8.1

wrapEntryForExpired

void wrapEntryForExpired(InvocationContext ctx,
                         Object key,
                         int segment)

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

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