com.github.dm.jrt.invocation

Interface Invocation<IN,OUT>

Type Parameters:

IN - the input data type.

OUT - the output data type.

All Known Implementing Classes:

CommandInvocation, DelegatingInvocation, FilterInvocation, FunctionInvocation, InvocationDecorator, PassingInvocation, TemplateInvocation

public interface Invocation<IN,OUT>

Interface defining a routine invocation.

The typical lifecycle of an invocation object is the one depicted below:

     

                   <init>

                   |     |
                   |     |-------------------------------
                   V     |                               |
            ----------------                             |
        --->|onInitialize()|-----------                  |
       |    ----------------           |                 |
       |           |      ------       |                 |
       |           |     |      |      |                 |
       |           V     V      |      |                 |
       |    ----------------    |      |                 |
       |    |  onInput()   |----       |                 |
       |    ----------------           V                 |
       |           |     |         ----------------      |
       |           |     |-------->|  onAbort()   |      |
       |           V     |         ----------------      |
       |    ----------------           |     |           |
       |    |  onResult()  |           |     |           |
       |    ----------------           |     |           |
       |           |      -------------      |           |
       |           |     |              (if exception is thrown)
       |           V     V                   |           |
       |    -----------------                |           |
        ----| onTerminate() |                |           |
            -----------------                |           |
                   |      -------------------------------
                   |     |
                   V     V
            -----------------
            |  onDestroy()  |
            -----------------
     
 

Note that the onInput() method will be called for each input passed to the routine, so, in case no input is expected, the onResult() method will be called soon after the initialization.

Note also that onAbort() might be called at any time between onInitialize() and onTerminate() in case the execution is aborted.
The only case in which the onTerminate() method does not get call at all, is when an exception escapes the onAbort() method invocation.

The onTerminate() method is meant to allow the clean up and reset operations needed to prepare the invocation object to be reused. When the method is not called or does not complete successfully, the invocation object is discarded.
While the onDestroy() method is meant to indicate that the invocation object is no longer needed, so any associated resource can be safely released. Note that this method may never get called if the routine is automatically garbage collected.

Keep in mind, when implementing an invocation class, that the result channel passed to the onInput() and onResult() methods will be closed as soon as the latter exits.
Any further attempt to post results will generate an exception.
It is anyway possible to keep on generating results by passing to the result channel an output or an I/O channel.

Be aware that there is no guarantee about how and when an invocation will produce a result. It might return one or more output for each input, or no output at all.

Any exception escaping the invocation methods, unless it extends the base RoutineException, will be wrapped as the cause of an InvocationException instance.

Created by davide-maestroni on 09/07/2014.

Method Summary

Methods

Modifier and Type	Method and Description
void	onAbort(RoutineException reason) Called when the routine execution is aborted. This method may be called at any time after the invocation initialization.
void	onDestroy() Called when the routine invocation is no longer needed.
void	onInitialize() Called when the routine invocation is initialized. This is always the first method in the invocation lifecycle.
void	onInput(IN input, ResultChannel<OUT> result) Called when an input is passed to the routine. This method is called once for each input object.
void	onResult(ResultChannel<OUT> result) Called when all the inputs has been passed to the routine. This method is called once in the invocation lifecycle to indicate that the final invocation results should be passed to the result channel.
void	onTerminate() Called when the invocation execution has completed.

Method Detail

onAbort

void onAbort(@Nullable
           RoutineException reason)

Called when the routine execution is aborted.
This method may be called at any time after the invocation initialization.

Parameters:

reason - the reason of the abortion.

onDestroy

void onDestroy()

Called when the routine invocation is no longer needed.

onInitialize

void onInitialize()

Called when the routine invocation is initialized.
This is always the first method in the invocation lifecycle.

onInput

void onInput(IN input,
           @NotNull
           ResultChannel<OUT> result)

Called when an input is passed to the routine.
This method is called once for each input object.

Parameters:

input - the input.

result - the result channel.

onResult

void onResult(@NotNull
            ResultChannel<OUT> result)

Called when all the inputs has been passed to the routine.
This method is called once in the invocation lifecycle to indicate that the final invocation results should be passed to the result channel.

Parameters:

result - the result channel.

onTerminate

void onTerminate()

Called when the invocation execution has completed.