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.EnumSet;
022 import java.util.Set;
023
024 import org.apache.commons.lang.math.LongRange;
025 import org.apache.hadoop.classification.InterfaceAudience.Private;
026 import org.apache.hadoop.classification.InterfaceAudience.Public;
027 import org.apache.hadoop.classification.InterfaceStability.Stable;
028 import org.apache.hadoop.classification.InterfaceStability.Unstable;
029 import org.apache.hadoop.yarn.api.ApplicationClientProtocol;
030 import org.apache.hadoop.yarn.api.records.YarnApplicationState;
031 import org.apache.hadoop.yarn.util.Records;
032
033 /**
034 * <p>The request from clients to get a report of Applications
035 * in the cluster from the <code>ResourceManager</code>.</p>
036 *
037 *
038 * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
039 */
040 @Public
041 @Stable
042 public abstract class GetApplicationsRequest {
043 @Public
044 @Stable
045 public static GetApplicationsRequest newInstance() {
046 GetApplicationsRequest request =
047 Records.newRecord(GetApplicationsRequest.class);
048 return request;
049 }
050
051 /**
052 * <p>
053 * The request from clients to get a report of Applications matching the
054 * giving application types in the cluster from the
055 * <code>ResourceManager</code>.
056 * </p>
057 *
058 * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
059 *
060 * <p>Setting any of the parameters to null, would just disable that
061 * filter</p>
062 *
063 * @param scope {@link ApplicationsRequestScope} to filter by
064 * @param users list of users to filter by
065 * @param queues list of scheduler queues to filter by
066 * @param applicationTypes types of applications
067 * @param applicationTags application tags to filter by
068 * @param applicationStates application states to filter by
069 * @param startRange range of application start times to filter by
070 * @param finishRange range of application finish times to filter by
071 * @param limit number of applications to limit to
072 * @return {@link GetApplicationsRequest} to be used with
073 * {@link ApplicationClientProtocol#getApplications(GetApplicationsRequest)}
074 */
075 @Public
076 @Stable
077 public static GetApplicationsRequest newInstance(
078 ApplicationsRequestScope scope,
079 Set<String> users,
080 Set<String> queues,
081 Set<String> applicationTypes,
082 Set<String> applicationTags,
083 EnumSet<YarnApplicationState> applicationStates,
084 LongRange startRange,
085 LongRange finishRange,
086 Long limit) {
087 GetApplicationsRequest request =
088 Records.newRecord(GetApplicationsRequest.class);
089 if (scope != null) {
090 request.setScope(scope);
091 }
092 request.setUsers(users);
093 request.setQueues(queues);
094 request.setApplicationTypes(applicationTypes);
095 request.setApplicationTags(applicationTags);
096 request.setApplicationStates(applicationStates);
097 if (startRange != null) {
098 request.setStartRange(
099 startRange.getMinimumLong(), startRange.getMaximumLong());
100 }
101 if (finishRange != null) {
102 request.setFinishRange(
103 finishRange.getMinimumLong(), finishRange.getMaximumLong());
104 }
105 if (limit != null) {
106 request.setLimit(limit);
107 }
108 return request;
109 }
110
111 /**
112 * <p>
113 * The request from clients to get a report of Applications matching the
114 * giving application types in the cluster from the
115 * <code>ResourceManager</code>.
116 * </p>
117 *
118 * @param scope {@link ApplicationsRequestScope} to filter by
119 * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
120 */
121 @Public
122 @Stable
123 public static GetApplicationsRequest newInstance(
124 ApplicationsRequestScope scope) {
125 GetApplicationsRequest request =
126 Records.newRecord(GetApplicationsRequest.class);
127 request.setScope(scope);
128 return request;
129 }
130
131 /**
132 * <p>
133 * The request from clients to get a report of Applications matching the
134 * giving application types in the cluster from the
135 * <code>ResourceManager</code>.
136 * </p>
137 *
138 *
139 * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
140 */
141 @Public
142 @Stable
143 public static GetApplicationsRequest
144 newInstance(Set<String> applicationTypes) {
145 GetApplicationsRequest request =
146 Records.newRecord(GetApplicationsRequest.class);
147 request.setApplicationTypes(applicationTypes);
148 return request;
149 }
150
151 /**
152 * <p>
153 * The request from clients to get a report of Applications matching the
154 * giving application states in the cluster from the
155 * <code>ResourceManager</code>.
156 * </p>
157 *
158 *
159 * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
160 */
161 @Public
162 @Stable
163 public static GetApplicationsRequest newInstance(
164 EnumSet<YarnApplicationState> applicationStates) {
165 GetApplicationsRequest request =
166 Records.newRecord(GetApplicationsRequest.class);
167 request.setApplicationStates(applicationStates);
168 return request;
169 }
170
171 /**
172 * <p>
173 * The request from clients to get a report of Applications matching the
174 * giving and application types and application types in the cluster from the
175 * <code>ResourceManager</code>.
176 * </p>
177 *
178 *
179 * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
180 */
181 @Public
182 @Stable
183 public static GetApplicationsRequest newInstance(
184 Set<String> applicationTypes,
185 EnumSet<YarnApplicationState> applicationStates) {
186 GetApplicationsRequest request =
187 Records.newRecord(GetApplicationsRequest.class);
188 request.setApplicationTypes(applicationTypes);
189 request.setApplicationStates(applicationStates);
190 return request;
191 }
192
193 /**
194 * Get the application types to filter applications on
195 *
196 * @return Set of Application Types to filter on
197 */
198 @Public
199 @Stable
200 public abstract Set<String> getApplicationTypes();
201
202 /**
203 * Set the application types to filter applications on
204 *
205 * @param applicationTypes
206 * A Set of Application Types to filter on.
207 * If not defined, match all applications
208 */
209 @Private
210 @Unstable
211 public abstract void
212 setApplicationTypes(Set<String> applicationTypes);
213
214 /**
215 * Get the application states to filter applications on
216 *
217 * @return Set of Application states to filter on
218 */
219 @Public
220 @Stable
221 public abstract EnumSet<YarnApplicationState> getApplicationStates();
222
223 /**
224 * Set the application states to filter applications on
225 *
226 * @param applicationStates
227 * A Set of Application states to filter on.
228 * If not defined, match all running applications
229 */
230 @Private
231 @Unstable
232 public abstract void
233 setApplicationStates(EnumSet<YarnApplicationState> applicationStates);
234
235 /**
236 * Set the application states to filter applications on
237 *
238 * @param applicationStates all lower-case string representation of the
239 * application states to filter on
240 */
241 @Private
242 @Unstable
243 public abstract void setApplicationStates(Set<String> applicationStates);
244
245 /**
246 * Get the users to filter applications on
247 *
248 * @return set of users to filter applications on
249 */
250 @Private
251 @Unstable
252 public abstract Set<String> getUsers();
253
254 /**
255 * Set the users to filter applications on
256 *
257 * @param users set of users to filter applications on
258 */
259 @Private
260 @Unstable
261 public abstract void setUsers(Set<String> users);
262
263 /**
264 * Get the queues to filter applications on
265 *
266 * @return set of queues to filter applications on
267 */
268 @Private
269 @Unstable
270 public abstract Set<String> getQueues();
271
272 /**
273 * Set the queue to filter applications on
274 *
275 * @param queue user to filter applications on
276 */
277 @Private
278 @Unstable
279 public abstract void setQueues(Set<String> queue);
280
281 /**
282 * Get the limit on the number applications to return
283 *
284 * @return number of applications to limit to
285 */
286 @Private
287 @Unstable
288 public abstract long getLimit();
289
290 /**
291 * Limit the number applications to return
292 *
293 * @param limit number of applications to limit to
294 */
295 @Private
296 @Unstable
297 public abstract void setLimit(long limit);
298
299 /**
300 * Get the range of start times to filter applications on
301 *
302 * @return {@link LongRange} of start times to filter applications on
303 */
304 @Private
305 @Unstable
306 public abstract LongRange getStartRange();
307
308 /**
309 * Set the range of start times to filter applications on
310 *
311 * @param begin beginning of the range
312 * @param end end of the range
313 * @throws IllegalArgumentException
314 */
315 @Private
316 @Unstable
317 public abstract void setStartRange(long begin, long end)
318 throws IllegalArgumentException;
319
320 /**
321 * Get the range of finish times to filter applications on
322 *
323 * @return {@link LongRange} of finish times to filter applications on
324 */
325 @Private
326 @Unstable
327 public abstract LongRange getFinishRange();
328
329 /**
330 * Set the range of finish times to filter applications on
331 *
332 * @param begin beginning of the range
333 * @param end end of the range
334 * @throws IllegalArgumentException
335 */
336 @Private
337 @Unstable
338 public abstract void setFinishRange(long begin, long end);
339
340 /**
341 * Get the tags to filter applications on
342 *
343 * @return list of tags to filter on
344 */
345 @Private
346 @Unstable
347 public abstract Set<String> getApplicationTags();
348
349 /**
350 * Set the list of tags to filter applications on
351 *
352 * @param tags list of tags to filter on
353 */
354 @Private
355 @Unstable
356 public abstract void setApplicationTags(Set<String> tags);
357
358 /**
359 * Get the {@link ApplicationsRequestScope} of applications to be filtered.
360 *
361 * @return {@link ApplicationsRequestScope} of applications to return.
362 */
363 @Private
364 @Unstable
365 public abstract ApplicationsRequestScope getScope();
366
367 /**
368 * Set the {@link ApplicationsRequestScope} of applications to filter.
369 *
370 * @param scope scope to use for filtering applications
371 */
372 @Private
373 @Unstable
374 public abstract void setScope(ApplicationsRequestScope scope);
375 }