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    }