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