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.Stable;
026    import org.apache.hadoop.classification.InterfaceStability.Unstable;
027    import org.apache.hadoop.yarn.api.AMRMProtocol;
028    import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
029    import org.apache.hadoop.yarn.api.records.Container;
030    import org.apache.hadoop.yarn.api.records.ContainerId;
031    import org.apache.hadoop.yarn.api.records.ResourceRequest;
032    
033    /**
034     * <p>The core request sent by the <code>ApplicationMaster</code> to the 
035     * <code>ResourceManager</code> to obtain resources in the cluster.</p> 
036     *
037     * <p>The request includes:
038     *   <ul>
039     *     <li>
040     *         {@link ApplicationAttemptId} being managed by the 
041     *         <code>ApplicationMaster</code>
042     *     </li>
043     *     <li>A response id to track duplicate responses.</li>
044     *     <li>Progress information.</li>
045     *     <li>
046     *       A list of {@link ResourceRequest} to inform the 
047     *       <code>ResourceManager</code> about the application's 
048     *       resource requirements.
049     *     </li>
050     *     <li>
051     *       A list of unused {@link Container} which are being returned. 
052     *     </li>
053     *   </ul>
054     * </p>
055     * 
056     * @see AMRMProtocol#allocate(AllocateRequest)
057     */
058    @Public
059    @Stable
060    public interface AllocateRequest {
061    
062      /**
063       * Get the <code>ApplicationAttemptId</code> being managed by the 
064       * <code>ApplicationMaster</code>.
065       * @return <code>ApplicationAttemptId</code> being managed by the 
066       *         <code>ApplicationMaster</code>
067       */
068      @Public
069      @Stable
070      ApplicationAttemptId getApplicationAttemptId();
071      
072      /**
073       * Set the <code>ApplicationAttemptId</code> being managed by the 
074       * <code>ApplicationMaster</code>.
075       * @param applicationAttemptId <code>ApplicationAttemptId</code> being managed 
076       *                             by the <code>ApplicationMaster</code>
077       */
078      @Public
079      @Stable
080      void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
081    
082      /**
083       * Get the <em>response id</em> used to track duplicate responses.
084       * @return <em>response id</em>
085       */
086      @Public
087      @Stable
088      int getResponseId();
089    
090      /**
091       * Set the <em>response id</em> used to track duplicate responses.
092       * @param id <em>response id</em>
093       */
094      @Public
095      @Stable
096      void setResponseId(int id);
097    
098      /**
099       * Get the <em>current progress</em> of application. 
100       * @return <em>current progress</em> of application
101       */
102      @Public
103      @Stable
104      float getProgress();
105      
106      /**
107       * Set the <em>current progress</em> of application
108       * @param progress <em>current progress</em> of application
109       */
110      @Public
111      @Stable
112      void setProgress(float progress);
113    
114      /**
115       * Get the list of <code>ResourceRequest</code> to update the 
116       * <code>ResourceManager</code> about the application's resource requirements.
117       * @return the list of <code>ResourceRequest</code>
118       */
119      @Public
120      @Stable
121      List<ResourceRequest> getAskList();
122      
123      @Private
124      @Unstable
125      ResourceRequest getAsk(int index);
126      
127      @Private
128      @Unstable
129      int getAskCount();
130      
131      /**
132       * Add list of <code>ResourceRequest</code> to update the 
133       * <code>ResourceManager</code> about the application's resource requirements.
134       * @param resourceRequest list of <code>ResourceRequest</code> to update the 
135       *                        <code>ResourceManager</code> about the application's 
136       *                        resource requirements
137       */
138      @Public
139      @Stable
140      void addAllAsks(List<ResourceRequest> resourceRequest);
141    
142      @Private
143      @Unstable
144      void addAsk(ResourceRequest request);
145    
146      @Private
147      @Unstable
148      void removeAsk(int index);
149    
150      @Private
151      @Unstable
152      void clearAsks();
153    
154      /**
155       * Get the list of <code>ContainerId</code> of unused containers being 
156       * released by the <code>ApplicationMaster</code>.
157       * @return list of <code>ContainerId</code> of unused containers being 
158       *         released by the <code>ApplicationMaster</code> 
159       */
160      @Public
161      @Stable
162      List<ContainerId> getReleaseList();
163      
164      @Private
165      @Unstable
166      ContainerId getRelease(int index);
167      
168      @Private
169      @Unstable
170      int getReleaseCount();
171    
172      /**
173       * Add the list of <code>ContainerId</code> of unused containers being 
174       * released by the <code>ApplicationMaster</code>
175       * @param releaseContainers list of <code>ContainerId</code> of unused 
176       *                          containers being released by the <
177       *                          code>ApplicationMaster</code>
178       */
179      @Public
180      @Stable
181      void addAllReleases(List<ContainerId> releaseContainers);
182      
183      @Private
184      @Unstable
185      void addRelease(ContainerId container);
186      
187      @Private
188      @Unstable
189      void removeRelease(int index);
190      
191      @Private
192      @Unstable
193      void clearReleases();
194    }