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 OperationException,
                              HandlerException

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 token 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 token representing an asynchronously running operation.

Throws:

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

HandlerException - Unexpected failures while running the handler.

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

fetchResult

R fetchResult(OperationContext context,
              OperationFetchResultDetails details)
       throws OperationStillRunningException,
              OperationException,
              HandlerException

Fetch the result for an asynchronously started operation.

Parameters:

context - Context for the call.

details - Details for the call including the operation token. 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.

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

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

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

fetchInfo

OperationInfo fetchInfo(OperationContext context,
                        OperationFetchInfoDetails details)
                 throws HandlerException

Fetch information about the asynchronously started operation.

Parameters:

context - Context for the call.

details - Details for the call including the operation token.

Returns:

Information about the operation.

Throws:

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

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

cancel

void cancel(OperationContext context,
            OperationCancelDetails details)
     throws HandlerException

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

Throws:

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

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