001 /** 002 * Copyright (c) 2010 Yahoo! Inc. All rights reserved. 003 * Licensed under the Apache License, Version 2.0 (the "License"); 004 * you may not use this file except in compliance with the License. 005 * You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software 010 * distributed under the License is distributed on an "AS IS" BASIS, 011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 012 * See the License for the specific language governing permissions and 013 * limitations under the License. See accompanying LICENSE file. 014 */ 015 package org.apache.oozie.workflow; 016 017 import org.apache.hadoop.conf.Configuration; 018 019 import java.util.Map; 020 021 /** 022 * A workflow instance is an executable instance of a {@link WorkflowApp}. 023 */ 024 public interface WorkflowInstance { 025 026 /** 027 * Separator to qualify variables belonging to a node. <p/> Variables names should be compossed as <code>nodeName + 028 * {@link #NODE_VAR_SEPARATOR} + varName</code>. 029 */ 030 public final static String NODE_VAR_SEPARATOR = "#"; 031 032 /** 033 * Defines the possible stati of a {@link WorkflowInstance}. 034 */ 035 public static enum Status { 036 PREP(false), 037 RUNNING(false), 038 SUSPENDED(false), 039 SUCCEEDED(true), 040 FAILED(true), 041 KILLED(true); 042 043 private boolean isEndState; 044 045 private Status(boolean isEndState) { 046 this.isEndState = isEndState; 047 } 048 049 /** 050 * Return if the status if an end state (it cannot change anymore). 051 * 052 * @return if the status if an end state (it cannot change anymore). 053 */ 054 public boolean isEndState() { 055 return isEndState; 056 } 057 058 } 059 060 /** 061 * Return the configuration of the instance. 062 * 063 * @return the configuration of the instance. 064 */ 065 public Configuration getConf(); 066 067 /** 068 * Return the ID of the instance. 069 * 070 * @return the ID of the instance. 071 */ 072 public String getId(); 073 074 /** 075 * Return the workflow application that defines the instance. 076 * 077 * @return the workflow application that defines the instance. 078 */ 079 public WorkflowApp getApp(); 080 081 /** 082 * Start the instance. 083 * 084 * @throws WorkflowException thrown if the instance could not be started. 085 */ 086 public boolean start() throws WorkflowException; 087 088 /** 089 * Signal the instance that a node has completed. 090 * 091 * @param path execution path of the node that has completed. 092 * @param signaValue signal value for the node. 093 * @return <code>true</code> if the instance has completed its execution, <code>false</code> otherwise. 094 */ 095 public boolean signal(String path, String signaValue) throws WorkflowException; 096 097 /** 098 * Fail the instance. <p/> All executing nodes will be be signaled for fail. 099 * 100 * @param nodeName the name of the node to be failed. 101 * @throws WorkflowException thrown if the instance could not be failed. 102 */ 103 public void fail(String nodeName) throws WorkflowException; 104 105 /** 106 * Kill the instance. <p/> All executing nodes will be be signaled for kill. 107 * 108 * @throws WorkflowException thrown if the instance could not be killed. 109 */ 110 public void kill() throws WorkflowException; 111 112 /** 113 * Suspend the instance. 114 * 115 * @throws WorkflowException thrown if the instance could not be suspended. 116 */ 117 public void suspend() throws WorkflowException; 118 119 /** 120 * Resume the instance. 121 * 122 * @throws WorkflowException thrown if the instance could not be resume. 123 */ 124 public void resume() throws WorkflowException; 125 126 /** 127 * Return the current status of the instance. 128 * 129 * @return the current status of the instance. 130 */ 131 public Status getStatus(); 132 133 /** 134 * Set a variable in the context of the instance. <p/> Variables are persisted with the instance. 135 * 136 * @param name variable name. 137 * @param value variable value, setting a <code>null</code> value removes the variable. 138 */ 139 public void setVar(String name, String value); 140 141 /** 142 * Return a variable from the context of the instance. 143 * 144 * @param name name of the variable. 145 * @return variable value, <code>null</code> if the variable is not in the context. 146 */ 147 public String getVar(String name); 148 149 /** 150 * Return a map with all the variables in the context of the instance. 151 * 152 * @return a map with all the variables in the context of the instance. 153 */ 154 public Map<String, String> getAllVars(); 155 156 /** 157 * Add a set of variables in the context of the instance. <p/> Variables are persisted with the instance. 158 * 159 * @param varMap map with the variables to add. 160 */ 161 public void setAllVars(Map<String, String> varMap); 162 163 /** 164 * Set a transient variable in the context of the instance. <p/> Transient variables are not persisted with the 165 * instance. 166 * 167 * @param name transient variable name. 168 * @param value transient variable value, setting a <code>null</code> value removes the variable. 169 */ 170 public void setTransientVar(String name, Object value); 171 172 /** 173 * Return a transient variable from the context of the instance. 174 * 175 * @param name name of the transient variable. 176 * @return transient variable value, <code>null</code> if the variable is not in the context. 177 */ 178 public Object getTransientVar(String name); 179 180 /** 181 * Return the transition a node did. <p/> This is meaninful only for action and decision nodes. 182 * 183 * @param node the node name. 184 * @return the transition the node did, <code>null</code> if the node didn't execute yet. 185 */ 186 public String getTransition(String node); 187 188 }