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}