| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You 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 org.apache.ignite.compute; |
| |
| import java.io.Serializable; |
| import java.util.List; |
| import org.apache.ignite.IgniteCheckedException; |
| import org.apache.ignite.IgniteException; |
| |
| /** |
| * Defines executable unit for {@link ComputeTask}. |
| * <h1 class="header">Description</h1> |
| * Grid job is an executable unit of {@link ComputeTask}. Grid task gets split into jobs |
| * when {@link ComputeTask#map(List, Object)} method is called. This method returns |
| * all jobs for the task mapped to their corresponding grid nodes for execution. Grid |
| * will then serialize this jobs and send them to requested nodes for execution. |
| * When a node receives a request to execute a job, the following sequence of events |
| * takes place: |
| * <ol> |
| * <li> |
| * If collision SPI is defined, then job gets put on waiting list which is passed to underlying |
| * {@link org.apache.ignite.spi.collision.CollisionSpi} SPI. Otherwise job will be submitted to the executor |
| * service responsible for job execution immediately upon arrival. |
| * </li> |
| * <li> |
| * If collision SPI is configured, then it will decide one of the following scheduling policies: |
| * <ul> |
| * <li> |
| * Job will be kept on waiting list. In this case, job will not get a |
| * chance to execute until next time the Collision SPI is called. |
| * </li> |
| * <li> |
| * Job will be moved to active list. In this case system will proceed |
| * with job execution. |
| * </li> |
| * <li> |
| * Job will be rejected. In this case the {@link ComputeJobResult} passed into |
| * {@link ComputeTask#result(ComputeJobResult, List)} method will contain |
| * {@link ComputeExecutionRejectedException} exception. If you are using any |
| * of the task adapters shipped with Ignite, then job will be failed |
| * over automatically for execution on another node. |
| * </li> |
| * </ul> |
| * </li> |
| * <li> |
| * For activated jobs, an instance of distributed task session (see {@link ComputeTaskSession}) |
| * will be injected. |
| * </li> |
| * <li> |
| * System will execute the job by calling {@link ComputeJob#execute()} method. |
| * </li> |
| * <li> |
| * If job gets cancelled while executing then {@link ComputeJob#cancel()} |
| * method will be called. Note that just like with {@link Thread#interrupt()} |
| * method, grid job cancellation serves as a hint that a job should stop |
| * executing or exhibit some other user defined behavior. Generally it is |
| * up to a job to decide whether it wants to react to cancellation or |
| * ignore it. Job cancellation can happen for several reasons: |
| * <ul> |
| * <li>Collision SPI cancelled an active job.</li> |
| * <li>Parent task has completed without waiting for this job's result.</li> |
| * <li>User cancelled task by calling {@link ComputeTaskFuture#cancel()} method.</li> |
| * </ul> |
| * </li> |
| * <li> |
| * Once job execution is complete, the return value will be sent back to parent |
| * task and will be passed into {@link ComputeTask#result(ComputeJobResult, List)} |
| * method via {@link ComputeJobResult} instance. If job execution resulted |
| * in a checked exception, then {@link ComputeJobResult#getException()} method |
| * will contain that exception. If job execution threw a runtime exception |
| * or error, then it will be wrapped into {@link ComputeUserUndeclaredException} |
| * exception. |
| * </li> |
| * </ol> |
| * <p> |
| * <h1 class="header">Resource Injection</h1> |
| * Grid job implementation can be injected using IoC (dependency injection) with |
| * ignite resources. Both, field and method based injection are supported. |
| * The following ignite resources can be injected: |
| * <ul> |
| * <li>{@link org.apache.ignite.resources.TaskSessionResource}</li> |
| * <li>{@link org.apache.ignite.resources.JobContextResource}</li> |
| * <li>{@link org.apache.ignite.resources.IgniteInstanceResource}</li> |
| * <li>{@link org.apache.ignite.resources.LoggerResource}</li> |
| * <li>{@link org.apache.ignite.resources.SpringApplicationContextResource}</li> |
| * <li>{@link org.apache.ignite.resources.SpringResource}</li> |
| * </ul> |
| * Refer to corresponding resource documentation for more information. |
| * <p> |
| * <h1 class="header">ComputeJobAdapter</h1> |
| * Ignite comes with convenience {@link ComputeJobAdapter} adapter that provides |
| * default empty implementation for {@link ComputeJob#cancel()} method and also |
| * allows user to set and get job argument, if there is one. |
| * <p> |
| * <h1 class="header">Distributed Session Attributes</h1> |
| * Jobs can communicate with parent task and with other job siblings from the same |
| * task by setting session attributes (see {@link ComputeTaskSession}). Other jobs |
| * can wait for an attribute to be set either synchronously or asynchronously. |
| * Such functionality allows jobs to synchronize their execution with other jobs |
| * at any point and can be useful when other jobs within task need to be made aware |
| * of certain event or state change that occurred during job execution. |
| * <p> |
| * Distributed task session can be injected into {@link ComputeJob} implementation |
| * using {@link org.apache.ignite.resources.TaskSessionResource @TaskSessionResource} annotation. |
| * Both, field and method based injections are supported. Refer to |
| * {@link ComputeTaskSession} documentation for more information on session functionality. |
| * <p> |
| * <h1 class="header">Saving Checkpoints</h1> |
| * Long running jobs may wish to save intermediate checkpoints to protect themselves |
| * from failures. There are three checkpoint management methods: |
| * <ul> |
| * <li>{@link ComputeTaskSession#saveCheckpoint(String, Object, ComputeTaskSessionScope, long)}</li> |
| * <li>{@link ComputeTaskSession#loadCheckpoint(String)}</li> |
| * <li>{@link ComputeTaskSession#removeCheckpoint(String)}</li> |
| * </ul> |
| * Jobs that utilize checkpoint functionality should attempt to load a check |
| * point at the beginning of execution. If a {@code non-null} value is returned, |
| * then job can continue from where it failed last time, otherwise it would start |
| * from scratch. Throughout it's execution job should periodically save its |
| * intermediate state to avoid starting from scratch in case of a failure. |
| */ |
| public interface ComputeJob extends Serializable { |
| /** |
| * This method is called when system detects that completion of this |
| * job can no longer alter the overall outcome (for example, when parent task |
| * has already reduced the results). Job is also cancelled when |
| * {@link ComputeTaskFuture#cancel()} is called. |
| * <p> |
| * Note that job cancellation is only a hint, and just like with |
| * {@link Thread#interrupt()} method, it is really up to the actual job |
| * instance to gracefully finish execution and exit. |
| */ |
| public void cancel(); |
| |
| /** |
| * Executes this job. |
| * |
| * @return Job execution result (possibly {@code null}). This result will be returned |
| * in {@link ComputeJobResult#getData()} method passed into |
| * {@link ComputeTask#result(ComputeJobResult, List)} task method on caller node. |
| * @throws IgniteException If job execution caused an exception. This exception will be |
| * returned in {@link ComputeJobResult#getException()} method passed into |
| * {@link ComputeTask#result(ComputeJobResult, List)} task method on caller node. |
| * If execution produces a {@link RuntimeException} or {@link Error}, then |
| * it will be wrapped into {@link IgniteCheckedException}. |
| */ |
| public Object execute() throws IgniteException; |
| } |
