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;
019    
020    import java.io.IOException;
021    import java.io.Writer;
022    
023    import org.apache.hadoop.conf.Configuration;
024    import org.apache.oozie.client.CoordinatorJob;
025    import org.apache.oozie.client.WorkflowJob;
026    
027    public abstract class BaseEngine {
028        public static final String USE_XCOMMAND = "oozie.useXCommand";
029    
030        protected String user;
031        protected String authToken;
032    
033        /**
034         * Return the user name.
035         *
036         * @return the user name.
037         */
038        public String getUser() {
039            return user;
040        }
041    
042        /**
043         * Return the authentication token.
044         *
045         * @return the authentication token.
046         */
047        protected String getAuthToken() {
048            return authToken;
049        }
050    
051        /**
052         * Submit a job.
053         * <p/>
054         * It validates configuration properties.
055         *
056         * @param conf job configuration.
057         * @param startJob indicates if the job should be started or not.
058         * @return the job Id.
059         * @throws BaseEngineException thrown if the job could not be created.
060         */
061        public abstract String submitJob(Configuration conf, boolean startJob) throws BaseEngineException;
062    
063        /**
064         * Start a job.
065         *
066         * @param jobId job Id.
067         * @throws BaseEngineException thrown if the job could not be started.
068         */
069        public abstract void start(String jobId) throws BaseEngineException;
070    
071        /**
072         * Resume a job.
073         *
074         * @param jobId job Id.
075         * @throws BaseEngineException thrown if the job could not be resumed.
076         */
077        public abstract void resume(String jobId) throws BaseEngineException;
078    
079        /**
080         * Suspend a job.
081         *
082         * @param jobId job Id.
083         * @throws BaseEngineException thrown if the job could not be suspended.
084         */
085        public abstract void suspend(String jobId) throws BaseEngineException;
086    
087        /**
088         * Kill a job.
089         *
090         * @param jobId job Id.
091         * @throws BaseEngineException thrown if the job could not be killed.
092         */
093        public abstract void kill(String jobId) throws BaseEngineException;
094    
095        /**
096         * Change a coordinator job.
097         *
098         * @param jobId job Id.
099         * @param changeValue change value.
100         * @throws BaseEngineException thrown if the job could not be changed.
101         */
102        public abstract void change(String jobId, String changeValue) throws BaseEngineException;
103    
104        /**
105         * Rerun a job.
106         *
107         * @param jobId job Id to rerun.
108         * @param conf configuration information for the rerun.
109         * @throws BaseEngineException thrown if the job could not be rerun.
110         */
111        public abstract void reRun(String jobId, Configuration conf) throws BaseEngineException;
112    
113        /**
114         * Return the info about a wf job.
115         *
116         * @param jobId job Id.
117         * @return the workflow job info.
118         * @throws DagEngineException thrown if the job info could not be obtained.
119         */
120        public abstract WorkflowJob getJob(String jobId) throws BaseEngineException;
121    
122        /**
123         * Return the info about a wf job with actions subset.
124         *
125         * @param jobId job Id
126         * @param start starting from this index in the list of actions belonging to the job
127         * @param length number of actions to be returned
128         * @return the workflow job info.
129         * @throws DagEngineException thrown if the job info could not be obtained.
130         */
131        public abstract WorkflowJob getJob(String jobId, int start, int length) throws BaseEngineException;
132    
133        /**
134         * Return the info about a coord job.
135         *
136         * @param jobId job Id.
137         * @return the coord job info.
138         * @throws BaseEngineException thrown if the job info could not be obtained.
139         */
140        public abstract CoordinatorJob getCoordJob(String jobId) throws BaseEngineException;
141    
142        /**
143         * Return the info about a coord job with actions subset.
144         *
145         * @param jobId job Id.
146         * @param filter the status filter
147         * @param start starting from this index in the list of actions belonging to the job
148         * @param length number of actions to be returned
149         * @return the coord job info.
150         * @throws BaseEngineException thrown if the job info could not be obtained.
151         */
152        public abstract CoordinatorJob getCoordJob(String jobId, String filter, int start, int length) throws BaseEngineException;
153    
154        /**
155         * Return the a job definition.
156         *
157         * @param jobId job Id.
158         * @return the job definition.
159         * @throws BaseEngineException thrown if the job definition could no be obtained.
160         */
161        public abstract String getDefinition(String jobId) throws BaseEngineException;
162    
163        /**
164         * Stream the log of a job.
165         *
166         * @param jobId job Id.
167         * @param writer writer to stream the log to.
168         * @throws IOException thrown if the log cannot be streamed.
169         * @throws BaseEngineException thrown if there is error in getting the Workflow/Coordinator Job Information for
170         *         jobId.
171         */
172        public abstract void streamLog(String jobId, Writer writer) throws IOException, BaseEngineException;
173    
174        /**
175         * Return the workflow Job ID for an external ID.
176         * <p/>
177         * This is reverse lookup for recovery purposes.
178         *
179         * @param externalId external ID provided at job submission time.
180         * @return the associated workflow job ID if any, <code>null</code> if none.
181         * @throws BaseEngineException thrown if the lookup could not be done.
182         */
183        public abstract String getJobIdForExternalId(String externalId) throws BaseEngineException;
184    
185        /**
186         * Dry run a job; like {@link BaseEngine#submitJob(org.apache.hadoop.conf.Configuration, boolean) but doesn't actually execute
187         * the job.
188         * <p/>
189         * It validates configuration properties.
190         *
191         * @param conf job configuration.
192         * @return the result of the dryrun
193         * @throws BaseEngineException thrown if there was a problem doing the dryrun
194         */
195        public abstract String dryRunSubmit(Configuration conf) throws BaseEngineException;
196    
197    }