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
019 package org.apache.hadoop.yarn.api.protocolrecords;
020
021 import java.util.List;
022
023 import org.apache.hadoop.classification.InterfaceAudience.Public;
024 import org.apache.hadoop.classification.InterfaceStability.Stable;
025 import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
026 import org.apache.hadoop.yarn.api.records.Container;
027 import org.apache.hadoop.yarn.api.records.ContainerId;
028 import org.apache.hadoop.yarn.api.records.ResourceBlacklistRequest;
029 import org.apache.hadoop.yarn.api.records.ContainerResourceIncreaseRequest;
030 import org.apache.hadoop.yarn.api.records.ResourceRequest;
031 import 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
056 public 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 }