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