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 * <p>The response sent by the <code>ResourceManager</code> the  
043 * <code>ApplicationMaster</code> during resource negotiation.</p>
044 *
045 * <p>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 <code>ApplicationMaster</code>
050 *       take some actions (resync, shutdown etc.).
051 *     <li>A list of newly allocated {@link Container}.</li>
052 *     <li>A list of completed {@link Container}s' statuses.</li>
053 *     <li>
054 *       The available headroom for resources in the cluster for the
055 *       application. 
056 *     </li>
057 *     <li>A list of nodes whose status has been updated.</li>
058 *     <li>The number of available nodes in a cluster.</li>
059 *     <li>A description of resources requested back by the cluster</li>
060 *     <li>AMRMToken, if AMRMToken has been rolled over</li>
061 *   </ul>
062 * </p>
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   * <p>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.<p>
227   *
228   * <p>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.<p>
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   * <p>Get the list of NMTokens required for communicating with NM. New NMTokens
246   * issued only if<p>
247   * <p>1) AM is receiving first container on underlying NodeManager.<br>
248   * OR<br>
249   * 2) NMToken master key rolled over in ResourceManager and AM is getting new
250   * container on the same underlying NodeManager.<p>
251   * <p>AM will receive one NMToken per NM irrespective of the number of containers
252   * issued on same NM. AM is expected to store these tokens until issued a
253   * new token for the same NM.<p>
254   */
255  @Public
256  @Stable
257  public abstract List<NMToken> getNMTokens();
258
259  @Private
260  @Unstable
261  public abstract void setNMTokens(List<NMToken> nmTokens);
262  
263  /**
264   * Get the list of newly increased containers by <code>ResourceManager</code>
265   */
266  @Public
267  @Stable
268  public abstract List<ContainerResourceIncrease> getIncreasedContainers();
269
270  /**
271   * Set the list of newly increased containers by <code>ResourceManager</code>
272   */
273  @Private
274  @Unstable
275  public abstract void setIncreasedContainers(
276      List<ContainerResourceIncrease> increasedContainers);
277
278  /**
279   * Get the list of newly decreased containers by <code>NodeManager</code>
280   */
281  @Public
282  @Stable
283  public abstract List<ContainerResourceDecrease> getDecreasedContainers();
284
285  /**
286   * Set the list of newly decreased containers by <code>NodeManager</code>
287   */
288  @Private
289  @Unstable
290  public abstract void setDecreasedContainers(
291      List<ContainerResourceDecrease> decreasedContainers);
292
293  /**
294   * The AMRMToken that belong to this attempt
295   *
296   * @return The AMRMToken that belong to this attempt
297   */
298  @Public
299  @Unstable
300  public abstract Token getAMRMToken();
301
302  @Private
303  @Unstable
304  public abstract void setAMRMToken(Token amRMToken);
305}