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 org.apache.hadoop.classification.InterfaceAudience.Public;
022import org.apache.hadoop.classification.InterfaceStability.Unstable;
023import org.apache.hadoop.yarn.util.Records;
024
025/**
026 * {@link ReservationListRequest} captures the set of requirements the
027 * user has to list reservations.
028 */
029@Public
030@Unstable
031public abstract class ReservationListRequest {
032
033  /**
034   * The {@link ReservationListRequest} will use the reservationId to search for
035   * reservations to list if it is provided. Otherwise, it will select active
036   * reservations within the startTime and endTime (inclusive).
037   *
038   * @param queue Required. Cannot be null or empty. Refers to the reservable
039   *              queue in the scheduler that was selected when creating a
040   *              reservation submission {@link ReservationSubmissionRequest}.
041   * @param reservationId Optional. String representation of
042   *                     {@code ReservationId} If provided, other fields will
043   *                     be ignored.
044   * @param startTime Optional. If provided, only reservations that
045   *                end after the startTime will be selected. This defaults
046   *                to 0 if an invalid number is used.
047   * @param endTime Optional. If provided, only reservations that
048   *                start on or before endTime will be selected. This defaults
049   *                to Long.MAX_VALUE if an invalid number is used.
050   * @param includeReservationAllocations Optional. Flag that
051   *                determines whether the entire reservation allocations are
052   *                to be returned. Reservation allocations are subject to
053   *                change in the event of re-planning as described by
054   *                {@code ReservationDefinition}.
055   */
056  @Public
057  @Unstable
058  public static ReservationListRequest newInstance(
059      String queue, String reservationId, long startTime, long endTime,
060      boolean includeReservationAllocations) {
061    ReservationListRequest request =
062        Records.newRecord(ReservationListRequest.class);
063    request.setQueue(queue);
064    request.setReservationId(reservationId);
065    request.setStartTime(startTime);
066    request.setEndTime(endTime);
067    request.setIncludeResourceAllocations(includeReservationAllocations);
068    return request;
069  }
070
071  /**
072   * The {@link ReservationListRequest} will use the reservationId to search for
073   * reservations to list if it is provided. Otherwise, it will select active
074   * reservations within the startTime and endTime (inclusive).
075   *
076   * @param queue Required. Cannot be null or empty. Refers to the reservable
077   *              queue in the scheduler that was selected when creating a
078   *              reservation submission {@link ReservationSubmissionRequest}.
079   * @param reservationId Optional. String representation of
080   *                     {@code ReservationId} If provided, other fields will
081   *                     be ignored.
082   * @param includeReservationAllocations Optional. Flag that
083   *                determines whether the entire reservation allocations are
084   *                to be returned. Reservation allocations are subject to
085   *                change in the event of re-planning as described by
086   *                {@code ReservationDefinition}.
087   */
088  @Public
089  @Unstable
090  public static ReservationListRequest newInstance(
091          String queue, String reservationId, boolean
092          includeReservationAllocations) {
093    return newInstance(queue, reservationId, -1, -1,
094            includeReservationAllocations);
095  }
096
097  /**
098   * The {@link ReservationListRequest} will use the reservationId to search for
099   * reservations to list if it is provided. Otherwise, it will select active
100   * reservations within the startTime and endTime (inclusive).
101   *
102   * @param queue Required. Cannot be null or empty. Refers to the reservable
103   *              queue in the scheduler that was selected when creating a
104   *              reservation submission {@link ReservationSubmissionRequest}.
105   * @param reservationId Optional. String representation of
106   *                     {@code ReservationId} If provided, other fields will
107   *                     be ignored.
108   */
109  @Public
110  @Unstable
111  public static ReservationListRequest newInstance(
112          String queue, String reservationId) {
113    return newInstance(queue, reservationId, -1, -1, false);
114  }
115
116  /**
117   * Get queue name to use to find reservations.
118   *
119   * @return the queue name to use to find reservations.
120   */
121  @Public
122  @Unstable
123  public abstract String getQueue();
124
125  /**
126   * Set queue name to use to find resource allocations.
127   *
128   * @param queue Required. Cannot be null or empty.
129   */
130  @Public
131  @Unstable
132  public abstract void setQueue(String queue);
133
134  /**
135   * Get the reservation id to use to find a reservation.
136   *
137   * @return the reservation id of the reservation.
138   */
139  @Public
140  @Unstable
141  public abstract String getReservationId();
142
143  /**
144   * Set the reservation id to use to find a reservation.
145   *
146   * @param reservationId Optional. String representation of
147   *                     {@code ReservationId} If provided, other fields will
148   *                     be ignored.
149   */
150  @Public
151  @Unstable
152  public abstract void setReservationId(String reservationId);
153
154  /**
155   * Get the start time to use to search for reservations.
156   * When this is set, reservations that start before this start
157   * time are ignored.
158   *
159   * @return the start time to use to search for reservations.
160   */
161  @Public
162  @Unstable
163  public abstract long getStartTime();
164
165  /**
166   * Set the start time to use to search for reservations.
167   * When this is set, reservations that start before this start
168   * time are ignored.
169   *
170   * @param startTime Optional. If provided, only reservations that
171   *                end after the startTime will be selected. This defaults
172   *                to 0 if an invalid number is used.
173   */
174  @Public
175  @Unstable
176  public abstract void setStartTime(long startTime);
177
178  /**
179   * Get the end time to use to search for reservations.
180   * When this is set, reservations that start after this end
181   * time are ignored.
182   *
183   * @return the end time to use to search for reservations.
184   */
185  @Public
186  @Unstable
187  public abstract long getEndTime();
188
189  /**
190   * Set the end time to use to search for reservations.
191   * When this is set, reservations that start after this end
192   * time are ignored.
193   *
194   * @param endTime Optional. If provided, only reservations that
195   *                start before endTime will be selected. This defaults
196   *                to Long.MAX_VALUE if an invalid number is used.
197   */
198  @Public
199  @Unstable
200  public abstract void setEndTime(long endTime);
201
202  /**
203   * Get the boolean representing whether or not the user
204   * is requesting the full resource allocation.
205   * If this is true, the full resource allocation will
206   * be included in the response.
207   *
208   * @return the end time to use to search for reservations.
209   */
210  @Public
211  @Unstable
212  public abstract boolean getIncludeResourceAllocations();
213
214  /**
215   * Set the boolean representing whether or not the user
216   * is requesting the full resource allocation.
217   * If this is true, the full resource allocation will
218   * be included in the response.
219   *
220   * @param includeReservationAllocations Optional. Flag that
221   *                determines whether the entire list of
222   *                {@code ResourceAllocationRequest} will be returned.
223   */
224  @Public
225  @Unstable
226  public abstract void setIncludeResourceAllocations(
227          boolean includeReservationAllocations);
228}