com.hazelcast.spi

Class Operation

java.lang.Object

com.hazelcast.spi.Operation

All Implemented Interfaces:

DataSerializable

Direct Known Subclasses:

AbstractAtomicLongOperation, AbstractAtomicReferenceOperation, AbstractCardinalityEstimatorOperation, AbstractClientOperation, AbstractCRDTReplicationOperation, AbstractDynamicConfigOperation, AbstractJoinOperation, AbstractLocalOperation, AbstractLockOperation, AbstractManagementOperation, AbstractMultiMapOperation, AbstractNamedOperation, AbstractPNCounterOperation, AbstractRingBufferOperation, AbstractSchedulerOperation, AbstractSerializableOperation, AbstractTxOperation, AbstractXAOperation, AccumulatorConsumerOperation, AddCacheConfigOperation, AddInterceptorOperation, AssignPartitions, AtomicLongReplicationOperation, AtomicReferenceReplicationOperation, AuthenticationFailureOp, Backup, BeforeJoinCheckFailureOp, CacheAssignAndGetUuidsOperation, CacheGetInvalidationMetaDataOperation, CacheReplicationOperation, CallableTaskOperation, CancellationOperation, ClassDataFinderOperation, CollectionOperation, CollectionReplicationOperation, CommitClusterStateOp, ConfigMismatchOp, CountDownLatchReplicationOperation, DeployClassesOperation, DeregistrationOperation, DistributedObjectDestroyOperation, EventJournalReadOperation, ExplicitSuspicionOp, FetchMembersViewOp, FetchPartitionStateOperation, FinalizeMigrationOperation, GroupMismatchOp, HasOngoingMigration, HeartbeatComplaintOp, HeartbeatOp, InitializeDistributedObjectOperation, JoinRequestOp, KeyValueJobOperation, LockClusterStateOp, LockReplicationOperation, MapAssignAndGetUuidsOperation, MapGetInvalidationMetaDataOperation, MapReplicationOperation, MasterResponseOp, MemberAttributeChangedOp, MemberCallableTaskOperation, MembersUpdateOp, MergeClustersOp, MergeOperation, MigrationCommitOperation, MigrationOperation, MigrationRequestOperation, MultiMapReplicationOperation, OnJoinCacheOperation, OnJoinRegistrationOperation, PartitionBackupReplicaAntiEntropyOperation, PartitionIteratingOperation, PartitionReplicaSyncRequest, PartitionReplicaSyncResponse, PartitionReplicaSyncRetryResponse, PartitionStateOperation, PostJoinMapOperation, PostJoinProxyOperation, ProcessingOperation, PromoteLiteMemberOp, PromotionCommitOperation, QueueReplicationOperation, RegistrationOperation, RemoveInterceptorOperation, ReplicationOperation, ReplicationOperation, ReplicationOperation, RollbackClusterStateOp, SafeStateCheckOperation, SemaphoreReplicationOperation, SendEventOperation, ShutdownNodeOp, ShutdownRequestOperation, ShutdownResponseOperation, StartProcessingJobOperation, TriggerExplicitSuspicionOp, TriggerMemberListPublishOp, WhoisMasterOp, XaReplicationOperation

public abstract class Operation
extends Object
implements DataSerializable

An operation could be compared to a Runnable. It contains logic that is going to be executed; this logic will be placed in the run() method.

Field Summary

Fields

Modifier and Type	Field and Description
static int	GENERIC_PARTITION_ID Marks an Operation as non-partition-specific.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Operation()

Method Summary

Modifier and Type	Method and Description
void	afterRun() Is executed called after run() or call() method completes normally and the operation is not blocked, see CallStatus.WAIT.
void	beforeRun() The beforeRun is called before either the run() or the call() method is called.
CallStatus	call() Call the operation and returns the CallStatus.
boolean	executedLocally() Returns true if local member is the caller.
Address	getCallerAddress()
String	getCallerUuid()
long	getCallId() Gets the call ID of this operation.
long	getCallTimeout() Gets the call timeout in milliseconds.
Connection	getConnection()
long	getInvocationTime() Gets the time in milliseconds when this invocation started.
protected ILogger	getLogger()
NodeEngine	getNodeEngine()
OperationResponseHandler	getOperationResponseHandler() Gets the OperationResponseHandler tied to this Operation.
int	getPartitionId() Returns the ID of the partition that this Operation will be executed on.
int	getReplicaIndex()
Object	getResponse() Called if and only if returnsResponse() returned true, shortly after run() returns.
<T> T	getService()
String	getServiceName()
long	getWaitTimeout() Returns the wait timeout in millis.
boolean	isUrgent()
void	logError(Throwable e) Logs Exception/Error thrown during operation execution.
void	onExecutionFailure(Throwable e) Called when an Exception/Error is thrown during operation execution.
ExceptionAction	onInvocationException(Throwable throwable) Called when an Exception/Error is thrown during an invocation.
protected void	onSetCallId(long callId) Called every time a new callId is set on the operation.
void	readData(ObjectDataInput in) Reads fields from the input stream
protected void	readInternal(ObjectDataInput in)
protected boolean	requiresExplicitServiceName() Returns true to force the explicit service name serialization for this operation, false otherwise.
boolean	returnsResponse() Method is intended to be subclassed.
void	run() Runs the operation.
void	sendResponse(Object value)
Operation	setCallerUuid(String callerUuid)
Operation	setNodeEngine(NodeEngine nodeEngine)
Operation	setOperationResponseHandler(OperationResponseHandler responseHandler) Sets the OperationResponseHandler.
Operation	setPartitionId(int partitionId) Sets the partition ID.
Operation	setReplicaIndex(int replicaIndex)
Operation	setService(Object service)
Operation	setServiceName(String serviceName)
Operation	setValidateTarget(boolean validateTarget)
void	setWaitTimeout(long timeout) Sets the wait timeout in millis.
String	toString()
protected void	toString(StringBuilder sb) A template method allows for additional information to be passed into the toString() method.
boolean	validatesTarget()
void	writeData(ObjectDataOutput out) Writes object fields to output stream
protected void	writeInternal(ObjectDataOutput out)

