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;
020
021 import java.util.List;
022
023 import org.apache.hadoop.classification.InterfaceAudience;
024 import org.apache.hadoop.classification.InterfaceStability;
025 import org.apache.hadoop.io.Text;
026 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
027 import org.apache.hadoop.yarn.api.records.ApplicationId;
028 import org.apache.hadoop.yarn.api.records.ApplicationReport;
029 import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
030 import org.apache.hadoop.yarn.api.records.DelegationToken;
031 import org.apache.hadoop.yarn.api.records.NodeReport;
032 import org.apache.hadoop.yarn.api.records.QueueInfo;
033 import org.apache.hadoop.yarn.api.records.QueueUserACLInfo;
034 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
035 import org.apache.hadoop.yarn.exceptions.YarnRemoteException;
036 import org.apache.hadoop.yarn.service.Service;
037
038 @InterfaceAudience.Public
039 @InterfaceStability.Evolving
040 public 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 }