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   * @return a report of Applications in {@link 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   * @return a report of Applications in {@link GetApplicationsRequest}
141   */
142  @Public
143  @Stable
144  public static GetApplicationsRequest
145      newInstance(Set<String> applicationTypes) {
146    GetApplicationsRequest request =
147        Records.newRecord(GetApplicationsRequest.class);
148    request.setApplicationTypes(applicationTypes);
149    return request;
150  }
151
152  /**
153   * <p>
154   * The request from clients to get a report of Applications matching the
155   * giving application states in the cluster from the
156   * <code>ResourceManager</code>.
157   * </p>
158   *
159   *
160   * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
161   * @return  a report of Applications in {@link GetApplicationsRequest}
162   */
163  @Public
164  @Stable
165  public static GetApplicationsRequest newInstance(
166      EnumSet<YarnApplicationState> applicationStates) {
167    GetApplicationsRequest request =
168        Records.newRecord(GetApplicationsRequest.class);
169    request.setApplicationStates(applicationStates);
170    return request;
171  }
172
173  /**
174   * <p>
175   * The request from clients to get a report of Applications matching the
176   * giving and application types and application types in the cluster from the
177   * <code>ResourceManager</code>.
178   * </p>
179   *
180   *
181   * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
182   * @return  a report of Applications in <code>GetApplicationsRequest</code>
183   */
184  @Public
185  @Stable
186  public static GetApplicationsRequest newInstance(
187      Set<String> applicationTypes,
188      EnumSet<YarnApplicationState> applicationStates) {
189    GetApplicationsRequest request =
190        Records.newRecord(GetApplicationsRequest.class);
191    request.setApplicationTypes(applicationTypes);
192    request.setApplicationStates(applicationStates);
193    return request;
194  }
195
196  /**
197   * Get the application types to filter applications on
198   *
199   * @return Set of Application Types to filter on
200   */
201  @Public
202  @Stable
203  public abstract Set<String> getApplicationTypes();
204
205  /**
206   * Set the application types to filter applications on
207   *
208   * @param applicationTypes
209   * A Set of Application Types to filter on.
210   * If not defined, match all applications
211   */
212  @Private
213  @Unstable
214  public abstract void
215      setApplicationTypes(Set<String> applicationTypes);
216
217  /**
218   * Get the application states to filter applications on
219   *
220   * @return Set of Application states to filter on
221   */
222  @Public
223  @Stable
224  public abstract EnumSet<YarnApplicationState> getApplicationStates();
225
226  /**
227   * Set the application states to filter applications on
228   *
229   * @param applicationStates
230   * A Set of Application states to filter on.
231   * If not defined, match all running applications
232   */
233  @Private
234  @Unstable
235  public abstract void
236      setApplicationStates(EnumSet<YarnApplicationState> applicationStates);
237
238  /**
239   * Set the application states to filter applications on
240   *
241   * @param applicationStates all lower-case string representation of the
242   *                          application states to filter on
243   */
244  @Private
245  @Unstable
246  public abstract void setApplicationStates(Set<String> applicationStates);
247
248  /**
249   * Get the users to filter applications on
250   *
251   * @return set of users to filter applications on
252   */
253  @Private
254  @Unstable
255  public abstract Set<String> getUsers();
256
257  /**
258   * Set the users to filter applications on
259   *
260   * @param users set of users to filter applications on
261   */
262  @Private
263  @Unstable
264  public abstract void setUsers(Set<String> users);
265
266  /**
267   * Get the queues to filter applications on
268   *
269   * @return set of queues to filter applications on
270   */
271  @Private
272  @Unstable
273  public abstract Set<String> getQueues();
274
275  /**
276   * Set the queue to filter applications on
277   *
278   * @param queue user to filter applications on
279   */
280  @Private
281  @Unstable
282  public abstract void setQueues(Set<String> queue);
283
284  /**
285   * Get the limit on the number applications to return
286   *
287   * @return number of applications to limit to
288   */
289  @Private
290  @Unstable
291  public abstract long getLimit();
292
293  /**
294   * Limit the number applications to return
295   *
296   * @param limit number of applications to limit to
297   */
298  @Private
299  @Unstable
300  public abstract void setLimit(long limit);
301
302  /**
303   * Get the range of start times to filter applications on
304   *
305   * @return {@link LongRange} of start times to filter applications on
306   */
307  @Private
308  @Unstable
309  public abstract LongRange getStartRange();
310
311  /**
312   * Set the range of start times to filter applications on
313   *
314   * @param range
315   */
316  @Private
317  @Unstable
318  public abstract void setStartRange(LongRange range);
319
320  /**
321   * Set the range of start times to filter applications on
322   *
323   * @param begin beginning of the range
324   * @param end end of the range
325   * @throws IllegalArgumentException
326   */
327  @Private
328  @Unstable
329  public abstract void setStartRange(long begin, long end)
330      throws IllegalArgumentException;
331
332  /**
333   * Get the range of finish times to filter applications on
334   *
335   * @return {@link LongRange} of finish times to filter applications on
336   */
337  @Private
338  @Unstable
339  public abstract LongRange getFinishRange();
340
341  /**
342   * Set the range of finish times to filter applications on
343   *
344   * @param range
345   */
346  @Private
347  @Unstable
348  public abstract void setFinishRange(LongRange range);
349
350  /**
351   * Set the range of finish times to filter applications on
352   *
353   * @param begin beginning of the range
354   * @param end end of the range
355   * @throws IllegalArgumentException
356   */
357  @Private
358  @Unstable
359  public abstract void setFinishRange(long begin, long end);
360
361  /**
362   * Get the tags to filter applications on
363   *
364   * @return list of tags to filter on
365   */
366  @Private
367  @Unstable
368  public abstract Set<String> getApplicationTags();
369
370  /**
371   * Set the list of tags to filter applications on
372   *
373   * @param tags list of tags to filter on
374   */
375  @Private
376  @Unstable
377  public abstract void setApplicationTags(Set<String> tags);
378
379  /**
380   * Get the {@link ApplicationsRequestScope} of applications to be filtered.
381   *
382   * @return {@link ApplicationsRequestScope} of applications to return.
383   */
384  @Private
385  @Unstable
386  public abstract ApplicationsRequestScope getScope();
387
388  /**
389   * Set the {@link ApplicationsRequestScope} of applications to filter.
390   *
391   * @param scope scope to use for filtering applications
392   */
393  @Private
394  @Unstable
395  public abstract void setScope(ApplicationsRequestScope scope);
396}