com.github.dm.jrt.invocation.Invocation Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jroutine Show documentation
Show all versions of jroutine Show documentation
Parallel programming on the go
/*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.github.dm.jrt.invocation;
import com.github.dm.jrt.channel.ResultChannel;
import com.github.dm.jrt.channel.RoutineException;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
/**
* Interface defining a routine invocation.
*
* The typical lifecycle of an invocation object is the one depicted below:
*
*
*
* | |
* | |-------------------------------
* V | |
* ---------------- |
* --->|onInitialize()|----------- |
* | ---------------- | |
* | | ------ | |
* | | | | | |
* | V V | | |
* | ---------------- | | |
* | | onInput() |---- | |
* | ---------------- V |
* | | | ---------------- |
* | | |-------->| onAbort() | |
* | V | ---------------- |
* | ---------------- | | |
* | | onResult() | | | |
* | ---------------- | | |
* | | ------------- | |
* | | | (if exception is thrown)
* | V V | |
* | ----------------- | |
* ----| onTerminate() | | |
* ----------------- | |
* | -------------------------------
* | |
* V V
* -----------------
* | onDestroy() |
* -----------------
*
*
* Note that the {@code onInput()} method will be called for each input passed to the routine, so,
* in case no input is expected, the {@code onResult()} method will be called soon after the
* initialization.
*
* Note also that {@code onAbort()} might be called at any time between {@code onInitialize()} and
* {@code onTerminate()} in case the execution is aborted.
*
* The only case in which the {@code onTerminate()} method does not get call at all, is when an
* exception escapes the {@code onAbort()} method invocation.
*
* The {@code 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.
* The {@code 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.
*
* Any exception escaping the invocation methods, unless it extends the base
* {@link com.github.dm.jrt.channel.RoutineException RoutineException}, will be wrapped as the cause
* of an {@link com.github.dm.jrt.invocation.InvocationException InvocationException} instance.
*
* Created by davide-maestroni on 09/07/2014.
*
* @param the input data type.
* @param the output data type.
*/
public interface Invocation {
/**
* Called when the routine execution is aborted.
* This method may be called at any time after the invocation initialization.
*
* @param reason the reason of the abortion.
*/
void onAbort(@Nullable RoutineException reason);
/**
* Called when the routine invocation is no longer needed.
*/
void onDestroy();
/**
* Called when the routine invocation is initialized.
* This is always the first method in the invocation lifecycle.
*/
void onInitialize();
/**
* Called when an input is passed to the routine.
* This method is called once for each input object.
*
* @param input the input.
* @param result the result channel.
*/
void onInput(IN input, @Nonnull ResultChannel 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.
*
* @param result the result channel.
*/
void onResult(@Nonnull ResultChannel result);
/**
* Called when the invocation execution has completed.
*/
void onTerminate();
}