com.hazelcast.map.impl.operation

Class EntryOperation

java.lang.Object

com.hazelcast.spi.Operation

com.hazelcast.spi.impl.AbstractNamedOperation

com.hazelcast.map.impl.operation.MapOperation

com.hazelcast.map.impl.operation.KeyBasedMapOperation

com.hazelcast.map.impl.operation.EntryOperation

All Implemented Interfaces:

DataSerializable, IdentifiedDataSerializable, Versioned, BackupAwareOperation, BlockingOperation, MutatingOperation, NamedOperation, PartitionAwareOperation, ServiceNamespaceAware

public class EntryOperation
extends KeyBasedMapOperation
implements BackupAwareOperation, BlockingOperation, MutatingOperation

Contains implementation of the off-loadable contract for EntryProcessor execution on a single key.

### Overview

Implementation of the the Offloadable contract for the EntryProcessor execution on a single key.

Allows off-loading the processing unit implementing this interface to the specified or default Executor. Currently supported in:

IMap.executeOnKey(Object, EntryProcessor) IMap.submitToKey(Object, EntryProcessor) IMap.submitToKey(Object, EntryProcessor, ExecutionCallback)

### Offloadable (for reading & writing)

If the EntryProcessor implements the Offloadable interface the processing will be offloaded to the given ExecutorService allowing unblocking the partition-thread. The key will be locked for the time-span of the processing in order to not generate a write-conflict.

If the EntryProcessor implements Offloadable the invocation scenario looks as follows: - EntryOperation fetches the entry and locks the given key on partition-thread - Then the processing is offloaded to the given executor - When the processing finishes if there is a change to the entry, a EntryOffloadableSetUnlockOperation is spawned which sets the new value and unlocks the given key on partition-thread if there is no change to the entry, a UnlockOperation is spawned, which just unlocks the kiven key on partition thread

There will not be a conflict on a write due to the pessimistic locking of the key. The threading looks as follows:

1. partition-thread (fetch & lock) 2. execution-thread (process) 3. partition-thread (set & unlock, or just unlock if no changes)

### Offloadable (for reading only)

If the EntryProcessor implements the Offloadable and ReadOnly interfaces the processing will be offloaded to the givenExecutorService allowing unblocking the partition-thread. Since the EntryProcessor is not supposed to do any changes to the Entry the key will NOT be locked for the time-span of the processing.

If the EntryProcessor implements Offloadable and ReadOnly the invocation scenario looks as follows: - EntryOperation fetches the entry and DOES NOT lock the given key on partition-thread - Then the processing is offloaded to the given executor - When the processing finishes if there is a change to the entry -> exception is thrown if there is no change to the entry -> the result is returned to the user from the executor-thread.

In the read-only case the threading looks as follows:

1. partition-thread (fetch) 2. execution-thread (process)

### Primary partition - main actors

- EntryOperation - EntryOffloadableSetUnlockOperation

### Backup partitions

Offloading will not be applied to backup partitions. It is possible to initialize the EntryBackupProcessor with some input provided by the EntryProcessor in the EntryProcessor.getBackupProcessor() method. The input allows providing context to the EntryBackupProcessor - for example the "delta" so that the EntryBackupProcessor does not have to calculate the "delta" but it may just apply it.

### Locking

The locking takes place only locally. If a partition locked by an off-loaded task gets migrated, the lock will not be migrated. In this situation the off-loaded task "relying" on the lock will fail on the unlock operation, since it will notice that there is no such a lock and therefore the processing for the key will get retried. The reason behind is that the off-loadable backup-processing does not use locking there cannot be any transfer of off-loadable locks from the primary replica to backup replicas.

GOTCHA: This operation LOADS missing keys from map-store, in contrast with PartitionWideEntryOperation.

Field Summary

Fields inherited from class com.hazelcast.map.impl.operation.KeyBasedMapOperation

dataKey, dataValue, maxIdle, threadId, ttl

Fields inherited from class com.hazelcast.map.impl.operation.MapOperation

createRecordStoreOnDemand, disableWanReplicationEvent, mapContainer, mapEventPublisher, mapService, mapServiceContext, recordStore

Fields inherited from class com.hazelcast.spi.impl.AbstractNamedOperation

name

Fields inherited from class com.hazelcast.spi.Operation

GENERIC_PARTITION_ID

Constructor Summary

Constructors

Constructor and Description
EntryOperation()
EntryOperation(String name, Data dataKey, EntryProcessor entryProcessor)

Method Summary

Modifier and Type	Method and Description
CallStatus	call() Call the operation and returns the CallStatus.
int	getAsyncBackupCount() The asynchronous backup count.
Operation	getBackupOperation() Creates the BackupOperation responsible for making the backup.
int	getId() Returns type identifier for this class.
Object	getResponse() Called if and only if Operation.returnsResponse() returned true, shortly after Operation.run() returns.
int	getSyncBackupCount() The synchronous backup count.
WaitNotifyKey	getWaitKey()
void	innerBeforeRun()
void	onWaitExpire()
protected void	readInternal(ObjectDataInput in)
boolean	shouldBackup() Checks if a backup needs to be made.
boolean	shouldWait()
protected void	writeInternal(ObjectDataOutput out)

