com.hazelcast.spi

## Class Operation

- java.lang.Object
- - com.hazelcast.spi.Operation

- All Implemented Interfaces:
    DataSerializable
  Direct Known Subclasses:
    AbstractAtomicLongOperation, AbstractAtomicReferenceOperation, AbstractCRDTReplicationOperation, AbstractLocalOperation, AbstractLockOperation, com.hazelcast.spi.impl.AbstractNamedOperation, AbstractPNCounterOperation, AtomicLongReplicationOperation, AtomicReferenceReplicationOperation, CountDownLatchReplicationOperation, LockReplicationOperation, SemaphoreReplicationOperation

      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

    All Methods Instance Methods Concrete Methods
    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 overridden.
    `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 overridden. 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`

Copyright © 2019. All rights reserved.