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 * <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
053public 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}