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.Collections;
022import java.util.List;
023
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.ApplicationMasterProtocol;
028import org.apache.hadoop.yarn.api.records.Container;
029import org.apache.hadoop.yarn.api.records.ContainerId;
030import org.apache.hadoop.yarn.api.records.ContainerResourceIncreaseRequest;
031import org.apache.hadoop.yarn.api.records.ResourceBlacklistRequest;
032import org.apache.hadoop.yarn.api.records.ResourceRequest;
033import org.apache.hadoop.yarn.api.records.UpdateContainerRequest;
034import org.apache.hadoop.yarn.util.Records;
035
036/**
037 * <p>The core request sent by the <code>ApplicationMaster</code> to the 
038 * <code>ResourceManager</code> to obtain resources in the cluster.</p> 
039 *
040 * <p>The request includes:
041 * <ul>
042 *   <li>A response id to track duplicate responses.</li>
043 *   <li>Progress information.</li>
044 *   <li>
045 *     A list of {@link ResourceRequest} to inform the
046 *     <code>ResourceManager</code> about the application's
047 *     resource requirements.
048 *   </li>
049 *   <li>
050 *     A list of unused {@link Container} which are being returned.
051 *   </li>
052 *   <li>
053 *     A list of {@link UpdateContainerRequest} to inform
054 *     the <code>ResourceManager</code> about the change in
055 *     requirements of running containers.
056 *   </li>
057 * </ul>
058 * 
059 * @see ApplicationMasterProtocol#allocate(AllocateRequest)
060 */
061@Public
062@Stable
063public abstract class AllocateRequest {
064
065  @Public
066  @Stable
067  public static AllocateRequest newInstance(int responseID, float appProgress,
068      List<ResourceRequest> resourceAsk,
069      List<ContainerId> containersToBeReleased,
070      ResourceBlacklistRequest resourceBlacklistRequest) {
071    return newInstance(responseID, appProgress, resourceAsk,
072        containersToBeReleased, null, resourceBlacklistRequest);
073  }
074
075  /**
076   * Use {@link AllocateRequest#newInstance(int, float, List, List,
077   * ResourceBlacklistRequest, List)} instead
078   * @param responseID responseId
079   * @param appProgress appProgress
080   * @param resourceAsk resourceAsk
081   * @param containersToBeReleased containersToBeReleased
082   * @param resourceBlacklistRequest resourceBlacklistRequest
083   * @param increaseRequests increaseRequests
084   * @return AllocateRequest
085   */
086  @Deprecated
087  public static AllocateRequest newInstance(int responseID, float appProgress,
088      List<ResourceRequest> resourceAsk,
089      List<ContainerId> containersToBeReleased,
090      ResourceBlacklistRequest resourceBlacklistRequest,
091      List<ContainerResourceIncreaseRequest> increaseRequests) {
092    AllocateRequest allocateRequest = Records.newRecord(AllocateRequest.class);
093    allocateRequest.setResponseId(responseID);
094    allocateRequest.setProgress(appProgress);
095    allocateRequest.setAskList(resourceAsk);
096    allocateRequest.setReleaseList(containersToBeReleased);
097    allocateRequest.setResourceBlacklistRequest(resourceBlacklistRequest);
098    allocateRequest.setIncreaseRequests(increaseRequests);
099    return allocateRequest;
100  }
101  
102  @Public
103  @Unstable
104  public static AllocateRequest newInstance(int responseID, float appProgress,
105      List<ResourceRequest> resourceAsk,
106      List<ContainerId> containersToBeReleased,
107      List<UpdateContainerRequest> updateRequests,
108      ResourceBlacklistRequest resourceBlacklistRequest) {
109    AllocateRequest allocateRequest = Records.newRecord(AllocateRequest.class);
110    allocateRequest.setResponseId(responseID);
111    allocateRequest.setProgress(appProgress);
112    allocateRequest.setAskList(resourceAsk);
113    allocateRequest.setReleaseList(containersToBeReleased);
114    allocateRequest.setResourceBlacklistRequest(resourceBlacklistRequest);
115    allocateRequest.setUpdateRequests(updateRequests);
116    return allocateRequest;
117  }
118  
119  /**
120   * Get the <em>response id</em> used to track duplicate responses.
121   * @return <em>response id</em>
122   */
123  @Public
124  @Stable
125  public abstract int getResponseId();
126
127  /**
128   * Set the <em>response id</em> used to track duplicate responses.
129   * @param id <em>response id</em>
130   */
131  @Public
132  @Stable
133  public abstract void setResponseId(int id);
134
135  /**
136   * Get the <em>current progress</em> of application. 
137   * @return <em>current progress</em> of application
138   */
139  @Public
140  @Stable
141  public abstract float getProgress();
142  
143  /**
144   * Set the <em>current progress</em> of application
145   * @param progress <em>current progress</em> of application
146   */
147  @Public
148  @Stable
149  public abstract void setProgress(float progress);
150
151  /**
152   * Get the list of <code>ResourceRequest</code> to update the 
153   * <code>ResourceManager</code> about the application's resource requirements.
154   * @return the list of <code>ResourceRequest</code>
155   * @see ResourceRequest
156   */
157  @Public
158  @Stable
159  public abstract List<ResourceRequest> getAskList();
160  
161  /**
162   * Set list of <code>ResourceRequest</code> to update the
163   * <code>ResourceManager</code> about the application's resource requirements.
164   * @param resourceRequests list of <code>ResourceRequest</code> to update the 
165   *                        <code>ResourceManager</code> about the application's 
166   *                        resource requirements
167   * @see ResourceRequest
168   */
169  @Public
170  @Stable
171  public abstract void setAskList(List<ResourceRequest> resourceRequests);
172
173  /**
174   * Get the list of <code>ContainerId</code> of containers being 
175   * released by the <code>ApplicationMaster</code>.
176   * @return list of <code>ContainerId</code> of containers being 
177   *         released by the <code>ApplicationMaster</code> 
178   */
179  @Public
180  @Stable
181  public abstract List<ContainerId> getReleaseList();
182
183  /**
184   * Set the list of <code>ContainerId</code> of containers being
185   * released by the <code>ApplicationMaster</code>
186   * @param releaseContainers list of <code>ContainerId</code> of 
187   *                          containers being released by the 
188   *                          <code>ApplicationMaster</code>
189   */
190  @Public
191  @Stable
192  public abstract void setReleaseList(List<ContainerId> releaseContainers);
193  
194  /**
195   * Get the <code>ResourceBlacklistRequest</code> being sent by the 
196   * <code>ApplicationMaster</code>.
197   * @return the <code>ResourceBlacklistRequest</code> being sent by the 
198   *         <code>ApplicationMaster</code>
199   * @see ResourceBlacklistRequest
200   */
201  @Public
202  @Stable
203  public abstract ResourceBlacklistRequest getResourceBlacklistRequest();
204  
205  /**
206   * Set the <code>ResourceBlacklistRequest</code> to inform the 
207   * <code>ResourceManager</code> about the blacklist additions and removals
208   * per the <code>ApplicationMaster</code>.
209   * 
210   * @param resourceBlacklistRequest the <code>ResourceBlacklistRequest</code>  
211   *                         to inform the <code>ResourceManager</code> about  
212   *                         the blacklist additions and removals
213   *                         per the <code>ApplicationMaster</code>
214   * @see ResourceBlacklistRequest
215   */
216  @Public
217  @Stable
218  public abstract void setResourceBlacklistRequest(
219      ResourceBlacklistRequest resourceBlacklistRequest);
220
221  /**
222   * Use {@link AllocateRequest#getUpdateRequests()} instead
223   * @return ContainerResourceIncreaseRequests
224   */
225  @Deprecated
226  public abstract List<ContainerResourceIncreaseRequest> getIncreaseRequests();
227
228  /**
229   * Use {@link AllocateRequest#setUpdateRequests(List)} instead
230   * @param increaseRequests increaseRequests
231   */
232  @Deprecated
233  public abstract void setIncreaseRequests(
234      List<ContainerResourceIncreaseRequest> increaseRequests);
235  
236  /**
237   * Get the list of container update requests being sent by the
238   * <code>ApplicationMaster</code>.
239   * @return list of {@link UpdateContainerRequest}
240   *         being sent by the
241   *         <code>ApplicationMaster</code>.
242   */
243  @Public
244  @Unstable
245  public abstract List<UpdateContainerRequest> getUpdateRequests();
246
247  /**
248   * Set the list of container update requests to inform the
249   * <code>ResourceManager</code> about the containers that need to be
250   * updated.
251   * @param updateRequests list of <code>UpdateContainerRequest</code> for
252   *                       containers to be updated
253   */
254  @Public
255  @Unstable
256  public abstract void setUpdateRequests(
257      List<UpdateContainerRequest> updateRequests);
258}