com.gh.bmd.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
Parallel programming on the go
There is a newer version: 5.9.0
/**
 * 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.gh.bmd.jrt.invocation;

import com.gh.bmd.jrt.channel.ResultChannel;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * Interface defining the behavior of a routine invocation.
 * 
 * The typical lifecycle of an invocation object is the following:
 * 
 *     
 *
 *                  |
 *                  V
 *            --------------
 *        --->|  onInit()  |
 *       |    --------------
 *       |          |     ------
 *       |          |    |      |
 *       |          V    V      |
 *       |    --------------    |
 *       |    | onInput()  |----
 *       |    --------------
 *       |          |               --------------
 *       |          |        ...--->| onAbort()  |
 *       |          V               --------------
 *       |    --------------            |    |
 *       |    | onResult() |            |    |
 *       |    --------------            |    |
 *       |          |     --------------     |
 *       |          |    |                   | (if exception is thrown)
 *       |          V    V                   |
 *       |    --------------                 |
 *        ----| onReturn() |                 |
 *            --------------                 |
 *                  |     -------------------
 *                  |    |
 *                  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
 * onInit() and onReturn() in case the execution is
 * aborted.

 * The only case in which the onReturn() method does not get call at all, is
 * when an exception escapes the onAbort() method invocation.
 * 

 * The onReturn() 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 onDestroy() method is meant to indicate that the invocation object is no
 * longer needed, so any associated resource can be safely released.
 * 
 * Created by davide on 9/7/14.
 *
 * @param   the input data type.
 * @param  the output data type.
 */
public interface Invocation {

    /**
     * Called when the routine execution is aborted.

     * This method can be called at any time after the invocation initialization.
     *
     * @param reason the reason of the abortion.
     */
    public void onAbort(@Nullable Throwable reason);

    /**
     * Called when the routine invocation is no longer needed.
     */
    public void onDestroy();

    /**
     * Called when the routine invocation is initialized.

     * This is always the first method in the invocation lifecycle.
     */
    public void onInit();

    /**
     * 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.
     */
    public void onInput(INPUT 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.
     */
    public void onResult(@Nonnull ResultChannel result);

    /**
     * Called when the routine execution has completed.
     */
    public void onReturn();
}