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 */
018package org.apache.oozie.workflow;
019
020import org.apache.hadoop.conf.Configuration;
021import org.apache.oozie.workflow.lite.NodeDef;
022
023import java.util.Map;
024
025/**
026 * A workflow instance is an executable instance of a {@link WorkflowApp}.
027 */
028public 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}