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