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