io.nexusrpc.handler

Interface OperationHandler<T,R>

Type Parameters:

T - The parameter type of the operation. This can be Void for no parameter.

R - the return type of the operation. This can be Void for no return.

public interface OperationHandler<T,R>

Handler for an operation.

An instance of this must be returned from an OperationImpl annotated method in a ServiceImpl. Simple synchronous operations can use sync(io.nexusrpc.handler.SynchronousOperationFunction<T, R>), more complex or asynchronous operations can manually implement this interface.

Method Summary

Modifier and Type	Method and Description
void	cancel(OperationContext context, OperationCancelDetails details) Cancel the asynchronously started operation.
OperationInfo	fetchInfo(OperationContext context, OperationFetchInfoDetails details) Fetch information about the asynchronously started operation.
R	fetchResult(OperationContext context, OperationFetchResultDetails details) Fetch the result for an asynchronously started operation.
OperationStartResult<R>	start(OperationContext context, OperationStartDetails details, T param) Handle the start of an operation.
static <T,R> OperationHandler<T,R>	sync(SynchronousOperationFunction<T,R> func) Create an operation handler for a synchronous operation backed by the given function.

Method Detail

sync

static <T,R> OperationHandler<T,R> sync(SynchronousOperationFunction<T,R> func)

Create an operation handler for a synchronous operation backed by the given function. This function will be called for each operation invocation. All other calls to the operation are not supported.

start

OperationStartResult<R> start(OperationContext context,
                              OperationStartDetails details,
                              T param)
                       throws OperationUnsuccessfulException,
                              OperationHandlerException

Handle the start of an operation.

The operation can be synchronous or asynchronous. Synchronous operations can return the result via OperationStartResult.sync(R). Asynchronous operations can return the started operation ID via OperationStartResult.async(java.lang.String).

Parameters:

context - Context for the call.

details - Details for the call.

param - Parameter for the operation. This may be null if the parameter was not given.

Returns:

The start result which is a synchronous value or an operation ID representing an asynchronously running operation.

Throws:

OperationUnsuccessfulException - If thrown, can have failure details and state such as saying the operation was cancelled.

OperationHandlerException - Unexpected failures while running the handler.

java.lang.RuntimeException - Any other exception, will be converted to an OperationHandlerException of type OperationHandlerException.ErrorType.INTERNAL.

fetchResult

R fetchResult(OperationContext context,
              OperationFetchResultDetails details)
       throws OperationStillRunningException,
              OperationUnsuccessfulException,
              OperationHandlerException

Fetch the result for an asynchronously started operation.

Parameters:

context - Context for the call.

details - Details for the call including the operation ID. The details also contain a timeout which affects how implementers should implement this function. See OperationFetchResultDetails.getTimeout() to see how to react to this value.

Returns:

The resulting value upon success.

Throws:

OperationStillRunningException - Operation is still running beyond the given timeout.

OperationUnsuccessfulException - Operation failed. If thrown, can have failure details and state such as saying the operation was cancelled.

OperationHandlerException - Unexpected failures while running the handler. This should be thrown with a type of OperationHandlerException.ErrorType.NOT_FOUND if the operation ID is not found.

java.lang.RuntimeException - Any other exception, will be converted to an OperationHandlerException of type OperationHandlerException.ErrorType.INTERNAL.

fetchInfo

OperationInfo fetchInfo(OperationContext context,
                        OperationFetchInfoDetails details)
                 throws OperationHandlerException

Fetch information about the asynchronously started operation.

Parameters:

context - Context for the call.

details - Details for the call including the operation ID.

Returns:

Information about the operation.

Throws:

OperationHandlerException - Unexpected failures while running the handler. This should be thrown with a type of OperationHandlerException.ErrorType.NOT_FOUND if the operation ID is not found.

java.lang.RuntimeException - Any other exception, will be converted to an OperationHandlerException of type OperationHandlerException.ErrorType.INTERNAL.

cancel

void cancel(OperationContext context,
            OperationCancelDetails details)
     throws OperationHandlerException

Cancel the asynchronously started operation.

This does not need to wait for cancellation to be processed, simply that cancellation is delivered. Duplicate cancellation requests for an operation or cancellation requests for an operation not running should just be ignored.

Parameters:

context - Context for the call.

details - Details for the call including the operation ID.

Throws:

OperationHandlerException - Unexpected failures while running the handler. This should be thrown with a type of OperationHandlerException.ErrorType.NOT_FOUND if the operation ID is not found.

java.lang.RuntimeException - Any other exception, will be converted to an OperationHandlerException of type OperationHandlerException.ErrorType.INTERNAL.