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