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.client;
020
021import java.util.List;
022
023import org.apache.hadoop.classification.InterfaceAudience;
024import org.apache.hadoop.classification.InterfaceStability;
025import org.apache.hadoop.io.Text;
026import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
027import org.apache.hadoop.yarn.api.records.ApplicationId;
028import org.apache.hadoop.yarn.api.records.ApplicationReport;
029import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
030import org.apache.hadoop.yarn.api.records.DelegationToken;
031import org.apache.hadoop.yarn.api.records.NodeReport;
032import org.apache.hadoop.yarn.api.records.QueueInfo;
033import org.apache.hadoop.yarn.api.records.QueueUserACLInfo;
034import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
035import org.apache.hadoop.yarn.exceptions.YarnRemoteException;
036import org.apache.hadoop.yarn.service.Service;
037
038@InterfaceAudience.Public
039@InterfaceStability.Evolving
040public interface YarnClient extends Service {
041
042  /**
043   * <p>
044   * Obtain a new {@link ApplicationId} for submitting new applications.
045   * </p>
046   * 
047   * <p>
048   * Returns a response which contains {@link ApplicationId} that can be used to
049   * submit a new application. See
050   * {@link #submitApplication(ApplicationSubmissionContext)}.
051   * </p>
052   * 
053   * <p>
054   * See {@link GetNewApplicationResponse} for other information that is
055   * returned.
056   * </p>
057   * 
058   * @return response containing the new <code>ApplicationId</code> to be used
059   *         to submit an application
060   * @throws YarnRemoteException
061   */
062  GetNewApplicationResponse getNewApplication() throws YarnRemoteException;
063
064  /**
065   * <p>
066   * Submit a new application to <code>YARN.</code>
067   * </p>
068   * 
069   * @param appContext
070   *          {@link ApplicationSubmissionContext} containing all the details
071   *          needed to submit a new application
072   * @return {@link ApplicationId} of the accepted application
073   * @throws YarnRemoteException
074   * @see #getNewApplication()
075   */
076  ApplicationId submitApplication(ApplicationSubmissionContext appContext)
077      throws YarnRemoteException;
078
079  /**
080   * <p>
081   * Kill an application identified by given ID.
082   * </p>
083   * 
084   * @param applicationId
085   *          {@link ApplicationId} of the application that needs to be killed
086   * @throws YarnRemoteException
087   *           in case of errors or if YARN rejects the request due to
088   *           access-control restrictions.
089   * @see #getQueueAclsInfo()
090   */
091  void killApplication(ApplicationId applicationId) throws YarnRemoteException;
092
093  /**
094   * <p>
095   * Get a report of the given Application.
096   * </p>
097   * 
098   * <p>
099   * In secure mode, <code>YARN</code> verifies access to the application, queue
100   * etc. before accepting the request.
101   * </p>
102   * 
103   * <p>
104   * If the user does not have <code>VIEW_APP</code> access then the following
105   * fields in the report will be set to stubbed values:
106   * <ul>
107   * <li>host - set to "N/A"</li>
108   * <li>RPC port - set to -1</li>
109   * <li>client token - set to "N/A"</li>
110   * <li>diagnostics - set to "N/A"</li>
111   * <li>tracking URL - set to "N/A"</li>
112   * <li>original tracking URL - set to "N/A"</li>
113   * <li>resource usage report - all values are -1</li>
114   * </ul>
115   * </p>
116   * 
117   * @param appId
118   *          {@link ApplicationId} of the application that needs a report
119   * @return application report
120   * @throws YarnRemoteException
121   */
122  ApplicationReport getApplicationReport(ApplicationId appId)
123      throws YarnRemoteException;
124
125  /**
126   * <p>
127   * Get a report (ApplicationReport) of all Applications in the cluster.
128   * </p>
129   * 
130   * <p>
131   * If the user does not have <code>VIEW_APP</code> access for an application
132   * then the corresponding report will be filtered as described in
133   * {@link #getApplicationReport(ApplicationId)}.
134   * </p>
135   * 
136   * @return a list of reports of all running applications
137   * @throws YarnRemoteException
138   */
139  List<ApplicationReport> getApplicationList() throws YarnRemoteException;
140
141  /**
142   * <p>
143   * Get metrics ({@link YarnClusterMetrics}) about the cluster.
144   * </p>
145   * 
146   * @return cluster metrics
147   * @throws YarnRemoteException
148   */
149  YarnClusterMetrics getYarnClusterMetrics() throws YarnRemoteException;
150
151  /**
152   * <p>
153   * Get a report of all nodes ({@link NodeReport}) in the cluster.
154   * </p>
155   * 
156   * @return A list of report of all nodes
157   * @throws YarnRemoteException
158   */
159  List<NodeReport> getNodeReports() throws YarnRemoteException;
160
161  /**
162   * <p>
163   * Get a delegation token so as to be able to talk to YARN using those tokens.
164   * 
165   * @param renewer
166   *          Address of the renewer who can renew these tokens when needed by
167   *          securely talking to YARN.
168   * @return a delegation token ({@link DelegationToken}) that can be used to
169   *         talk to YARN
170   * @throws YarnRemoteException
171   */
172  DelegationToken getRMDelegationToken(Text renewer) throws YarnRemoteException;
173
174  /**
175   * <p>
176   * Get information ({@link QueueInfo}) about a given <em>queue</em>.
177   * </p>
178   * 
179   * @param queueName
180   *          Name of the queue whose information is needed
181   * @return queue information
182   * @throws YarnRemoteException
183   *           in case of errors or if YARN rejects the request due to
184   *           access-control restrictions.
185   */
186  QueueInfo getQueueInfo(String queueName) throws YarnRemoteException;
187
188  /**
189   * <p>
190   * Get information ({@link QueueInfo}) about all queues, recursively if there
191   * is a hierarchy
192   * </p>
193   * 
194   * @return a list of queue-information for all queues
195   * @throws YarnRemoteException
196   */
197  List<QueueInfo> getAllQueues() throws YarnRemoteException;
198
199  /**
200   * <p>
201   * Get information ({@link QueueInfo}) about top level queues.
202   * </p>
203   * 
204   * @return a list of queue-information for all the top-level queues
205   * @throws YarnRemoteException
206   */
207  List<QueueInfo> getRootQueueInfos() throws YarnRemoteException;
208
209  /**
210   * <p>
211   * Get information ({@link QueueInfo}) about all the immediate children queues
212   * of the given queue
213   * </p>
214   * 
215   * @param parent
216   *          Name of the queue whose child-queues' information is needed
217   * @return a list of queue-information for all queues who are direct children
218   *         of the given parent queue.
219   * @throws YarnRemoteException
220   */
221  List<QueueInfo> getChildQueueInfos(String parent) throws YarnRemoteException;
222
223  /**
224   * <p>
225   * Get information about <em>acls</em> for <em>current user</em> on all the
226   * existing queues.
227   * </p>
228   * 
229   * @return a list of queue acls ({@link QueueUserACLInfo}) for
230   *         <em>current user</em>
231   * @throws YarnRemoteException
232   */
233  List<QueueUserACLInfo> getQueueAclsInfo() throws YarnRemoteException;
234}