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}