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