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     *     <li></li>
054     *   </ul>
055     * </p>
056     * 
057     * @see AMRMProtocol#allocate(AllocateRequest)
058     */
059    @Public
060    @Stable
061    public interface AllocateRequest {
062    
063      /**
064       * Get the <code>ApplicationAttemptId</code> being managed by the 
065       * <code>ApplicationMaster</code>.
066       * @return <code>ApplicationAttemptId</code> being managed by the 
067       *         <code>ApplicationMaster</code>
068       */
069      @Public
070      @Stable
071      ApplicationAttemptId getApplicationAttemptId();
072      
073      /**
074       * Set the <code>ApplicationAttemptId</code> being managed by the 
075       * <code>ApplicationMaster</code>.
076       * @param applicationAttemptId <code>ApplicationAttemptId</code> being managed 
077       *                             by the <code>ApplicationMaster</code>
078       */
079      @Public
080      @Stable
081      void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
082    
083      /**
084       * Get the <em>response id</em>.
085       * @return <em>response id</em>
086       */
087      @Public
088      @Stable
089      int getResponseId();
090    
091      /**
092       * Set the <em>response id</em>
093       * @param id <em>response id</em>
094       */
095      @Public
096      @Stable
097      void setResponseId(int id);
098    
099      /**
100       * Get the <em>current progress</em> of application. 
101       * @return <em>current progress</em> of application
102       */
103      @Public
104      @Stable
105      float getProgress();
106      
107      /**
108       * Set the <em>current progress</em> of application
109       * @param progress <em>current progress</em> of application
110       */
111      @Public
112      @Stable
113      void setProgress(float progress);
114    
115      /**
116       * Get the list of <code>ResourceRequest</code> to upate the 
117       * <code>ResourceManager</code> about the application's resource requirements.
118       * @return the list of <code>ResourceRequest</code>
119       */
120      @Public
121      @Stable
122      List<ResourceRequest> getAskList();
123      
124      @Private
125      @Unstable
126      ResourceRequest getAsk(int index);
127      
128      @Private
129      @Unstable
130      int getAskCount();
131      
132      /**
133       * Add list of <code>ResourceRequest</code> to upate the 
134       * <code>ResourceManager</code> about the application's resource requirements.
135       * @param resourceRequest list of <code>ResourceRequest</code> to upate the 
136       *                        <code>ResourceManager</code> about the application's 
137       *                        resource requirements
138       */
139      @Public
140      @Stable
141      void addAllAsks(List<ResourceRequest> resourceRequest);
142    
143      @Private
144      @Unstable
145      void addAsk(ResourceRequest request);
146    
147      @Private
148      @Unstable
149      void removeAsk(int index);
150    
151      @Private
152      @Unstable
153      void clearAsks();
154    
155      /**
156       * Get the list of <code>ContainerId</code> of unused containers being 
157       * released by the <code>ApplicationMaster</code>.
158       * @return list of <code>ContainerId</code> of unused containers being 
159       *         released by the <code>ApplicationMaster</code> 
160       */
161      @Public
162      @Stable
163      List<ContainerId> getReleaseList();
164      
165      @Private
166      @Unstable
167      ContainerId getRelease(int index);
168      
169      @Private
170      @Unstable
171      int getReleaseCount();
172    
173      /**
174       * Add the list of <code>ContainerId</code> of unused containers being 
175       * released by the <code>ApplicationMaster</code>
176       * @param releaseContainers list of <code>ContainerId</code> of unused 
177       *                          containers being released by the <
178       *                          code>ApplicationMaster</code>
179       */
180      @Public
181      @Stable
182      void addAllReleases(List<ContainerId> releaseContainers);
183      
184      @Private
185      @Unstable
186      void addRelease(ContainerId container);
187      
188      @Private
189      @Unstable
190      void removeRelease(int index);
191      
192      @Private
193      @Unstable
194      void clearReleases();
195    }