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.ContainerStatus;
032    import org.apache.hadoop.yarn.api.records.NMToken;
033    import org.apache.hadoop.yarn.api.records.NodeReport;
034    import org.apache.hadoop.yarn.api.records.PreemptionMessage;
035    import org.apache.hadoop.yarn.api.records.Resource;
036    import org.apache.hadoop.yarn.util.Records;
037    
038    /**
039     * <p>The response sent by the <code>ResourceManager</code> the  
040     * <code>ApplicationMaster</code> during resource negotiation.</p>
041     *
042     * <p>The response, includes:
043     *   <ul>
044     *     <li>Response ID to track duplicate responses.</li>
045     *     <li>
046     *       An AMCommand sent by ResourceManager to let the <code>ApplicationMaster</code>
047     *       take some actions (resync, shutdown etc.).
048     *     <li>A list of newly allocated {@link Container}.</li>
049     *     <li>A list of completed {@link Container}s' statuses.</li>
050     *     <li>
051     *       The available headroom for resources in the cluster for the
052     *       application. 
053     *     </li>
054     *     <li>A list of nodes whose status has been updated.</li>
055     *     <li>The number of available nodes in a cluster.</li>
056     *     <li>A description of resources requested back by the cluster</li>
057     *   </ul>
058     * </p>
059     * 
060     * @see ApplicationMasterProtocol#allocate(AllocateRequest)
061     */
062    @Public
063    @Stable
064    public abstract class AllocateResponse {
065    
066      @Public
067      @Stable
068      public static AllocateResponse newInstance(int responseId,
069          List<ContainerStatus> completedContainers,
070          List<Container> allocatedContainers, List<NodeReport> updatedNodes,
071          Resource availResources, AMCommand command, int numClusterNodes,
072          PreemptionMessage preempt, List<NMToken> nmTokens) {
073        AllocateResponse response = Records.newRecord(AllocateResponse.class);
074        response.setNumClusterNodes(numClusterNodes);
075        response.setResponseId(responseId);
076        response.setCompletedContainersStatuses(completedContainers);
077        response.setAllocatedContainers(allocatedContainers);
078        response.setUpdatedNodes(updatedNodes);
079        response.setAvailableResources(availResources);
080        response.setAMCommand(command);
081        response.setPreemptionMessage(preempt);
082        response.setNMTokens(nmTokens);
083        return response;
084      }
085    
086      /**
087       * If the <code>ResourceManager</code> needs the
088       * <code>ApplicationMaster</code> to take some action then it will send an
089       * AMCommand to the <code>ApplicationMaster</code>. See <code>AMCommand</code> 
090       * for details on commands and actions for them.
091       * @return <code>AMCommand</code> if the <code>ApplicationMaster</code> should
092       *         take action, <code>null</code> otherwise
093       * @see AMCommand
094       */
095      @Public
096      @Stable
097      public abstract AMCommand getAMCommand();
098    
099      @Private
100      @Unstable
101      public abstract void setAMCommand(AMCommand command);
102    
103      /**
104       * Get the <em>last response id</em>.
105       * @return <em>last response id</em>
106       */
107      @Public
108      @Stable
109      public abstract int getResponseId();
110    
111      @Private
112      @Unstable
113      public abstract void setResponseId(int responseId);
114    
115      /**
116       * Get the list of <em>newly allocated</em> <code>Container</code> by the
117       * <code>ResourceManager</code>.
118       * @return list of <em>newly allocated</em> <code>Container</code>
119       */
120      @Public
121      @Stable
122      public abstract List<Container> getAllocatedContainers();
123    
124      /**
125       * Set the list of <em>newly allocated</em> <code>Container</code> by the
126       * <code>ResourceManager</code>.
127       * @param containers list of <em>newly allocated</em> <code>Container</code>
128       */
129      @Private
130      @Unstable
131      public abstract void setAllocatedContainers(List<Container> containers);
132    
133      /**
134       * Get the <em>available headroom</em> for resources in the cluster for the
135       * application.
136       * @return limit of available headroom for resources in the cluster for the
137       * application
138       */
139      @Public
140      @Stable
141      public abstract Resource getAvailableResources();
142    
143      @Private
144      @Unstable
145      public abstract void setAvailableResources(Resource limit);
146    
147      /**
148       * Get the list of <em>completed containers' statuses</em>.
149       * @return the list of <em>completed containers' statuses</em>
150       */
151      @Public
152      @Stable
153      public abstract List<ContainerStatus> getCompletedContainersStatuses();
154    
155      @Private
156      @Unstable
157      public abstract void setCompletedContainersStatuses(List<ContainerStatus> containers);
158    
159      /**
160       * Get the list of <em>updated <code>NodeReport</code>s</em>. Updates could
161       * be changes in health, availability etc of the nodes.
162       * @return The delta of updated nodes since the last response
163       */
164      @Public
165      @Stable
166      public abstract  List<NodeReport> getUpdatedNodes();
167    
168      @Private
169      @Unstable
170      public abstract void setUpdatedNodes(final List<NodeReport> updatedNodes);
171    
172      /**
173       * Get the number of hosts available on the cluster.
174       * @return the available host count.
175       */
176      @Public
177      @Stable
178      public abstract int getNumClusterNodes();
179      
180      @Private
181      @Unstable
182      public abstract void setNumClusterNodes(int numNodes);
183    
184      /**
185       * <p>Get the description of containers owned by the AM, but requested back by
186       * the cluster. Note that the RM may have an inconsistent view of the
187       * resources owned by the AM. These messages are advisory, and the AM may
188       * elect to ignore them.<p>
189       *
190       * <p>The message is a snapshot of the resources the RM wants back from the AM.
191       * While demand persists, the RM will repeat its request; applications should
192       * not interpret each message as a request for <em>additional<em>
193       * resources on top of previous messages. Resources requested consistently
194       * over some duration may be forcibly killed by the RM.<p>
195       *
196       * @return A specification of the resources to reclaim from this AM.
197       */
198      @Public
199      @Evolving
200      public abstract PreemptionMessage getPreemptionMessage();
201    
202      @Private
203      @Unstable
204      public abstract void setPreemptionMessage(PreemptionMessage request);
205    
206      /**
207       * <p>Get the list of NMTokens required for communicating with NM. New NMTokens
208       * issued only if<p>
209       * <p>1) AM is receiving first container on underlying NodeManager.<br>
210       * OR<br>
211       * 2) NMToken master key rolled over in ResourceManager and AM is getting new
212       * container on the same underlying NodeManager.<p>
213       * <p>AM will receive one NMToken per NM irrespective of the number of containers
214       * issued on same NM. AM is expected to store these tokens until issued a
215       * new token for the same NM.<p>
216       */
217      @Public
218      @Stable
219      public abstract List<NMToken> getNMTokens();
220    
221      @Private
222      @Unstable
223      public abstract void setNMTokens(List<NMToken> nmTokens);
224    }