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.AMRMProtocol;
029    import org.apache.hadoop.yarn.api.records.Container;
030    import org.apache.hadoop.yarn.api.records.ContainerStatus;
031    import org.apache.hadoop.yarn.api.records.NodeReport;
032    import org.apache.hadoop.yarn.api.records.Resource;
033    
034    /**
035     * <p>The response sent by the <code>ResourceManager</code> the  
036     * <code>ApplicationMaster</code> during resource negotiation.</p>
037     *
038     * <p>The response, includes:
039     *   <ul>
040     *     <li>Response ID to track duplicate responses.</li>
041     *     <li>
042     *       A reboot flag to let the <code>ApplicationMaster</code> know that its 
043     *       horribly out of sync and needs to reboot.</li>
044     *     <li>A list of newly allocated {@link Container}.</li>
045     *     <li>A list of completed {@link Container}.</li>
046     *     <li>
047     *       The available headroom for resources in the cluster for the
048     *       application. 
049     *     </li>
050     *     <li>A list of nodes whose status has been updated.</li>
051     *     <li>The number of available nodes in a cluster.</li>
052     *     <li>A description of resources requested back by the cluster</li>
053     *   </ul>
054     * </p>
055     * 
056     * @see AMRMProtocol#allocate(AllocateRequest)
057     */
058    @Public
059    @Stable
060    public interface AllocateResponse {
061      /**
062       * Should the <code>ApplicationMaster</code> reboot for being horribly
063       * out-of-sync with the <code>ResourceManager</code> as deigned by
064       * {@link #getResponseId()}?
065       *
066       * @return <code>true</code> if the <code>ApplicationMaster</code> should
067       *         reboot, <code>false</code> otherwise
068       */
069      @Public
070      @Stable
071      public boolean getReboot();
072    
073      @Private
074      @Unstable
075      public void setReboot(boolean reboot);
076    
077      /**
078       * Get the <em>last response id</em>.
079       * @return <em>last response id</em>
080       */
081      @Public
082      @Stable
083      public int getResponseId();
084    
085      @Private
086      @Unstable
087      public void setResponseId(int responseId);
088    
089      /**
090       * Get the list of <em>newly allocated</em> <code>Container</code> by the
091       * <code>ResourceManager</code>.
092       * @return list of <em>newly allocated</em> <code>Container</code>
093       */
094      @Public
095      @Stable
096      public List<Container> getAllocatedContainers();
097    
098      /**
099       * Set the list of <em>newly allocated</em> <code>Container</code> by the
100       * <code>ResourceManager</code>.
101       * @param containers list of <em>newly allocated</em> <code>Container</code>
102       */
103      @Public
104      @Stable
105      public void setAllocatedContainers(List<Container> containers);
106    
107      /**
108       * Get the <em>available headroom</em> for resources in the cluster for the
109       * application.
110       * @return limit of available headroom for resources in the cluster for the
111       * application
112       */
113      @Public
114      @Stable
115      public Resource getAvailableResources();
116    
117      @Private
118      @Unstable
119      public void setAvailableResources(Resource limit);
120    
121      /**
122       * Get the list of <em>completed containers' statuses</em>.
123       * @return the list of <em>completed containers' statuses</em>
124       */
125      @Public
126      @Stable
127      public List<ContainerStatus> getCompletedContainersStatuses();
128    
129      @Private
130      @Unstable
131      public void setCompletedContainersStatuses(List<ContainerStatus> containers);
132    
133      /**
134       * Get the list of <em>updated <code>NodeReport</code>s</em>. Updates could
135       * be changes in health, availability etc of the nodes.
136       * @return The delta of updated nodes since the last response
137       */
138      @Public
139      @Unstable
140      public List<NodeReport> getUpdatedNodes();
141    
142      @Private
143      @Unstable
144      public void setUpdatedNodes(final List<NodeReport> updatedNodes);
145    
146      /**
147       * Get the number of hosts available on the cluster.
148       * @return the available host count.
149       */
150      @Public
151      @Stable
152      public int getNumClusterNodes();
153      
154      @Private
155      @Unstable
156      public void setNumClusterNodes(int numNodes);
157    
158      /**
159       * Get the description of containers owned by the AM, but requested back by
160       * the cluster. Note that the RM may have an inconsistent view of the
161       * resources owned by the AM. These messages are advisory, and the AM may
162       * elect to ignore them.
163       *
164       * The message is a snapshot of the resources the RM wants back from the AM.
165       * While demand persists, the RM will repeat its request; applications should
166       * not interpret each message as a request for <emph>additional<emph>
167       * resources on top of previous messages. Resources requested consistently
168       * over some duration may be forcibly killed by the RM.
169       *
170       * @return A specification of the resources to reclaim from this AM.
171       */
172      @Public
173      @Evolving
174      public PreemptionMessage getPreemptionMessage();
175    
176      @Private
177      @Unstable
178      public void setPreemptionMessage(PreemptionMessage request);
179    
180    }