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.EnumSet;
022import java.util.Set;
023
024import org.apache.commons.lang.math.LongRange;
025import org.apache.hadoop.classification.InterfaceAudience.Private;
026import org.apache.hadoop.classification.InterfaceAudience.Public;
027import org.apache.hadoop.classification.InterfaceStability.Stable;
028import org.apache.hadoop.classification.InterfaceStability.Unstable;
029import org.apache.hadoop.yarn.api.ApplicationClientProtocol;
030import org.apache.hadoop.yarn.api.records.YarnApplicationState;
031import 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
042public 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 range
312   */
313  @Private
314  @Unstable
315  public abstract void setStartRange(LongRange range);
316
317  /**
318   * Set the range of start times to filter applications on
319   *
320   * @param begin beginning of the range
321   * @param end end of the range
322   * @throws IllegalArgumentException
323   */
324  @Private
325  @Unstable
326  public abstract void setStartRange(long begin, long end)
327      throws IllegalArgumentException;
328
329  /**
330   * Get the range of finish times to filter applications on
331   *
332   * @return {@link LongRange} of finish times to filter applications on
333   */
334  @Private
335  @Unstable
336  public abstract LongRange getFinishRange();
337
338  /**
339   * Set the range of finish times to filter applications on
340   *
341   * @param range
342   */
343  @Private
344  @Unstable
345  public abstract void setFinishRange(LongRange range);
346
347  /**
348   * Set the range of finish times to filter applications on
349   *
350   * @param begin beginning of the range
351   * @param end end of the range
352   * @throws IllegalArgumentException
353   */
354  @Private
355  @Unstable
356  public abstract void setFinishRange(long begin, long end);
357
358  /**
359   * Get the tags to filter applications on
360   *
361   * @return list of tags to filter on
362   */
363  @Private
364  @Unstable
365  public abstract Set<String> getApplicationTags();
366
367  /**
368   * Set the list of tags to filter applications on
369   *
370   * @param tags list of tags to filter on
371   */
372  @Private
373  @Unstable
374  public abstract void setApplicationTags(Set<String> tags);
375
376  /**
377   * Get the {@link ApplicationsRequestScope} of applications to be filtered.
378   *
379   * @return {@link ApplicationsRequestScope} of applications to return.
380   */
381  @Private
382  @Unstable
383  public abstract ApplicationsRequestScope getScope();
384
385  /**
386   * Set the {@link ApplicationsRequestScope} of applications to filter.
387   *
388   * @param scope scope to use for filtering applications
389   */
390  @Private
391  @Unstable
392  public abstract void setScope(ApplicationsRequestScope scope);
393}