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 }