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    }