com.hazelcast.spi

## Class Offload

- java.lang.Object
- - com.hazelcast.spi.CallStatus
  - - com.hazelcast.spi.Offload

-     public abstract class Offload
      extends CallStatus

  This is an internal class. So if you are a regular Hazelcast user, you don't want to use this class. You probably want to use `Offloadable`. The Offload is a `CallStatus` designed when an offloaded operation needs to offload the processing of the operation to a different system, e.g a different thread and at some point in the future a response will be ready. Offload instance can be created by Operations that require offloading, for more information see the `Operation.call()`. If the operation 'offloads' some work, but doesn't send a response ever, `CallStatus.DONE_VOID` should be used instead.

  # Response handling

  When the `init(NodeEngineImpl, Set)` is called, the original `OperationResponseHandler` of the offloaded operation is decorated with one of designed for the offloading (see heartbeats for more info). This means that sending a response for an offloaded operation, can be done using the regular response handling mechanism (see `Operation.sendResponse(Object)` or `Operation.getOperationResponseHandler()`. But one should not modify the response handler of an offloaded Operation because otherwise one could e.g. run into a memory leak (the offloaded operation will not be removed from the asynchronous operations). There is an important difference with exception handling. With regular operation when an exception is thrown, first the `Operation.onExecutionFailure(Throwable)` is called before the `Operation.sendResponse(Object)` is called. But with an offloaded operation, typically the `Operation.sendResponse(Object)` is called by the implementation of the offloading logic. So if you need the `Operation.onExecutionFailure(Throwable)` to be executed, just as the sendResponse call, the onExecuteFailure call is your own concern.

  # Heartbeats

  The Offload functionality automatically registers the offloaded operation for operation heartbeats. The registration is done when the `init(NodeEngineImpl, Set)` is called. And it is unregistered, as soon as a response is send to the offloaded operation. This is done by decorating updating the original response handler of the operation by wrapping it in a decorating response handler that automatically deregisters on completion.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ExecutionService` | `executionService`
    `protected NodeEngine` | `nodeEngine`
    `protected com.hazelcast.spi.impl.operationservice.InternalOperationService` | `operationService`
    `protected SerializationService` | `serializationService`

    - ### Fields inherited from class com.hazelcast.spi.CallStatus

      `DONE_RESPONSE, DONE_RESPONSE_ORDINAL, DONE_VOID, DONE_VOID_ORDINAL, OFFLOAD_ORDINAL, WAIT, WAIT_ORDINAL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Offload(Operation offloadedOperation)` Creates a new Offload instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `init(com.hazelcast.spi.impl.NodeEngineImpl nodeEngine, Set<Operation> asyncOperations)` Initializes the Offload.
    `Operation` | `offloadedOperation()` Returns the Operation that created this Offload.
    `abstract void` | `start()` Starts the actual offloading.

    - ### Methods inherited from class com.hazelcast.spi.CallStatus

      `ordinal`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### operationService

          protected com.hazelcast.spi.impl.operationservice.InternalOperationService operationService

    - #### nodeEngine

          protected NodeEngine nodeEngine

    - #### executionService

          protected ExecutionService executionService

    - #### serializationService

          protected SerializationService serializationService

  - ### Constructor Detail

    - #### Offload

          public Offload(Operation offloadedOperation)

      Creates a new Offload instance.
      Parameters:
        `offloadedOperation` - the Operation that is offloaded

  - ### Method Detail

    - #### offloadedOperation

          public final Operation offloadedOperation()

      Returns the Operation that created this Offload. Returned operation should not be null. Currently this is used to automatically register the operation for the sake of heartbeats.
      Returns:
        the Operation.

    - #### init

          public final void init(com.hazelcast.spi.impl.NodeEngineImpl nodeEngine,
                                 Set<Operation> asyncOperations)

      Initializes the Offload. As part of the initialization, the `OperationResponseHandler` of the offloaded `Operation` is replaced by a decorated version that takes care of automatic deregistration of the operation on completion. This method is called before the `start()` is called by the Operation infrastructure. An implementor of the `Offload` doesn't need to deal with this method.
      Parameters:
        `nodeEngine` - the `NodeEngineImpl`

    - #### start

          public abstract void start()
                              throws Exception

      Starts the actual offloading. This method is still called on the same thread that called the `Operation.call()` where this Offload instance was returned. So in most cases you want to schedule some work and then return from this method ASAP so that the thread is released. This method is called after the `Operation.afterRun()` is called. It is allowed to call `Operation.sendResponse(Object)` in the start method if there is nothing to offload.
      Throws:
        `Exception` - if something fails. If this happens, regular Operation exception handling is triggered and normally the exception is returned to the caller.

Copyright © 2020. All rights reserved.