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.api;
020
021import java.io.IOException;
022
023import org.apache.hadoop.classification.InterfaceAudience.Public;
024import org.apache.hadoop.classification.InterfaceStability.Stable;
025import org.apache.hadoop.classification.InterfaceStability.Unstable;
026import org.apache.hadoop.io.retry.Idempotent;
027import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest;
028import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest;
029import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse;
030import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsRequest;
031import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodeLabelsResponse;
032import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest;
033import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse;
034import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest;
035import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse;
036import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsRequest;
037import org.apache.hadoop.yarn.api.protocolrecords.GetNodesToLabelsResponse;
038import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest;
039import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse;
040import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
041import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
042import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest;
043import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse;
044import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesRequest;
045import org.apache.hadoop.yarn.api.protocolrecords.MoveApplicationAcrossQueuesResponse;
046import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteRequest;
047import org.apache.hadoop.yarn.api.protocolrecords.ReservationDeleteResponse;
048import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionRequest;
049import org.apache.hadoop.yarn.api.protocolrecords.ReservationSubmissionResponse;
050import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateRequest;
051import org.apache.hadoop.yarn.api.protocolrecords.ReservationUpdateResponse;
052import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
053import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
054import org.apache.hadoop.yarn.api.records.ApplicationId;
055import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
056import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
057import org.apache.hadoop.yarn.api.records.NodeReport;
058import org.apache.hadoop.yarn.api.records.ReservationId;
059import org.apache.hadoop.yarn.api.records.Resource;
060import org.apache.hadoop.yarn.api.records.ResourceRequest;
061import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
062import org.apache.hadoop.yarn.exceptions.ApplicationNotFoundException;
063import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException;
064import org.apache.hadoop.yarn.exceptions.YarnException;
065
066/**
067 * <p>The protocol between clients and the <code>ResourceManager</code>
068 * to submit/abort jobs and to get information on applications, cluster metrics,
069 * nodes, queues and ACLs.</p> 
070 */
071@Public
072@Stable
073public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
074  /**
075   * <p>The interface used by clients to obtain a new {@link ApplicationId} for 
076   * submitting new applications.</p>
077   * 
078   * <p>The <code>ResourceManager</code> responds with a new, monotonically
079   * increasing, {@link ApplicationId} which is used by the client to submit
080   * a new application.</p>
081   *
082   * <p>The <code>ResourceManager</code> also responds with details such 
083   * as maximum resource capabilities in the cluster as specified in
084   * {@link GetNewApplicationResponse}.</p>
085   *
086   * @param request request to get a new <code>ApplicationId</code>
087   * @return response containing the new <code>ApplicationId</code> to be used
088   * to submit an application
089   * @throws YarnException
090   * @throws IOException
091   * @see #submitApplication(SubmitApplicationRequest)
092   */
093  @Public
094  @Stable
095  @Idempotent
096  public GetNewApplicationResponse getNewApplication(
097      GetNewApplicationRequest request)
098  throws YarnException, IOException;
099  
100  /**
101   * <p>The interface used by clients to submit a new application to the
102   * <code>ResourceManager.</code></p>
103   * 
104   * <p>The client is required to provide details such as queue, 
105   * {@link Resource} required to run the <code>ApplicationMaster</code>, 
106   * the equivalent of {@link ContainerLaunchContext} for launching
107   * the <code>ApplicationMaster</code> etc. via the 
108   * {@link SubmitApplicationRequest}.</p>
109   * 
110   * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 
111   * {@link SubmitApplicationResponse} on accepting the submission and throws 
112   * an exception if it rejects the submission. However, this call needs to be
113   * followed by {@link #getApplicationReport(GetApplicationReportRequest)}
114   * to make sure that the application gets properly submitted - obtaining a
115   * {@link SubmitApplicationResponse} from ResourceManager doesn't guarantee
116   * that RM 'remembers' this application beyond failover or restart. If RM
117   * failover or RM restart happens before ResourceManager saves the
118   * application's state successfully, the subsequent
119   * {@link #getApplicationReport(GetApplicationReportRequest)} will throw
120   * a {@link ApplicationNotFoundException}. The Clients need to re-submit
121   * the application with the same {@link ApplicationSubmissionContext} when
122   * it encounters the {@link ApplicationNotFoundException} on the
123   * {@link #getApplicationReport(GetApplicationReportRequest)} call.</p>
124   * 
125   * <p>During the submission process, it checks whether the application
126   * already exists. If the application exists, it will simply return
127   * SubmitApplicationResponse</p>
128   *
129   * <p> In secure mode,the <code>ResourceManager</code> verifies access to
130   * queues etc. before accepting the application submission.</p>
131   * 
132   * @param request request to submit a new application
133   * @return (empty) response on accepting the submission
134   * @throws YarnException
135   * @throws IOException
136   * @throws InvalidResourceRequestException
137   *           The exception is thrown when a {@link ResourceRequest} is out of
138   *           the range of the configured lower and upper resource boundaries.
139   * @see #getNewApplication(GetNewApplicationRequest)
140   */
141  @Public
142  @Stable
143  @Idempotent
144  public SubmitApplicationResponse submitApplication(
145      SubmitApplicationRequest request) 
146  throws YarnException, IOException;
147  
148  /**
149   * <p>The interface used by clients to request the 
150   * <code>ResourceManager</code> to abort submitted application.</p>
151   * 
152   * <p>The client, via {@link KillApplicationRequest} provides the
153   * {@link ApplicationId} of the application to be aborted.</p>
154   * 
155   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
156   * application, queue etc. before terminating the application.</p> 
157   * 
158   * <p>Currently, the <code>ResourceManager</code> returns an empty response
159   * on success and throws an exception on rejecting the request.</p>
160   * 
161   * @param request request to abort a submitted application
162   * @return <code>ResourceManager</code> returns an empty response
163   *         on success and throws an exception on rejecting the request
164   * @throws YarnException
165   * @throws IOException
166   * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 
167   */
168  @Public
169  @Stable
170  @Idempotent
171  public KillApplicationResponse forceKillApplication(
172      KillApplicationRequest request) 
173  throws YarnException, IOException;
174
175  /**
176   * <p>The interface used by clients to get metrics about the cluster from
177   * the <code>ResourceManager</code>.</p>
178   * 
179   * <p>The <code>ResourceManager</code> responds with a
180   * {@link GetClusterMetricsResponse} which includes the 
181   * {@link YarnClusterMetrics} with details such as number of current
182   * nodes in the cluster.</p>
183   * 
184   * @param request request for cluster metrics
185   * @return cluster metrics
186   * @throws YarnException
187   * @throws IOException
188   */
189  @Public
190  @Stable
191  @Idempotent
192  public GetClusterMetricsResponse getClusterMetrics(
193      GetClusterMetricsRequest request) 
194  throws YarnException, IOException;
195
196  /**
197   * <p>The interface used by clients to get a report of all nodes
198   * in the cluster from the <code>ResourceManager</code>.</p>
199   * 
200   * <p>The <code>ResourceManager</code> responds with a 
201   * {@link GetClusterNodesResponse} which includes the 
202   * {@link NodeReport} for all the nodes in the cluster.</p>
203   * 
204   * @param request request for report on all nodes
205   * @return report on all nodes
206   * @throws YarnException
207   * @throws IOException
208   */
209  @Public
210  @Stable
211  @Idempotent
212  public GetClusterNodesResponse getClusterNodes(
213      GetClusterNodesRequest request) 
214  throws YarnException, IOException;
215  
216  /**
217   * <p>The interface used by clients to get information about <em>queues</em>
218   * from the <code>ResourceManager</code>.</p>
219   * 
220   * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
221   * as used/total resources, child queues, running applications etc.</p>
222   *
223   * <p> In secure mode,the <code>ResourceManager</code> verifies access before
224   * providing the information.</p> 
225   * 
226   * @param request request to get queue information
227   * @return queue information
228   * @throws YarnException
229   * @throws IOException
230   */
231  @Public
232  @Stable
233  @Idempotent
234  public GetQueueInfoResponse getQueueInfo(
235      GetQueueInfoRequest request) 
236  throws YarnException, IOException;
237  
238  /**
239   * <p>The interface used by clients to get information about <em>queue 
240   * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
241   * </p>
242   * 
243   * <p>The <code>ResourceManager</code> responds with queue acls for all
244   * existing queues.</p>
245   * 
246   * @param request request to get queue acls for <em>current user</em>
247   * @return queue acls for <em>current user</em>
248   * @throws YarnException
249   * @throws IOException
250   */
251  @Public
252  @Stable
253 @Idempotent
254  public GetQueueUserAclsInfoResponse getQueueUserAcls(
255      GetQueueUserAclsInfoRequest request) 
256  throws YarnException, IOException;
257
258  /**
259   * Move an application to a new queue.
260   * 
261   * @param request the application ID and the target queue
262   * @return an empty response
263   * @throws YarnException
264   * @throws IOException
265   */
266  @Public
267  @Unstable
268  @Idempotent
269  public MoveApplicationAcrossQueuesResponse moveApplicationAcrossQueues(
270      MoveApplicationAcrossQueuesRequest request) throws YarnException, IOException;
271
272  /**
273   * <p>
274   * The interface used by clients to submit a new reservation to the
275   * {@code ResourceManager}.
276   * </p>
277   * 
278   * <p>
279   * The client packages all details of its request in a
280   * {@link ReservationSubmissionRequest} object. This contains information
281   * about the amount of capacity, temporal constraints, and concurrency needs.
282   * Furthermore, the reservation might be composed of multiple stages, with
283   * ordering dependencies among them.
284   * </p>
285   * 
286   * <p>
287   * In order to respond, a new admission control component in the
288   * {@code ResourceManager} performs an analysis of the resources that have
289   * been committed over the period of time the user is requesting, verify that
290   * the user requests can be fulfilled, and that it respect a sharing policy
291   * (e.g., {@code CapacityOverTimePolicy}). Once it has positively determined
292   * that the ReservationSubmissionRequest is satisfiable the
293   * {@code ResourceManager} answers with a
294   * {@link ReservationSubmissionResponse} that include a non-null
295   * {@link ReservationId}. Upon failure to find a valid allocation the response
296   * is an exception with the reason.
297   * 
298   * On application submission the client can use this {@link ReservationId} to
299   * obtain access to the reserved resources.
300   * </p>
301   * 
302   * <p>
303   * The system guarantees that during the time-range specified by the user, the
304   * reservationID will be corresponding to a valid reservation. The amount of
305   * capacity dedicated to such queue can vary overtime, depending of the
306   * allocation that has been determined. But it is guaranteed to satisfy all
307   * the constraint expressed by the user in the
308   * {@link ReservationSubmissionRequest}.
309   * </p>
310   * 
311   * @param request the request to submit a new Reservation
312   * @return response the {@link ReservationId} on accepting the submission
313   * @throws YarnException if the request is invalid or reservation cannot be
314   *           created successfully
315   * @throws IOException
316   * 
317   */
318  @Public
319  @Unstable
320  public ReservationSubmissionResponse submitReservation(
321      ReservationSubmissionRequest request) throws YarnException, IOException;
322
323  /**
324   * <p>
325   * The interface used by clients to update an existing Reservation. This is
326   * referred to as a re-negotiation process, in which a user that has
327   * previously submitted a Reservation.
328   * </p>
329   * 
330   * <p>
331   * The allocation is attempted by virtually substituting all previous
332   * allocations related to this Reservation with new ones, that satisfy the new
333   * {@link ReservationUpdateRequest}. Upon success the previous allocation is
334   * substituted by the new one, and on failure (i.e., if the system cannot find
335   * a valid allocation for the updated request), the previous allocation
336   * remains valid.
337   * 
338   * The {@link ReservationId} is not changed, and applications currently
339   * running within this reservation will automatically receive the resources
340   * based on the new allocation.
341   * </p>
342   * 
343   * @param request to update an existing Reservation (the ReservationRequest
344   *          should refer to an existing valid {@link ReservationId})
345   * @return response empty on successfully updating the existing reservation
346   * @throws YarnException if the request is invalid or reservation cannot be
347   *           updated successfully
348   * @throws IOException
349   * 
350   */
351  @Public
352  @Unstable
353  public ReservationUpdateResponse updateReservation(
354      ReservationUpdateRequest request) throws YarnException, IOException;
355
356  /**
357   * <p>
358   * The interface used by clients to remove an existing Reservation.
359   * 
360   * Upon deletion of a reservation applications running with this reservation,
361   * are automatically downgraded to normal jobs running without any dedicated
362   * reservation.
363   * </p>
364   * 
365   * @param request to remove an existing Reservation (the ReservationRequest
366   *          should refer to an existing valid {@link ReservationId})
367   * @return response empty on successfully deleting the existing reservation
368   * @throws YarnException if the request is invalid or reservation cannot be
369   *           deleted successfully
370   * @throws IOException
371   * 
372   */
373  @Public
374  @Unstable
375  public ReservationDeleteResponse deleteReservation(
376      ReservationDeleteRequest request) throws YarnException, IOException;
377
378  /**
379   * <p>
380   * The interface used by client to get node to labels mappings in existing cluster
381   * </p>
382   *
383   * @param request
384   * @return node to labels mappings
385   * @throws YarnException
386   * @throws IOException
387   */
388  @Public
389  @Unstable
390  public GetNodesToLabelsResponse getNodeToLabels(
391      GetNodesToLabelsRequest request) throws YarnException, IOException;
392
393  /**
394   * <p>
395   * The interface used by client to get node labels in the cluster
396   * </p>
397   *
398   * @param request to get node labels collection of this cluster
399   * @return node labels collection of this cluster
400   * @throws YarnException
401   * @throws IOException
402   */
403  @Public
404  @Unstable
405  public GetClusterNodeLabelsResponse getClusterNodeLabels(
406      GetClusterNodeLabelsRequest request) throws YarnException, IOException;
407}