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.protocolrecords;
020
021import java.util.ArrayList;
022import java.util.List;
023
024import org.apache.hadoop.classification.InterfaceAudience.Private;
025import org.apache.hadoop.classification.InterfaceAudience.Public;
026import org.apache.hadoop.classification.InterfaceStability.Evolving;
027import org.apache.hadoop.classification.InterfaceStability.Stable;
028import org.apache.hadoop.classification.InterfaceStability.Unstable;
029import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
030import org.apache.hadoop.yarn.api.records.AMCommand;
031import org.apache.hadoop.yarn.api.records.Container;
032import org.apache.hadoop.yarn.api.records.ContainerResourceDecrease;
033import org.apache.hadoop.yarn.api.records.ContainerResourceIncrease;
034import org.apache.hadoop.yarn.api.records.ContainerStatus;
035import org.apache.hadoop.yarn.api.records.NMToken;
036import org.apache.hadoop.yarn.api.records.NodeReport;
037import org.apache.hadoop.yarn.api.records.PreemptionMessage;
038import org.apache.hadoop.yarn.api.records.Priority;
039import org.apache.hadoop.yarn.api.records.Resource;
040import org.apache.hadoop.yarn.api.records.Token;
041import org.apache.hadoop.yarn.api.records.UpdateContainerError;
042import org.apache.hadoop.yarn.api.records.UpdatedContainer;
043import org.apache.hadoop.yarn.util.Records;
044
045/**
046 * The response sent by the <code>ResourceManager</code> the
047 * <code>ApplicationMaster</code> during resource negotiation.
048 * <p>
049 * The response, includes:
050 * <ul>
051 *   <li>Response ID to track duplicate responses.</li>
052 *   <li>
053 *     An AMCommand sent by ResourceManager to let the
054 *     {@code ApplicationMaster} take some actions (resync, shutdown etc.).
055 *   </li>
056 *   <li>A list of newly allocated {@link Container}.</li>
057 *   <li>A list of completed {@link Container}s' statuses.</li>
058 *   <li>
059 *     The available headroom for resources in the cluster for the
060 *     application.
061 *   </li>
062 *   <li>A list of nodes whose status has been updated.</li>
063 *   <li>The number of available nodes in a cluster.</li>
064 *   <li>A description of resources requested back by the cluster</li>
065 *   <li>AMRMToken, if AMRMToken has been rolled over</li>
066 *   <li>
067 *     A list of {@link Container} representing the containers
068 *     whose resource has been increased.
069 *   </li>
070 *   <li>
071 *     A list of {@link Container} representing the containers
072 *     whose resource has been decreased.
073 *   </li>
074 * </ul>
075 * 
076 * @see ApplicationMasterProtocol#allocate(AllocateRequest)
077 */
078@Public
079@Stable
080public abstract class AllocateResponse {
081
082  @Public
083  @Stable
084  public static AllocateResponse newInstance(int responseId,
085      List<ContainerStatus> completedContainers,
086      List<Container> allocatedContainers, List<NodeReport> updatedNodes,
087      Resource availResources, AMCommand command, int numClusterNodes,
088      PreemptionMessage preempt, List<NMToken> nmTokens) {
089    AllocateResponse response = Records.newRecord(AllocateResponse.class);
090    response.setNumClusterNodes(numClusterNodes);
091    response.setResponseId(responseId);
092    response.setCompletedContainersStatuses(completedContainers);
093    response.setAllocatedContainers(allocatedContainers);
094    response.setUpdatedNodes(updatedNodes);
095    response.setAvailableResources(availResources);
096    response.setAMCommand(command);
097    response.setPreemptionMessage(preempt);
098    response.setNMTokens(nmTokens);
099    return response;
100  }
101
102  /**
103   * Use {@link AllocateResponse#newInstance(int, List, List, List, Resource,
104   * AMCommand, int, PreemptionMessage, List, Token, List)} instead
105   * @param responseId responseId
106   * @param completedContainers completedContainers
107   * @param allocatedContainers allocatedContainers
108   * @param updatedNodes updatedNodes
109   * @param availResources availResources
110   * @param command command
111   * @param numClusterNodes numClusterNodes
112   * @param preempt preempt
113   * @param nmTokens nmTokens
114   * @param increasedContainers increasedContainers
115   * @param decreasedContainers decreasedContainers
116   * @return AllocateResponse
117   */
118  @Deprecated
119  public static AllocateResponse newInstance(int responseId,
120      List<ContainerStatus> completedContainers,
121      List<Container> allocatedContainers, List<NodeReport> updatedNodes,
122      Resource availResources, AMCommand command, int numClusterNodes,
123      PreemptionMessage preempt, List<NMToken> nmTokens,
124      List<ContainerResourceIncrease> increasedContainers,
125      List<ContainerResourceDecrease> decreasedContainers) {
126    return newInstance(responseId, completedContainers, allocatedContainers,
127        updatedNodes, availResources, command, numClusterNodes, preempt,
128        nmTokens);
129  }
130
131  @Public
132  @Unstable
133  public static AllocateResponse newInstance(int responseId,
134      List<ContainerStatus> completedContainers,
135      List<Container> allocatedContainers, List<NodeReport> updatedNodes,
136      Resource availResources, AMCommand command, int numClusterNodes,
137      PreemptionMessage preempt, List<NMToken> nmTokens,
138      List<UpdatedContainer> updatedContainers) {
139    AllocateResponse response = newInstance(responseId, completedContainers,
140        allocatedContainers, updatedNodes, availResources, command,
141        numClusterNodes, preempt, nmTokens);
142    response.setUpdatedContainers(updatedContainers);
143    return response;
144  }
145
146  @Private
147  @Unstable
148  public static AllocateResponse newInstance(int responseId,
149      List<ContainerStatus> completedContainers,
150      List<Container> allocatedContainers, List<NodeReport> updatedNodes,
151      Resource availResources, AMCommand command, int numClusterNodes,
152      PreemptionMessage preempt, List<NMToken> nmTokens, Token amRMToken,
153      List<UpdatedContainer> updatedContainers) {
154    AllocateResponse response =
155        newInstance(responseId, completedContainers, allocatedContainers,
156          updatedNodes, availResources, command, numClusterNodes, preempt,
157          nmTokens, updatedContainers);
158    response.setAMRMToken(amRMToken);
159    return response;
160  }
161
162  /**
163   * If the <code>ResourceManager</code> needs the
164   * <code>ApplicationMaster</code> to take some action then it will send an
165   * AMCommand to the <code>ApplicationMaster</code>. See <code>AMCommand</code> 
166   * for details on commands and actions for them.
167   * @return <code>AMCommand</code> if the <code>ApplicationMaster</code> should
168   *         take action, <code>null</code> otherwise
169   * @see AMCommand
170   */
171  @Public
172  @Stable
173  public abstract AMCommand getAMCommand();
174
175  @Private
176  @Unstable
177  public abstract void setAMCommand(AMCommand command);
178
179  /**
180   * Get the <em>last response id</em>.
181   * @return <em>last response id</em>
182   */
183  @Public
184  @Stable
185  public abstract int getResponseId();
186
187  @Private
188  @Unstable
189  public abstract void setResponseId(int responseId);
190
191  /**
192   * Get the list of <em>newly allocated</em> <code>Container</code> by the
193   * <code>ResourceManager</code>.
194   * @return list of <em>newly allocated</em> <code>Container</code>
195   */
196  @Public
197  @Stable
198  public abstract List<Container> getAllocatedContainers();
199
200  /**
201   * Set the list of <em>newly allocated</em> <code>Container</code> by the
202   * <code>ResourceManager</code>.
203   * @param containers list of <em>newly allocated</em> <code>Container</code>
204   */
205  @Private
206  @Unstable
207  public abstract void setAllocatedContainers(List<Container> containers);
208
209  /**
210   * Get the <em>available headroom</em> for resources in the cluster for the
211   * application.
212   * @return limit of available headroom for resources in the cluster for the
213   * application
214   */
215  @Public
216  @Stable
217  public abstract Resource getAvailableResources();
218
219  @Private
220  @Unstable
221  public abstract void setAvailableResources(Resource limit);
222
223  /**
224   * Get the list of <em>completed containers' statuses</em>.
225   * @return the list of <em>completed containers' statuses</em>
226   */
227  @Public
228  @Stable
229  public abstract List<ContainerStatus> getCompletedContainersStatuses();
230
231  @Private
232  @Unstable
233  public abstract void setCompletedContainersStatuses(List<ContainerStatus> containers);
234
235  /**
236   * Get the list of <em>updated <code>NodeReport</code>s</em>. Updates could
237   * be changes in health, availability etc of the nodes.
238   * @return The delta of updated nodes since the last response
239   */
240  @Public
241  @Stable
242  public abstract  List<NodeReport> getUpdatedNodes();
243
244  @Private
245  @Unstable
246  public abstract void setUpdatedNodes(final List<NodeReport> updatedNodes);
247
248  /**
249   * Get the number of hosts available on the cluster.
250   * @return the available host count.
251   */
252  @Public
253  @Stable
254  public abstract int getNumClusterNodes();
255  
256  @Private
257  @Unstable
258  public abstract void setNumClusterNodes(int numNodes);
259
260  /**
261   * Get the description of containers owned by the AM, but requested back by
262   * the cluster. Note that the RM may have an inconsistent view of the
263   * resources owned by the AM. These messages are advisory, and the AM may
264   * elect to ignore them.
265   * <p>
266   * The message is a snapshot of the resources the RM wants back from the AM.
267   * While demand persists, the RM will repeat its request; applications should
268   * not interpret each message as a request for <em>additional</em>
269   * resources on top of previous messages. Resources requested consistently
270   * over some duration may be forcibly killed by the RM.
271   *
272   * @return A specification of the resources to reclaim from this AM.
273   */
274  @Public
275  @Evolving
276  public abstract PreemptionMessage getPreemptionMessage();
277
278  @Private
279  @Unstable
280  public abstract void setPreemptionMessage(PreemptionMessage request);
281
282  /**
283   * Get the list of NMTokens required for communicating with NM. New NMTokens
284   * issued only if
285   * <p>
286   * 1) AM is receiving first container on underlying NodeManager.<br>
287   * OR<br>
288   * 2) NMToken master key rolled over in ResourceManager and AM is getting new
289   * container on the same underlying NodeManager.
290   * <p>
291   * AM will receive one NMToken per NM irrespective of the number of containers
292   * issued on same NM. AM is expected to store these tokens until issued a
293   * new token for the same NM.
294   */
295  @Public
296  @Stable
297  public abstract List<NMToken> getNMTokens();
298
299  @Private
300  @Unstable
301  public abstract void setNMTokens(List<NMToken> nmTokens);
302  
303  /**
304   * Get the list of newly updated containers by
305   * <code>ResourceManager</code>.
306   */
307  @Public
308  @Unstable
309  public abstract List<UpdatedContainer> getUpdatedContainers();
310
311  /**
312   * Set the list of newly updated containers by
313   * <code>ResourceManager</code>.
314   *
315   * @param updatedContainers List of Updated Containers.
316   */
317  @Private
318  @Unstable
319  public abstract void setUpdatedContainers(
320      List<UpdatedContainer> updatedContainers);
321
322  /**
323   * The AMRMToken that belong to this attempt
324   *
325   * @return The AMRMToken that belong to this attempt
326   */
327  @Public
328  @Unstable
329  public abstract Token getAMRMToken();
330
331  @Private
332  @Unstable
333  public abstract void setAMRMToken(Token amRMToken);
334
335  /**
336   * Priority of the application
337   *
338   * @return get application priority
339   */
340  @Public
341  @Unstable
342  public abstract Priority getApplicationPriority();
343
344  @Private
345  @Unstable
346  public abstract void setApplicationPriority(Priority priority);
347
348  /**
349   * Get the list of container update errors to inform the
350   * Application Master about the container updates that could not be
351   * satisfied due to error.
352   *
353   * @return List of Update Container Errors.
354   */
355  @Public
356  @Unstable
357  public List<UpdateContainerError> getUpdateErrors() {
358    return new ArrayList<>();
359  }
360
361  /**
362   * Set the list of container update errors to inform the
363   * Application Master about the container updates that could not be
364   * satisfied due to error.
365   * @param updateErrors list of <code>UpdateContainerError</code> for
366   *                       containers updates requests that were in error
367   */
368  @Public
369  @Unstable
370  public void setUpdateErrors(List<UpdateContainerError> updateErrors) {
371  }
372
373  /**
374   * Use {@link AllocateResponse#getUpdatedContainers()} instead
375   * @return null
376   */
377  @Deprecated
378  public abstract List<ContainerResourceIncrease> getIncreasedContainers();
379
380  /**
381   * Use {@link AllocateResponse#getUpdatedContainers()} instead
382   * @return null
383   */
384  @Deprecated
385  public abstract List<ContainerResourceDecrease> getDecreasedContainers();
386}