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