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
019package org.apache.hadoop.yarn.api.protocolrecords;
020
021import java.util.List;
022
023import org.apache.hadoop.classification.InterfaceAudience.Private;
024import org.apache.hadoop.classification.InterfaceAudience.Public;
025import org.apache.hadoop.classification.InterfaceStability.Stable;
026import org.apache.hadoop.classification.InterfaceStability.Unstable;
027import org.apache.hadoop.yarn.api.AMRMProtocol;
028import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
029import org.apache.hadoop.yarn.api.records.Container;
030import org.apache.hadoop.yarn.api.records.ContainerId;
031import 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
060public 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 containers being 
156   * released by the <code>ApplicationMaster</code>.
157   * @return list of <code>ContainerId</code> of 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 containers being 
174   * released by the <code>ApplicationMaster</code>
175   * @param releaseContainers list of <code>ContainerId</code> of 
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}