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