Methods inherited from class java.lang.Object

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

Field Detail

GENERIC_PARTITION_ID

public static final int GENERIC_PARTITION_ID

Marks an Operation as non-partition-specific.

See Also:

Constant Field Values

Constructor Detail

Operation

protected Operation()

Method Detail

executedLocally

public boolean executedLocally()

Returns true if local member is the caller.

Note: On the caller member this method always returns true. It's meant to be used on target member to determine if the execution is local.

isUrgent

public boolean isUrgent()

beforeRun

public void beforeRun()
               throws Exception

The beforeRun is called before either the run() or the call() method is called. runs before wait-support

Throws:

Exception

run

public void run()
         throws Exception

Runs the operation. Either the run() or call() method should be implemented; not both. Runs after wait-support, supposed to do actual operation

Throws:

Exception

See Also:

call()

call

public CallStatus call()
                throws Exception

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 run() methods will be replaced by call methods. The call method looks very much like the 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.

Returns:

the CallStatus.

Throws:

Exception - if something failed while executing 'call'.

See Also:

run()

afterRun

public void afterRun()
              throws Exception

Is executed called after run() or call() method completes normally and the operation is not blocked, see CallStatus.WAIT. Runs after backups, before wait-notify.

Throws:

Exception

returnsResponse

public boolean returnsResponse()

Method is intended to be subclassed. If it returns true, getResponse() will be called right after run() method. If it returns false, sendResponse(Object) must be called later to finish the operation.

In other words, true is for synchronous operation and false is for asynchronous one.

Default implementation is synchronous operation (true).

getResponse

public Object getResponse()

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

getServiceName

public String getServiceName()

setServiceName

public final Operation setServiceName(String serviceName)

getPartitionId

public final int getPartitionId()

Returns the ID of the partition that this Operation will be executed on. If the partitionId is equal or larger than 0, it means that it is tied to a specific partition: for example, a map.get('foo'). If it is smaller than 0, than it means that it isn't bound to a particular partition. The partitionId should never be equal or larger than the total number of partitions. For example, if there are 271 partitions, the maximum partition ID is 270. The partitionId is used by the OperationService to figure out which member owns a specific partition, and to send the operation to that member.

Returns:

the ID of the partition.

See Also:

setPartitionId(int)

setPartitionId

public final Operation setPartitionId(int partitionId)

Sets the partition ID.

Parameters:

partitionId - the ID of the partition.

Returns:

the updated Operation.

See Also:

getPartitionId()

getReplicaIndex

public final int getReplicaIndex()

setReplicaIndex

public final Operation setReplicaIndex(int replicaIndex)

getCallId

public final long getCallId()

Gets the call ID of this operation. The call ID is used to associate the invocation of an operation on a remote system with the response from the execution of that operation.

• Initially the call ID is zero.
• When an Invocation of the operation is created, a positive call ID is assigned
• When the invocation ends, the operation is deactivate()d, and the call ID is negated.
• The same operation may be involved in a further invocation (retrying); this will assign a new call ID and reactivate the operation.

Returns:

the call ID

onSetCallId

protected void onSetCallId(long callId)

Called every time a new callId is set on the operation. A new callId is set before initial invocation and before every invocation retry.

By default this is a no-op method. Operation implementations which want to get notified on callId changes can override it.

For example an operation can distinguish the first invocation and invocation retries by keeping the initial callId.

Parameters:

callId - the new call ID that was set on the operation

validatesTarget

public boolean validatesTarget()

setValidateTarget

public final Operation setValidateTarget(boolean validateTarget)

getNodeEngine