Methods inherited from class com.hazelcast.map.impl.operation.KeyBasedMapOperation

getKey, getThreadId, getTtl, getValue, setThreadId

Methods inherited from class com.hazelcast.map.impl.operation.MapOperation

beforeRun, canThisOpGenerateWANEvent, evict, getCallerProvenance, getFactoryId, getServiceName, getServiceNamespace, invalidateAllKeysInNearCaches, invalidateNearCache, invalidateNearCache, isPostProcessing, publishLoadAsWanUpdate, publishWanRemove, publishWanUpdate, setMapContainer, setMapService

Methods inherited from class com.hazelcast.spi.impl.AbstractNamedOperation

getName, toString

Methods inherited from class com.hazelcast.spi.Operation

afterRun, executedLocally, getCallerAddress, getCallerUuid, getCallId, getCallTimeout, getConnection, getInvocationTime, getLogger, getNodeEngine, getOperationResponseHandler, getPartitionId, getReplicaIndex, getService, getWaitTimeout, isUrgent, logError, onExecutionFailure, onInvocationException, onSetCallId, readData, requiresExplicitServiceName, returnsResponse, run, sendResponse, setCallerUuid, setNodeEngine, setOperationResponseHandler, setPartitionId, setReplicaIndex, setService, setServiceName, setValidateTarget, setWaitTimeout, toString, validatesTarget, writeData

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.hazelcast.spi.PartitionAwareOperation

getPartitionId

Methods inherited from interface com.hazelcast.spi.BlockingOperation

getWaitTimeout

Methods inherited from interface com.hazelcast.nio.serialization.DataSerializable

readData, writeData

Constructor Detail

EntryOperation

public EntryOperation()

EntryOperation

public EntryOperation(String name,
                      Data dataKey,
                      EntryProcessor entryProcessor)

Method Detail

innerBeforeRun

public void innerBeforeRun()
                    throws Exception

Overrides:

innerBeforeRun in class MapOperation

Throws:

Exception

call

public CallStatus call()

Description copied from class: Operation

Call the operation and returns the CallStatus. An Operation should either implement call or run; not both. If run is implemented, then the system remains backwards compatible to prevent making massive code changes while adding this feature. In the future all Operation.run() methods will be replaced by call methods. The call method looks very much like the Operation.run() method and it is very close to Runnable.run() and Callable.call(). The main difference between a run and call, is that the returned CallStatus from the call can tell something about the actual execution. For example it could tell that some waiting is required in case of a BlockingOperation. Or that the actual execution work is offloaded to some executor in case of an Offloadable EntryOperation. In the future new types of CallStatus are expected to be added, e.g. for interleaving. In the future it is very likely that for regular Operation that want to return a concrete response, the actual response can be returned directly. In this case we'll change the return type to Object to prevent forcing the response to be wrapped in a CallStatus.DONE_RESPONSE monad since that would force additional litter to be created.

Overrides:

call in class Operation

Returns:

the CallStatus.

See Also:

Operation.run()

getWaitKey

public WaitNotifyKey getWaitKey()

Specified by:

getWaitKey in interface BlockingOperation

shouldWait

public boolean shouldWait()

Specified by:

shouldWait in interface BlockingOperation

onWaitExpire

public void onWaitExpire()

Specified by:

onWaitExpire in interface BlockingOperation

getResponse

public Object getResponse()

Description copied from class: Operation

Called if and only if Operation.returnsResponse() returned true, shortly after Operation.run() returns.

Overrides:

getResponse in class Operation

getBackupOperation

public Operation getBackupOperation()

Description copied from interface: BackupAwareOperation

Creates the BackupOperation responsible for making the backup.

Specified by:

getBackupOperation in interface BackupAwareOperation

Returns:

the created BackupOperation responsible for making the backup.

shouldBackup

public boolean shouldBackup()

Description copied from interface: BackupAwareOperation

Checks if a backup needs to be made.

If a call has not made any change, e.g. an AtomicLong increment with 0, no backup needs to be made.

Specified by:

shouldBackup in interface BackupAwareOperation

Returns:

true if a backup needs to be made, false otherwise.

getAsyncBackupCount

public int getAsyncBackupCount()

Description copied from interface: BackupAwareOperation

The asynchronous backup count. If no asynchronous backups need to be made, 0 is returned.

Specified by:

getAsyncBackupCount in interface BackupAwareOperation

Returns:

the asynchronous backup count.

getSyncBackupCount

public int getSyncBackupCount()

Description copied from interface: BackupAwareOperation

The synchronous backup count. If no backups need to be made, 0 is returned.

Specified by:

getSyncBackupCount in interface BackupAwareOperation

Returns:

the synchronous backup count.

getId

public int getId()

Description copied from interface: IdentifiedDataSerializable

Returns type identifier for this class. It should be unique per DataSerializableFactory.

Specified by:

getId in interface IdentifiedDataSerializable

Returns:

type ID

readInternal

protected void readInternal(ObjectDataInput in)
                     throws IOException

Overrides:

readInternal in class KeyBasedMapOperation

Throws:

IOException

writeInternal

protected void writeInternal(ObjectDataOutput out)
                      throws IOException

Overrides:

writeInternal in class KeyBasedMapOperation

Throws:

IOException