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
019 package org.apache.hadoop.yarn.api.records;
020
021 import org.apache.hadoop.classification.InterfaceAudience.Private;
022 import org.apache.hadoop.classification.InterfaceAudience.Public;
023 import org.apache.hadoop.classification.InterfaceStability.Stable;
024 import org.apache.hadoop.classification.InterfaceStability.Unstable;
025 import org.apache.hadoop.yarn.api.ApplicationClientProtocol;
026 import org.apache.hadoop.yarn.util.Records;
027
028 import java.util.Set;
029
030 /**
031 * <p><code>ApplicationReport</code> is a report of an application.</p>
032 *
033 * <p>It includes details such as:
034 * <ul>
035 * <li>{@link ApplicationId} of the application.</li>
036 * <li>Applications user.</li>
037 * <li>Application queue.</li>
038 * <li>Application name.</li>
039 * <li>Host on which the <code>ApplicationMaster</code> is running.</li>
040 * <li>RPC port of the <code>ApplicationMaster</code>.</li>
041 * <li>Tracking URL.</li>
042 * <li>{@link YarnApplicationState} of the application.</li>
043 * <li>Diagnostic information in case of errors.</li>
044 * <li>Start time of the application.</li>
045 * <li>Client {@link Token} of the application (if security is enabled).</li>
046 * </ul>
047 * </p>
048 *
049 * @see ApplicationClientProtocol#getApplicationReport(org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest)
050 */
051 @Public
052 @Stable
053 public abstract class ApplicationReport {
054
055 @Private
056 @Unstable
057 public static ApplicationReport newInstance(ApplicationId applicationId,
058 ApplicationAttemptId applicationAttemptId, String user, String queue,
059 String name, String host, int rpcPort, Token clientToAMToken,
060 YarnApplicationState state, String diagnostics, String url,
061 long startTime, long finishTime, FinalApplicationStatus finalStatus,
062 ApplicationResourceUsageReport appResources, String origTrackingUrl,
063 float progress, String applicationType, Token amRmToken) {
064 ApplicationReport report = Records.newRecord(ApplicationReport.class);
065 report.setApplicationId(applicationId);
066 report.setCurrentApplicationAttemptId(applicationAttemptId);
067 report.setUser(user);
068 report.setQueue(queue);
069 report.setName(name);
070 report.setHost(host);
071 report.setRpcPort(rpcPort);
072 report.setClientToAMToken(clientToAMToken);
073 report.setYarnApplicationState(state);
074 report.setDiagnostics(diagnostics);
075 report.setTrackingUrl(url);
076 report.setStartTime(startTime);
077 report.setFinishTime(finishTime);
078 report.setFinalApplicationStatus(finalStatus);
079 report.setApplicationResourceUsageReport(appResources);
080 report.setOriginalTrackingUrl(origTrackingUrl);
081 report.setProgress(progress);
082 report.setApplicationType(applicationType);
083 report.setAMRMToken(amRmToken);
084 return report;
085 }
086
087 /**
088 * Get the <code>ApplicationId</code> of the application.
089 * @return <code>ApplicationId</code> of the application
090 */
091 @Public
092 @Stable
093 public abstract ApplicationId getApplicationId();
094
095 @Private
096 @Unstable
097 public abstract void setApplicationId(ApplicationId applicationId);
098
099 /**
100 * Get the <code>ApplicationAttemptId</code> of the current
101 * attempt of the application
102 * @return <code>ApplicationAttemptId</code> of the attempt
103 */
104 @Public
105 @Stable
106 public abstract ApplicationAttemptId getCurrentApplicationAttemptId();
107
108 @Private
109 @Unstable
110 public abstract void setCurrentApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
111
112 /**
113 * Get the <em>user</em> who submitted the application.
114 * @return <em>user</em> who submitted the application
115 */
116 @Public
117 @Stable
118 public abstract String getUser();
119
120 @Private
121 @Unstable
122 public abstract void setUser(String user);
123
124 /**
125 * Get the <em>queue</em> to which the application was submitted.
126 * @return <em>queue</em> to which the application was submitted
127 */
128 @Public
129 @Stable
130 public abstract String getQueue();
131
132 @Private
133 @Unstable
134 public abstract void setQueue(String queue);
135
136 /**
137 * Get the user-defined <em>name</em> of the application.
138 * @return <em>name</em> of the application
139 */
140 @Public
141 @Stable
142 public abstract String getName();
143
144 @Private
145 @Unstable
146 public abstract void setName(String name);
147
148 /**
149 * Get the <em>host</em> on which the <code>ApplicationMaster</code>
150 * is running.
151 * @return <em>host</em> on which the <code>ApplicationMaster</code>
152 * is running
153 */
154 @Public
155 @Stable
156 public abstract String getHost();
157
158 @Private
159 @Unstable
160 public abstract void setHost(String host);
161
162 /**
163 * Get the <em>RPC port</em> of the <code>ApplicationMaster</code>.
164 * @return <em>RPC port</em> of the <code>ApplicationMaster</code>
165 */
166 @Public
167 @Stable
168 public abstract int getRpcPort();
169
170 @Private
171 @Unstable
172 public abstract void setRpcPort(int rpcPort);
173
174 /**
175 * Get the <em>client token</em> for communicating with the
176 * <code>ApplicationMaster</code>.
177 * <p>
178 * <em>ClientToAMToken</em> is the security token used by the AMs to verify
179 * authenticity of any <code>client</code>.
180 * </p>
181 *
182 * <p>
183 * The <code>ResourceManager</code>, provides a secure token (via
184 * {@link ApplicationReport#getClientToAMToken()}) which is verified by the
185 * ApplicationMaster when the client directly talks to an AM.
186 * </p>
187 * @return <em>client token</em> for communicating with the
188 * <code>ApplicationMaster</code>
189 */
190 @Public
191 @Stable
192 public abstract Token getClientToAMToken();
193
194 @Private
195 @Unstable
196 public abstract void setClientToAMToken(Token clientToAMToken);
197
198 /**
199 * Get the <code>YarnApplicationState</code> of the application.
200 * @return <code>YarnApplicationState</code> of the application
201 */
202 @Public
203 @Stable
204 public abstract YarnApplicationState getYarnApplicationState();
205
206 @Private
207 @Unstable
208 public abstract void setYarnApplicationState(YarnApplicationState state);
209
210 /**
211 * Get the <em>diagnositic information</em> of the application in case of
212 * errors.
213 * @return <em>diagnositic information</em> of the application in case
214 * of errors
215 */
216 @Public
217 @Stable
218 public abstract String getDiagnostics();
219
220 @Private
221 @Unstable
222 public abstract void setDiagnostics(String diagnostics);
223
224 /**
225 * Get the <em>tracking url</em> for the application.
226 * @return <em>tracking url</em> for the application
227 */
228 @Public
229 @Stable
230 public abstract String getTrackingUrl();
231
232 @Private
233 @Unstable
234 public abstract void setTrackingUrl(String url);
235
236 /**
237 * Get the original not-proxied <em>tracking url</em> for the application.
238 * This is intended to only be used by the proxy itself.
239 * @return the original not-proxied <em>tracking url</em> for the application
240 */
241 @Private
242 @Unstable
243 public abstract String getOriginalTrackingUrl();
244
245 @Private
246 @Unstable
247 public abstract void setOriginalTrackingUrl(String url);
248
249 /**
250 * Get the <em>start time</em> of the application.
251 * @return <em>start time</em> of the application
252 */
253 @Public
254 @Stable
255 public abstract long getStartTime();
256
257 @Private
258 @Unstable
259 public abstract void setStartTime(long startTime);
260
261 /**
262 * Get the <em>finish time</em> of the application.
263 * @return <em>finish time</em> of the application
264 */
265 @Public
266 @Stable
267 public abstract long getFinishTime();
268
269 @Private
270 @Unstable
271 public abstract void setFinishTime(long finishTime);
272
273
274 /**
275 * Get the <em>final finish status</em> of the application.
276 * @return <em>final finish status</em> of the application
277 */
278 @Public
279 @Stable
280 public abstract FinalApplicationStatus getFinalApplicationStatus();
281
282 @Private
283 @Unstable
284 public abstract void setFinalApplicationStatus(FinalApplicationStatus finishState);
285
286 /**
287 * Retrieve the structure containing the job resources for this application
288 * @return the job resources structure for this application
289 */
290 @Public
291 @Stable
292 public abstract ApplicationResourceUsageReport getApplicationResourceUsageReport();
293
294 /**
295 * Store the structure containing the job resources for this application
296 * @param appResources structure for this application
297 */
298 @Private
299 @Unstable
300 public abstract void setApplicationResourceUsageReport(ApplicationResourceUsageReport appResources);
301
302 /**
303 * Get the application's progress ( range 0.0 to 1.0 )
304 * @return application's progress
305 */
306 @Public
307 @Stable
308 public abstract float getProgress();
309
310 @Private
311 @Unstable
312 public abstract void setProgress(float progress);
313
314 /**
315 * Get the application's Type
316 * @return application's Type
317 */
318 @Public
319 @Stable
320 public abstract String getApplicationType();
321
322 @Private
323 @Unstable
324 public abstract void setApplicationType(String applicationType);
325
326 /**
327 * Get all tags corresponding to the application
328 * @return Application's tags
329 */
330 @Public
331 @Stable
332 public abstract Set<String> getApplicationTags();
333
334 @Private
335 @Unstable
336 public abstract void setApplicationTags(Set<String> tags);
337
338 @Private
339 @Stable
340 public abstract void setAMRMToken(Token amRmToken);
341
342 /**
343 * Get the AMRM token of the application.
344 * <p/>
345 * The AMRM token is required for AM to RM scheduling operations. For
346 * managed Application Masters Yarn takes care of injecting it. For unmanaged
347 * Applications Masters, the token must be obtained via this method and set
348 * in the {@link org.apache.hadoop.security.UserGroupInformation} of the
349 * current user.
350 * <p/>
351 * The AMRM token will be returned only if all the following conditions are
352 * met:
353 * <li>
354 * <ul>the requester is the owner of the ApplicationMaster</ul>
355 * <ul>the application master is an unmanaged ApplicationMaster</ul>
356 * <ul>the application master is in ACCEPTED state</ul>
357 * </li>
358 * Else this method returns NULL.
359 *
360 * @return the AM to RM token if available.
361 */
362 @Public
363 @Stable
364 public abstract Token getAMRMToken();
365
366 }