public final NodeEngine getNodeEngine()

setNodeEngine

public final Operation setNodeEngine(NodeEngine nodeEngine)

getService

public final <T> T getService()

setService

public final Operation setService(Object service)

getCallerAddress

public final Address getCallerAddress()

getConnection

public final Connection getConnection()

getOperationResponseHandler

public final OperationResponseHandler getOperationResponseHandler()

Gets the OperationResponseHandler tied to this Operation. The returned value can be null.

Returns:

the OperationResponseHandler

setOperationResponseHandler

public final Operation setOperationResponseHandler(OperationResponseHandler responseHandler)

Sets the OperationResponseHandler. Value is allowed to be null.

Parameters:

responseHandler - the OperationResponseHandler to set.

Returns:

this instance.

sendResponse

public final void sendResponse(Object value)

getInvocationTime

public final long getInvocationTime()

Gets the time in milliseconds when this invocation started. For more information, see ClusterClock.getClusterTime().

Returns:

the time of the invocation start.

getCallTimeout

public final long getCallTimeout()

Gets the call timeout in milliseconds. For example, if a call should start execution within 60 seconds or it should be aborted otherwise, then the call timeout is 60000 milliseconds. Once the operation execution starts, the call timeout is no longer relevant, even if the execution takes a long time. For more information about the default value, see GroupProperty.OPERATION_CALL_TIMEOUT_MILLIS

Returns:

the call timeout in milliseconds.

See Also:

setCallTimeout(long), OperationAccessor.setCallTimeout(Operation, long)

getWaitTimeout

public final long getWaitTimeout()

Returns the wait timeout in millis. -1 means infinite wait, and 0 means no waiting at all. The wait timeout is the amount of time a BlockingOperation is allowed to be parked in the OperationParker. Examples:

1. in case of ILock.tryLock(10, ms), the wait timeout is 10 ms
2. in case of ILock.lock(), the wait timeout is -1
3. in case of ILock.tryLock(), the wait timeout is 0.

The waitTimeout is only relevant for blocking operations. For non blocking operations the value is ignored.

Returns:

the wait timeout.

setWaitTimeout

public final void setWaitTimeout(long timeout)

Sets the wait timeout in millis.

Parameters:

timeout - the wait timeout.

See Also:

for more detail.

onInvocationException

public ExceptionAction onInvocationException(Throwable throwable)

Called when an Exception/Error is thrown during an invocation. Invocation process will continue, it will retry or fail according to returned ExceptionAction.

This method is called on caller side of the invocation.

Parameters:

throwable - Exception/Error thrown during invocation

Returns:

ExceptionAction

getCallerUuid

public String getCallerUuid()

setCallerUuid

public Operation setCallerUuid(String callerUuid)

getLogger

protected final ILogger getLogger()

onExecutionFailure

public void onExecutionFailure(Throwable e)

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

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

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

Parameters:

e - Exception/Error thrown during operation execution

logError

public void logError(Throwable e)

Logs Exception/Error thrown during operation execution. Operation implementations can override this behaviour according to their needs.

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

Parameters:

e - Exception/Error thrown during operation execution

writeData

public final void writeData(ObjectDataOutput out)
                     throws IOException

Description copied from interface: DataSerializable

Writes object fields to output stream

Specified by:

writeData in interface DataSerializable

Parameters:

out - output

Throws:

IOException - if an I/O error occurs. In particular, an IOException may be thrown if the output stream has been closed.

readData

public final void readData(ObjectDataInput in)
                    throws IOException

Description copied from interface: DataSerializable

Reads fields from the input stream

Specified by:

readData in interface DataSerializable

Parameters:

in - input

Throws:

IOException - if an I/O error occurs. In particular, an IOException may be thrown if the input stream has been closed.

requiresExplicitServiceName

protected boolean requiresExplicitServiceName()

Returns true to force the explicit service name serialization for this operation, false otherwise.

Usually, the method should be overridden if getServiceName() is also overridden, but it was not overridden in the previous HZ version, i.e. the service name was provided using an explicit external call to setServiceName(java.lang.String). This mechanism is required to maintain the backward compatibility of the serialized representation of the operation since the service name is not serialized if it matches the one returned by getServiceName().

writeInternal

protected void writeInternal(ObjectDataOutput out)
                      throws IOException

Throws:

IOException

readInternal

protected void readInternal(ObjectDataInput in)
                     throws IOException

Throws:

IOException

toString

protected void toString(StringBuilder sb)

A template method allows for additional information to be passed into the toString() method. So an Operation subclass can override this method and add additional debugging content. The default implementation does nothing so one is not forced to provide an empty implementation. It is a good practice to always call the super.toString(stringBuffer) when implementing this method to make sure that the super class can inject content if needed.

Parameters:

sb - the StringBuilder to add the debug info to.

toString

public String toString()

Overrides:

toString in class Object