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