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