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.yarn.api.ApplicationMasterProtocol;
026import org.apache.hadoop.yarn.api.records.Container;
027import org.apache.hadoop.yarn.api.records.ContainerId;
028import org.apache.hadoop.yarn.api.records.ResourceBlacklistRequest;
029import org.apache.hadoop.yarn.api.records.ContainerResourceIncreaseRequest;
030import org.apache.hadoop.yarn.api.records.ResourceRequest;
031import org.apache.hadoop.yarn.util.Records;
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>A response id to track duplicate responses.</li>
040 *     <li>Progress information.</li>
041 *     <li>
042 *       A list of {@link ResourceRequest} to inform the 
043 *       <code>ResourceManager</code> about the application's 
044 *       resource requirements.
045 *     </li>
046 *     <li>
047 *       A list of unused {@link Container} which are being returned. 
048 *     </li>
049 *   </ul>
050 * </p>
051 * 
052 * @see ApplicationMasterProtocol#allocate(AllocateRequest)
053 */
054@Public
055@Stable
056public abstract class AllocateRequest {
057
058  @Public
059  @Stable
060  public static AllocateRequest newInstance(int responseID, float appProgress,
061      List<ResourceRequest> resourceAsk,
062      List<ContainerId> containersToBeReleased,
063      ResourceBlacklistRequest resourceBlacklistRequest) {
064    return newInstance(responseID, appProgress, resourceAsk,
065        containersToBeReleased, resourceBlacklistRequest, null);
066  }
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      List<ContainerResourceIncreaseRequest> increaseRequests) {
075    AllocateRequest allocateRequest = Records.newRecord(AllocateRequest.class);
076    allocateRequest.setResponseId(responseID);
077    allocateRequest.setProgress(appProgress);
078    allocateRequest.setAskList(resourceAsk);
079    allocateRequest.setReleaseList(containersToBeReleased);
080    allocateRequest.setResourceBlacklistRequest(resourceBlacklistRequest);
081    allocateRequest.setIncreaseRequests(increaseRequests);
082    return allocateRequest;
083  }
084  
085  /**
086   * Get the <em>response id</em> used to track duplicate responses.
087   * @return <em>response id</em>
088   */
089  @Public
090  @Stable
091  public abstract int getResponseId();
092
093  /**
094   * Set the <em>response id</em> used to track duplicate responses.
095   * @param id <em>response id</em>
096   */
097  @Public
098  @Stable
099  public abstract void setResponseId(int id);
100
101  /**
102   * Get the <em>current progress</em> of application. 
103   * @return <em>current progress</em> of application
104   */
105  @Public
106  @Stable
107  public abstract float getProgress();
108  
109  /**
110   * Set the <em>current progress</em> of application
111   * @param progress <em>current progress</em> of application
112   */
113  @Public
114  @Stable
115  public abstract void setProgress(float progress);
116
117  /**
118   * Get the list of <code>ResourceRequest</code> to update the 
119   * <code>ResourceManager</code> about the application's resource requirements.
120   * @return the list of <code>ResourceRequest</code>
121   * @see ResourceRequest
122   */
123  @Public
124  @Stable
125  public abstract List<ResourceRequest> getAskList();
126  
127  /**
128   * Set list of <code>ResourceRequest</code> to update the
129   * <code>ResourceManager</code> about the application's resource requirements.
130   * @param resourceRequests list of <code>ResourceRequest</code> to update the 
131   *                        <code>ResourceManager</code> about the application's 
132   *                        resource requirements
133   * @see ResourceRequest
134   */
135  @Public
136  @Stable
137  public abstract void setAskList(List<ResourceRequest> resourceRequests);
138
139  /**
140   * Get the list of <code>ContainerId</code> of containers being 
141   * released by the <code>ApplicationMaster</code>.
142   * @return list of <code>ContainerId</code> of containers being 
143   *         released by the <code>ApplicationMaster</code> 
144   */
145  @Public
146  @Stable
147  public abstract List<ContainerId> getReleaseList();
148
149  /**
150   * Set the list of <code>ContainerId</code> of containers being
151   * released by the <code>ApplicationMaster</code>
152   * @param releaseContainers list of <code>ContainerId</code> of 
153   *                          containers being released by the 
154   *                          <code>ApplicationMaster</code>
155   */
156  @Public
157  @Stable
158  public abstract void setReleaseList(List<ContainerId> releaseContainers);
159  
160  /**
161   * Get the <code>ResourceBlacklistRequest</code> being sent by the 
162   * <code>ApplicationMaster</code>.
163   * @return the <code>ResourceBlacklistRequest</code> being sent by the 
164   *         <code>ApplicationMaster</code>
165   * @see ResourceBlacklistRequest
166   */
167  @Public
168  @Stable
169  public abstract ResourceBlacklistRequest getResourceBlacklistRequest();
170  
171  /**
172   * Set the <code>ResourceBlacklistRequest</code> to inform the 
173   * <code>ResourceManager</code> about the blacklist additions and removals
174   * per the <code>ApplicationMaster</code>.
175   * 
176   * @param resourceBlacklistRequest the <code>ResourceBlacklistRequest</code>  
177   *                         to inform the <code>ResourceManager</code> about  
178   *                         the blacklist additions and removals
179   *                         per the <code>ApplicationMaster</code>
180   * @see ResourceBlacklistRequest
181   */
182  @Public
183  @Stable
184  public abstract void setResourceBlacklistRequest(
185      ResourceBlacklistRequest resourceBlacklistRequest);
186  
187  /**
188   * Get the <code>ContainerResourceIncreaseRequest</code> being sent by the
189   * <code>ApplicationMaster</code>
190   */
191  @Public
192  @Stable
193  public abstract List<ContainerResourceIncreaseRequest> getIncreaseRequests();
194  
195  /**
196   * Set the <code>ContainerResourceIncreaseRequest</code> to inform the
197   * <code>ResourceManager</code> about some container's resources need to be
198   * increased
199   */
200  @Public
201  @Stable
202  public abstract void setIncreaseRequests(
203      List<ContainerResourceIncreaseRequest> increaseRequests);
204}