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    
019    package org.apache.hadoop.yarn.api.protocolrecords;
020    
021    import java.util.List;
022    
023    import org.apache.hadoop.classification.InterfaceAudience.Private;
024    import org.apache.hadoop.classification.InterfaceAudience.Public;
025    import org.apache.hadoop.classification.InterfaceStability.Evolving;
026    import org.apache.hadoop.classification.InterfaceStability.Stable;
027    import org.apache.hadoop.classification.InterfaceStability.Unstable;
028    import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
029    import org.apache.hadoop.yarn.api.records.AMCommand;
030    import org.apache.hadoop.yarn.api.records.Container;
031    import org.apache.hadoop.yarn.api.records.ContainerResourceDecrease;
032    import org.apache.hadoop.yarn.api.records.ContainerResourceIncrease;
033    import org.apache.hadoop.yarn.api.records.ContainerStatus;
034    import org.apache.hadoop.yarn.api.records.NMToken;
035    import org.apache.hadoop.yarn.api.records.NodeReport;
036    import org.apache.hadoop.yarn.api.records.PreemptionMessage;
037    import org.apache.hadoop.yarn.api.records.Resource;
038    import org.apache.hadoop.yarn.api.records.Token;
039    import 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
068    public 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    }