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