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.client.api;
020    
021    import java.io.IOException;
022    import java.util.EnumSet;
023    import java.util.List;
024    import java.util.Set;
025    
026    import org.apache.hadoop.classification.InterfaceAudience;
027    import org.apache.hadoop.classification.InterfaceAudience.Private;
028    import org.apache.hadoop.classification.InterfaceAudience.Public;
029    import org.apache.hadoop.classification.InterfaceStability;
030    import org.apache.hadoop.io.Text;
031    import org.apache.hadoop.service.AbstractService;
032    import org.apache.hadoop.yarn.api.records.ApplicationId;
033    import org.apache.hadoop.yarn.api.records.ApplicationReport;
034    import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
035    import org.apache.hadoop.yarn.api.records.NodeReport;
036    import org.apache.hadoop.yarn.api.records.NodeState;
037    import org.apache.hadoop.yarn.api.records.QueueInfo;
038    import org.apache.hadoop.yarn.api.records.QueueUserACLInfo;
039    import org.apache.hadoop.yarn.api.records.Token;
040    import org.apache.hadoop.yarn.api.records.YarnApplicationState;
041    import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
042    import org.apache.hadoop.yarn.client.api.impl.YarnClientImpl;
043    import org.apache.hadoop.yarn.exceptions.YarnException;
044    import org.apache.hadoop.yarn.security.AMRMTokenIdentifier;
045    
046    @InterfaceAudience.Public
047    @InterfaceStability.Stable
048    public abstract class YarnClient extends AbstractService {
049    
050      /**
051       * Create a new instance of YarnClient.
052       */
053      @Public
054      public static YarnClient createYarnClient() {
055        YarnClient client = new YarnClientImpl();
056        return client;
057      }
058    
059      @Private
060      protected YarnClient(String name) {
061        super(name);
062      }
063    
064      /**
065       * <p>
066       * Obtain a {@link YarnClientApplication} for a new application,
067       * which in turn contains the {@link ApplicationSubmissionContext} and
068       * {@link org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse}
069       * objects.
070       * </p>
071       *
072       * @return {@link YarnClientApplication} built for a new application
073       * @throws YarnException
074       * @throws IOException
075       */
076      public abstract YarnClientApplication createApplication()
077          throws YarnException, IOException;
078    
079      /**
080       * <p>
081       * Submit a new application to <code>YARN.</code> It is a blocking call, such
082       * that it will not return {@link ApplicationId} until the submitted
083       * application has been submitted and accepted by the ResourceManager.
084       * </p>
085       * 
086       * @param appContext
087       *          {@link ApplicationSubmissionContext} containing all the details
088       *          needed to submit a new application
089       * @return {@link ApplicationId} of the accepted application
090       * @throws YarnException
091       * @throws IOException
092       * @see #createApplication()
093       */
094      public abstract ApplicationId submitApplication(ApplicationSubmissionContext appContext)
095          throws YarnException, IOException;
096    
097      /**
098       * <p>
099       * Kill an application identified by given ID.
100       * </p>
101       * 
102       * @param applicationId
103       *          {@link ApplicationId} of the application that needs to be killed
104       * @throws YarnException
105       *           in case of errors or if YARN rejects the request due to
106       *           access-control restrictions.
107       * @throws IOException
108       * @see #getQueueAclsInfo()
109       */
110      public abstract void killApplication(ApplicationId applicationId) throws YarnException,
111          IOException;
112    
113      /**
114       * <p>
115       * Get a report of the given Application.
116       * </p>
117       * 
118       * <p>
119       * In secure mode, <code>YARN</code> verifies access to the application, queue
120       * etc. before accepting the request.
121       * </p>
122       * 
123       * <p>
124       * If the user does not have <code>VIEW_APP</code> access then the following
125       * fields in the report will be set to stubbed values:
126       * <ul>
127       * <li>host - set to "N/A"</li>
128       * <li>RPC port - set to -1</li>
129       * <li>client token - set to "N/A"</li>
130       * <li>diagnostics - set to "N/A"</li>
131       * <li>tracking URL - set to "N/A"</li>
132       * <li>original tracking URL - set to "N/A"</li>
133       * <li>resource usage report - all values are -1</li>
134       * </ul>
135       * </p>
136       * 
137       * @param appId
138       *          {@link ApplicationId} of the application that needs a report
139       * @return application report
140       * @throws YarnException
141       * @throws IOException
142       */
143      public abstract ApplicationReport getApplicationReport(ApplicationId appId)
144          throws YarnException, IOException;
145    
146      /**
147       * Get the AMRM token of the application.
148       * <p/>
149       * The AMRM token is required for AM to RM scheduling operations. For 
150       * managed Application Masters Yarn takes care of injecting it. For unmanaged
151       * Applications Masters, the token must be obtained via this method and set
152       * in the {@link org.apache.hadoop.security.UserGroupInformation} of the
153       * current user.
154       * <p/>
155       * The AMRM token will be returned only if all the following conditions are
156       * met:
157       * <li>
158       *   <ul>the requester is the owner of the ApplicationMaster</ul>
159       *   <ul>the application master is an unmanaged ApplicationMaster</ul>
160       *   <ul>the application master is in ACCEPTED state</ul>
161       * </li>
162       * Else this method returns NULL.
163       *
164       * @param appId {@link ApplicationId} of the application to get the AMRM token
165       * @return the AMRM token if available
166       * @throws YarnException
167       * @throws IOException
168       */
169      public abstract org.apache.hadoop.security.token.Token<AMRMTokenIdentifier>
170          getAMRMToken(ApplicationId appId) throws YarnException, IOException;
171    
172      /**
173       * <p>
174       * Get a report (ApplicationReport) of all Applications in the cluster.
175       * </p>
176       *
177       * <p>
178       * If the user does not have <code>VIEW_APP</code> access for an application
179       * then the corresponding report will be filtered as described in
180       * {@link #getApplicationReport(ApplicationId)}.
181       * </p>
182       *
183       * @return a list of reports of all running applications
184       * @throws YarnException
185       * @throws IOException
186       */
187      public abstract List<ApplicationReport> getApplications()
188          throws YarnException, IOException;
189    
190      /**
191       * <p>
192       * Get a report (ApplicationReport) of Applications
193       * matching the given application types in the cluster.
194       * </p>
195       *
196       * <p>
197       * If the user does not have <code>VIEW_APP</code> access for an application
198       * then the corresponding report will be filtered as described in
199       * {@link #getApplicationReport(ApplicationId)}.
200       * </p>
201       *
202       * @param applicationTypes
203       * @return a list of reports of applications
204       * @throws YarnException
205       * @throws IOException
206       */
207      public abstract List<ApplicationReport> getApplications(
208          Set<String> applicationTypes) throws YarnException, IOException;
209    
210      /**
211       * <p>
212       * Get a report (ApplicationReport) of Applications matching the given
213       * application states in the cluster.
214       * </p>
215       *
216       * <p>
217       * If the user does not have <code>VIEW_APP</code> access for an application
218       * then the corresponding report will be filtered as described in
219       * {@link #getApplicationReport(ApplicationId)}.
220       * </p>
221       *
222       * @param applicationStates
223       * @return a list of reports of applications
224       * @throws YarnException
225       * @throws IOException
226       */
227      public abstract List<ApplicationReport>
228          getApplications(EnumSet<YarnApplicationState> applicationStates)
229              throws YarnException, IOException;
230    
231      /**
232       * <p>
233       * Get a report (ApplicationReport) of Applications matching the given
234       * application types and application states in the cluster.
235       * </p>
236       *
237       * <p>
238       * If the user does not have <code>VIEW_APP</code> access for an application
239       * then the corresponding report will be filtered as described in
240       * {@link #getApplicationReport(ApplicationId)}.
241       * </p>
242       *
243       * @param applicationTypes
244       * @param applicationStates
245       * @return a list of reports of applications
246       * @throws YarnException
247       * @throws IOException
248       */
249      public abstract List<ApplicationReport> getApplications(
250          Set<String> applicationTypes,
251          EnumSet<YarnApplicationState> applicationStates) throws YarnException,
252          IOException;
253    
254      /**
255       * <p>
256       * Get metrics ({@link YarnClusterMetrics}) about the cluster.
257       * </p>
258       * 
259       * @return cluster metrics
260       * @throws YarnException
261       * @throws IOException
262       */
263      public abstract YarnClusterMetrics getYarnClusterMetrics() throws YarnException,
264          IOException;
265    
266      /**
267       * <p>
268       * Get a report of nodes ({@link NodeReport}) in the cluster.
269       * </p>
270       * 
271       * @param states The {@link NodeState}s to filter on. If no filter states are
272       *          given, nodes in all states will be returned.
273       * @return A list of node reports
274       * @throws YarnException
275       * @throws IOException
276       */
277      public abstract List<NodeReport> getNodeReports(NodeState... states)
278          throws YarnException, IOException;
279    
280      /**
281       * <p>
282       * Get a delegation token so as to be able to talk to YARN using those tokens.
283       * 
284       * @param renewer
285       *          Address of the renewer who can renew these tokens when needed by
286       *          securely talking to YARN.
287       * @return a delegation token ({@link Token}) that can be used to
288       *         talk to YARN
289       * @throws YarnException
290       * @throws IOException
291       */
292      public abstract Token getRMDelegationToken(Text renewer)
293          throws YarnException, IOException;
294    
295      /**
296       * <p>
297       * Get information ({@link QueueInfo}) about a given <em>queue</em>.
298       * </p>
299       * 
300       * @param queueName
301       *          Name of the queue whose information is needed
302       * @return queue information
303       * @throws YarnException
304       *           in case of errors or if YARN rejects the request due to
305       *           access-control restrictions.
306       * @throws IOException
307       */
308      public abstract QueueInfo getQueueInfo(String queueName) throws YarnException,
309          IOException;
310    
311      /**
312       * <p>
313       * Get information ({@link QueueInfo}) about all queues, recursively if there
314       * is a hierarchy
315       * </p>
316       * 
317       * @return a list of queue-information for all queues
318       * @throws YarnException
319       * @throws IOException
320       */
321      public abstract List<QueueInfo> getAllQueues() throws YarnException, IOException;
322    
323      /**
324       * <p>
325       * Get information ({@link QueueInfo}) about top level queues.
326       * </p>
327       * 
328       * @return a list of queue-information for all the top-level queues
329       * @throws YarnException
330       * @throws IOException
331       */
332      public abstract List<QueueInfo> getRootQueueInfos() throws YarnException, IOException;
333    
334      /**
335       * <p>
336       * Get information ({@link QueueInfo}) about all the immediate children queues
337       * of the given queue
338       * </p>
339       * 
340       * @param parent
341       *          Name of the queue whose child-queues' information is needed
342       * @return a list of queue-information for all queues who are direct children
343       *         of the given parent queue.
344       * @throws YarnException
345       * @throws IOException
346       */
347      public abstract List<QueueInfo> getChildQueueInfos(String parent) throws YarnException,
348          IOException;
349    
350      /**
351       * <p>
352       * Get information about <em>acls</em> for <em>current user</em> on all the
353       * existing queues.
354       * </p>
355       * 
356       * @return a list of queue acls ({@link QueueUserACLInfo}) for
357       *         <em>current user</em>
358       * @throws YarnException
359       * @throws IOException
360       */
361      public abstract List<QueueUserACLInfo> getQueueAclsInfo() throws YarnException,
362          IOException;
363    }