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 package org.apache.oozie.workflow;
019
020 import org.apache.hadoop.conf.Configuration;
021 import org.apache.oozie.workflow.lite.NodeDef;
022
023 import java.util.Map;
024
025 /**
026 * A workflow instance is an executable instance of a {@link WorkflowApp}.
027 */
028 public interface WorkflowInstance {
029
030 /**
031 * Separator to qualify variables belonging to a node. <p/> Variables names should be compossed as <code>nodeName +
032 * {@link #NODE_VAR_SEPARATOR} + varName</code>.
033 */
034 public final static String NODE_VAR_SEPARATOR = "#";
035
036 /**
037 * Defines the possible stati of a {@link WorkflowInstance}.
038 */
039 public static enum Status {
040 PREP(false),
041 RUNNING(false),
042 SUSPENDED(false),
043 SUCCEEDED(true),
044 FAILED(true),
045 KILLED(true);
046
047 private boolean isEndState;
048
049 private Status(boolean isEndState) {
050 this.isEndState = isEndState;
051 }
052
053 /**
054 * Return if the status if an end state (it cannot change anymore).
055 *
056 * @return if the status if an end state (it cannot change anymore).
057 */
058 public boolean isEndState() {
059 return isEndState;
060 }
061
062 }
063
064 /**
065 * Return the configuration of the instance.
066 *
067 * @return the configuration of the instance.
068 */
069 public Configuration getConf();
070
071 /**
072 * Return the ID of the instance.
073 *
074 * @return the ID of the instance.
075 */
076 public String getId();
077
078 /**
079 * Return the workflow application that defines the instance.
080 *
081 * @return the workflow application that defines the instance.
082 */
083 public WorkflowApp getApp();
084
085 /**
086 * Start the instance.
087 *
088 * @throws WorkflowException thrown if the instance could not be started.
089 */
090 public boolean start() throws WorkflowException;
091
092 /**
093 * Signal the instance that a node has completed.
094 *
095 * @param path execution path of the node that has completed.
096 * @param signaValue signal value for the node.
097 * @return <code>true</code> if the instance has completed its execution, <code>false</code> otherwise.
098 */
099 public boolean signal(String path, String signaValue) throws WorkflowException;
100
101 /**
102 * Fail the instance. <p/> All executing nodes will be be signaled for fail.
103 *
104 * @param nodeName the name of the node to be failed.
105 * @throws WorkflowException thrown if the instance could not be failed.
106 */
107 public void fail(String nodeName) throws WorkflowException;
108
109 /**
110 * Kill the instance. <p/> All executing nodes will be be signaled for kill.
111 *
112 * @throws WorkflowException thrown if the instance could not be killed.
113 */
114 public void kill() throws WorkflowException;
115
116 /**
117 * Suspend the instance.
118 *
119 * @throws WorkflowException thrown if the instance could not be suspended.
120 */
121 public void suspend() throws WorkflowException;
122
123 /**
124 * Resume the instance.
125 *
126 * @throws WorkflowException thrown if the instance could not be resume.
127 */
128 public void resume() throws WorkflowException;
129
130 /**
131 * Return the current status of the instance.
132 *
133 * @return the current status of the instance.
134 */
135 public Status getStatus();
136
137 /**
138 * Set a variable in the context of the instance. <p/> Variables are persisted with the instance.
139 *
140 * @param name variable name.
141 * @param value variable value, setting a <code>null</code> value removes the variable.
142 */
143 public void setVar(String name, String value);
144
145 /**
146 * Return a variable from the context of the instance.
147 *
148 * @param name name of the variable.
149 * @return variable value, <code>null</code> if the variable is not in the context.
150 */
151 public String getVar(String name);
152
153 /**
154 * Return a map with all the variables in the context of the instance.
155 *
156 * @return a map with all the variables in the context of the instance.
157 */
158 public Map<String, String> getAllVars();
159
160 /**
161 * Add a set of variables in the context of the instance. <p/> Variables are persisted with the instance.
162 *
163 * @param varMap map with the variables to add.
164 */
165 public void setAllVars(Map<String, String> varMap);
166
167 /**
168 * Set a transient variable in the context of the instance. <p/> Transient variables are not persisted with the
169 * instance.
170 *
171 * @param name transient variable name.
172 * @param value transient variable value, setting a <code>null</code> value removes the variable.
173 */
174 public void setTransientVar(String name, Object value);
175
176 /**
177 * Return a transient variable from the context of the instance.
178 *
179 * @param name name of the transient variable.
180 * @return transient variable value, <code>null</code> if the variable is not in the context.
181 */
182 public Object getTransientVar(String name);
183
184 /**
185 * Return the transition a node did. <p/> This is meaninful only for action and decision nodes.
186 *
187 * @param node the node name.
188 * @return the transition the node did, <code>null</code> if the node didn't execute yet.
189 */
190 public String getTransition(String node);
191
192 /**
193 * Get NodeDef from workflow instance
194 * @param executionPath execution path
195 * @return node def
196 */
197 public NodeDef getNodeDef(String executionPath);
198
199 }