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.MutatingKeyBasedMapOperation

com.hazelcast.map.impl.operation.EntryOperation

All Implemented Interfaces:

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

public class EntryOperation
extends MutatingKeyBasedMapOperation
implements BackupAwareOperation, BlockingOperation

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.MutatingKeyBasedMapOperation

dataKey, dataValue, threadId, ttl

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

createRecordStoreOnDemand, 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
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()
int	getSyncBackupCount() The synchronous backup count.
WaitNotifyKey	getWaitKey()
void	innerBeforeRun()
void	onExecutionFailure(Throwable e) Called when an Exception/Error is thrown during operation execution.
void	onWaitExpire()
protected void	readInternal(ObjectDataInput in)
boolean	returnsResponse()
void	run()
void	runOffloaded()
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.MutatingKeyBasedMapOperation

getKey, getThreadId, getTtl, getValue, setThreadId

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

beforeRun, evict, getFactoryId, getServiceName, getServiceNamespace, invalidateAllKeysInNearCaches, invalidateNearCache, invalidateNearCache, isPostProcessing, 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, onInvocationException, onSetCallId, readData, 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

run

public void run()

Specified by:

run in class Operation

runOffloaded

public void runOffloaded()

onExecutionFailure

public void onExecutionFailure(Throwable e)

Description copied from class: Operation

Called when an Exception/Error is thrown during operation execution.

By default this method does nothing. Operation implementations can override this behaviour due to their needs.

This method is called on node & thread that's executing the operation.

Overrides:

onExecutionFailure in class Operation

Parameters:

e - Exception/Error thrown during operation execution

returnsResponse

public boolean returnsResponse()

Overrides:

returnsResponse in class Operation

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()

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.

readInternal

protected void readInternal(ObjectDataInput in)
                     throws IOException

Overrides:

readInternal in class MutatingKeyBasedMapOperation

Throws:

IOException

writeInternal

protected void writeInternal(ObjectDataOutput out)
                      throws IOException

Overrides:

writeInternal in class MutatingKeyBasedMapOperation

Throws:

IOException

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