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 com.gh.bmd.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 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.

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

 * Any exception escaping the invocation methods, unless it extends the base
 * {@link com.gh.bmd.jrt.channel.RoutineException RoutineException}, will be wrapped as the cause
 * of an {@link com.gh.bmd.jrt.invocation.InvocationException InvocationException} instance.
 * 
 * Created by davide-maestroni 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 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(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.
     */
    void onResult(@Nonnull ResultChannel result);

    /**
     * Called when the invocation execution has completed.
     */
    void onTerminate();
}