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;
020
021 import org.apache.hadoop.classification.InterfaceAudience.Public;
022 import org.apache.hadoop.classification.InterfaceStability.Stable;
023
024 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenRequest;
025 import org.apache.hadoop.yarn.api.protocolrecords.GetDelegationTokenResponse;
026 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest;
027 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
028 import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsRequest;
029 import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsResponse;
030 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
031 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse;
032 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
033 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
034 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
035 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
036 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest;
037 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
038 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest;
039 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse;
040 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
041 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
042 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
043 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
044 import org.apache.hadoop.yarn.api.records.ApplicationId;
045 import org.apache.hadoop.yarn.api.records.ApplicationReport;
046 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
047 import org.apache.hadoop.yarn.api.records.NodeReport;
048 import org.apache.hadoop.yarn.api.records.DelegationToken;
049 import org.apache.hadoop.yarn.api.records.Resource;
050 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
051 import org.apache.hadoop.yarn.exceptions.YarnRemoteException;
052
053 /**
054 * <p>The protocol between clients and the <code>ResourceManager</code>
055 * to submit/abort jobs and to get information on applications, cluster metrics,
056 * nodes, queues and ACLs.</p>
057 */
058 @Public
059 @Stable
060 public interface ClientRMProtocol {
061 /**
062 * <p>The interface used by clients to obtain a new {@link ApplicationId} for
063 * submitting new applications.</p>
064 *
065 * <p>The <code>ResourceManager</code> responds with a new, monotonically
066 * increasing, {@link ApplicationId} which is used by the client to submit
067 * a new application.</p>
068 *
069 * <p>The <code>ResourceManager</code> also responds with details such
070 * as minimum and maximum resource capabilities in the cluster as specified in
071 * {@link GetNewApplicationResponse}.</p>
072 *
073 * @param request request to get a new <code>ApplicationId</code>
074 * @return response containing the new <code>ApplicationId</code> to be used
075 * to submit an application
076 * @throws YarnRemoteException
077 * @see #submitApplication(SubmitApplicationRequest)
078 */
079 public GetNewApplicationResponse getNewApplication(
080 GetNewApplicationRequest request)
081 throws YarnRemoteException;
082
083 /**
084 * <p>The interface used by clients to submit a new application to the
085 * <code>ResourceManager.</code></p>
086 *
087 * <p>The client is required to provide details such as queue,
088 * {@link Resource} required to run the <code>ApplicationMaster</code>,
089 * the equivalent of {@link ContainerLaunchContext} for launching
090 * the <code>ApplicationMaster</code> etc. via the
091 * {@link SubmitApplicationRequest}.</p>
092 *
093 * <p>Currently the <code>ResourceManager</code> sends an immediate (empty)
094 * {@link SubmitApplicationResponse} on accepting the submission and throws
095 * an exception if it rejects the submission.</p>
096 *
097 * <p> In secure mode,the <code>ResourceManager</code> verifies access to
098 * queues etc. before accepting the application submission.</p>
099 *
100 * @param request request to submit a new application
101 * @return (empty) response on accepting the submission
102 * @throws YarnRemoteException
103 * @see #getNewApplication(GetNewApplicationRequest)
104 */
105 public SubmitApplicationResponse submitApplication(
106 SubmitApplicationRequest request)
107 throws YarnRemoteException;
108
109 /**
110 * <p>The interface used by clients to request the
111 * <code>ResourceManager</code> to abort submitted application.</p>
112 *
113 * <p>The client, via {@link KillApplicationRequest} provides the
114 * {@link ApplicationId} of the application to be aborted.</p>
115 *
116 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
117 * application, queue etc. before terminating the application.</p>
118 *
119 * <p>Currently, the <code>ResourceManager</code> returns an empty response
120 * on success and throws an exception on rejecting the request.</p>
121 *
122 * @param request request to abort a submited application
123 * @return <code>ResourceManager</code> returns an empty response
124 * on success and throws an exception on rejecting the request
125 * @throws YarnRemoteException
126 * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest)
127 */
128 public KillApplicationResponse forceKillApplication(
129 KillApplicationRequest request)
130 throws YarnRemoteException;
131
132 /**
133 * <p>The interface used by clients to get a report of an Application from
134 * the <code>ResourceManager</code>.</p>
135 *
136 * <p>The client, via {@link GetApplicationReportRequest} provides the
137 * {@link ApplicationId} of the application.</p>
138 *
139 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
140 * application, queue etc. before accepting the request.</p>
141 *
142 * <p>The <code>ResourceManager</code> responds with a
143 * {@link GetApplicationReportResponse} which includes the
144 * {@link ApplicationReport} for the application.</p>
145 *
146 * @param request request for an application report
147 * @return application report
148 * @throws YarnRemoteException
149 */
150 public GetApplicationReportResponse getApplicationReport(
151 GetApplicationReportRequest request)
152 throws YarnRemoteException;
153
154 /**
155 * <p>The interface used by clients to get metrics about the cluster from
156 * the <code>ResourceManager</code>.</p>
157 *
158 * <p>The <code>ResourceManager</code> responds with a
159 * {@link GetClusterMetricsResponse} which includes the
160 * {@link YarnClusterMetrics} with details such as number of current
161 * nodes in the cluster.</p>
162 *
163 * @param request request for cluster metrics
164 * @return cluster metrics
165 * @throws YarnRemoteException
166 */
167 public GetClusterMetricsResponse getClusterMetrics(
168 GetClusterMetricsRequest request)
169 throws YarnRemoteException;
170
171 /**
172 * <p>The interface used by clients to get a report of all Applications
173 * in the cluster from the <code>ResourceManager</code>.</p>
174 *
175 * <p>The <code>ResourceManager</code> responds with a
176 * {@link GetAllApplicationsResponse} which includes the
177 * {@link ApplicationReport} for all the applications.</p>
178 *
179 * @param request request for report on all running applications
180 * @return report on all running applications
181 * @throws YarnRemoteException
182 */
183 public GetAllApplicationsResponse getAllApplications(
184 GetAllApplicationsRequest request)
185 throws YarnRemoteException;
186
187 /**
188 * <p>The interface used by clients to get a report of all nodes
189 * in the cluster from the <code>ResourceManager</code>.</p>
190 *
191 * <p>The <code>ResourceManager</code> responds with a
192 * {@link GetClusterNodesResponse} which includes the
193 * {@link NodeReport} for all the nodes in the cluster.</p>
194 *
195 * @param request request for report on all nodes
196 * @return report on all nodes
197 * @throws YarnRemoteException
198 */
199 public GetClusterNodesResponse getClusterNodes(
200 GetClusterNodesRequest request)
201 throws YarnRemoteException;
202
203 /**
204 * <p>The interface used by clients to get information about <em>queues</em>
205 * from the <code>ResourceManager</code>.</p>
206 *
207 * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
208 * as used/total resources, child queues, running applications etc.</p>
209 *
210 * <p> In secure mode,the <code>ResourceManager</code> verifies access before
211 * providing the information.</p>
212 *
213 * @param request request to get queue information
214 * @return queue information
215 * @throws YarnRemoteException
216 */
217 public GetQueueInfoResponse getQueueInfo(
218 GetQueueInfoRequest request)
219 throws YarnRemoteException;
220
221 /**
222 * <p>The interface used by clients to get information about <em>queue
223 * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
224 * </p>
225 *
226 * <p>The <code>ResourceManager</code> responds with queue acls for all
227 * existing queues.</p>
228 *
229 * @param request request to get queue acls for <em>current user</em>
230 * @return queue acls for <em>current user</em>
231 * @throws YarnRemoteException
232 */
233 public GetQueueUserAclsInfoResponse getQueueUserAcls(
234 GetQueueUserAclsInfoRequest request)
235 throws YarnRemoteException;
236
237 /**
238 * <p>The interface used by clients to get delegation token, enabling the
239 * containers to be able to talk to the service using those tokens.
240 *
241 * <p> The <code>ResourceManager</code> responds with the delegation token
242 * {@link DelegationToken} that can be used by the client to speak to this
243 * service.
244 * @param request request to get a delegation token for the client.
245 * @return delegation token that can be used to talk to this service
246 * @throws YarnRemoteException
247 */
248 public GetDelegationTokenResponse getDelegationToken(
249 GetDelegationTokenRequest request)
250 throws YarnRemoteException;
251 }