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}