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.records;
020
021import org.apache.hadoop.classification.InterfaceAudience.Private;
022import org.apache.hadoop.classification.InterfaceAudience.Public;
023import org.apache.hadoop.classification.InterfaceStability.Stable;
024import org.apache.hadoop.classification.InterfaceStability.Unstable;
025import org.apache.hadoop.yarn.util.Records;
026
027import java.util.List;
028
029/**
030 * {@code ReservationAllocationState} represents the reservation that is
031 * made by a user.
032 * <p>
033 * It includes:
034 * <ul>
035 *   <li>Duration of the reservation.</li>
036 *   <li>Acceptance time of the duration.</li>
037 *   <li>
038 *       List of {@link ResourceAllocationRequest}, which includes the time
039 *       interval, and capability of the allocation.
040 *       {@code ResourceAllocationRequest} represents an allocation
041 *       made for a reservation for the current state of the queue. This can be
042 *       changed for reasons such as re-planning, but will always be subject to
043 *       the constraints of the user contract as described by
044 *       {@link ReservationDefinition}
045 *   </li>
046 *   <li>{@link ReservationId} of the reservation.</li>
047 *   <li>{@link ReservationDefinition} used to make the reservation.</li>
048 * </ul>
049 *
050 * @see ResourceAllocationRequest
051 * @see ReservationId
052 * @see ReservationDefinition
053 */
054@Public
055@Stable
056public abstract class ReservationAllocationState {
057
058  /**
059   *
060   * @param acceptanceTime The acceptance time of the reservation.
061   * @param user The username of the user who made the reservation.
062   * @param resourceAllocations List of {@link ResourceAllocationRequest}
063   *                            representing the current state of the
064   *                            reservation resource allocations. This is
065   *                            subject to change in the event of re-planning.
066   * @param reservationId {@link ReservationId } of the reservation being
067   *                                            listed.
068   * @param reservationDefinition {@link ReservationDefinition} used to make
069   *                              the reservation.
070   * @return {@code ReservationAllocationState} that represents the state of
071   * the reservation.
072   */
073  @Public
074  @Stable
075  public static ReservationAllocationState newInstance(long acceptanceTime,
076           String user, List<ResourceAllocationRequest> resourceAllocations,
077           ReservationId reservationId,
078           ReservationDefinition reservationDefinition) {
079    ReservationAllocationState ri = Records.newRecord(
080            ReservationAllocationState.class);
081    ri.setAcceptanceTime(acceptanceTime);
082    ri.setUser(user);
083    ri.setResourceAllocationRequests(resourceAllocations);
084    ri.setReservationId(reservationId);
085    ri.setReservationDefinition(reservationDefinition);
086    return ri;
087  }
088
089  /**
090   * Get the acceptance time of the reservation.
091   *
092   * @return the time that the reservation was accepted.
093   */
094  @Public
095  @Unstable
096  public abstract long getAcceptanceTime();
097
098  /**
099   * Set the time that the reservation was accepted.
100   *
101   * @param acceptanceTime The acceptance time of the reservation.
102   */
103  @Private
104  @Unstable
105  public abstract void setAcceptanceTime(long acceptanceTime);
106
107  /**
108   * Get the user who made the reservation.
109   *
110   * @return the name of the user who made the reservation.
111   */
112  @Public
113  @Unstable
114  public abstract String getUser();
115
116  /**
117   * Set the user who made the reservation.
118   *
119   * @param user The username of the user who made the reservation.
120   */
121  @Private
122  @Unstable
123  public abstract void setUser(String user);
124
125  /**
126   * Get the Resource allocations of the reservation based on the current state
127   * of the plan. This is subject to change in the event of re-planning.
128   * The allocations will be constraint to the user contract as described by
129   * the {@link ReservationDefinition}
130   *
131   * @return a list of resource allocations for the reservation.
132   */
133  @Public
134  @Unstable
135  public abstract List<ResourceAllocationRequest>
136          getResourceAllocationRequests();
137
138  /**
139   * Set the list of resource allocations made for the reservation.
140   *
141   * @param resourceAllocations List of {@link ResourceAllocationRequest}
142   *                            representing the current state of the
143   *                            reservation resource allocations. This is
144   *                            subject to change in the event of re-planning.
145   */
146  @Private
147  @Unstable
148  public abstract void setResourceAllocationRequests(
149          List<ResourceAllocationRequest> resourceAllocations);
150
151  /**
152   * Get the id of the reservation.
153   *
154   * @return the reservation id corresponding to the reservation.
155   */
156  @Public
157  @Unstable
158  public abstract ReservationId getReservationId();
159
160  /**
161   * Set the id corresponding to the reservation.
162   * `
163   * @param reservationId {@link ReservationId } of the reservation being
164   *                                            listed.
165   */
166  @Private
167  @Unstable
168  public abstract void setReservationId(ReservationId reservationId);
169
170  /**
171   * Get the reservation definition used to make the reservation.
172   *
173   * @return the reservation definition used to make the reservation.
174   */
175  @Public
176  @Unstable
177  public abstract ReservationDefinition getReservationDefinition();
178
179  /**
180   * Set the definition of the reservation.
181   *
182   * @param reservationDefinition {@link ReservationDefinition} used to make
183   *                              the reservation.
184   */
185  @Private
186  @Unstable
187  public abstract void setReservationDefinition(ReservationDefinition
188                                                      reservationDefinition);
189
190
191}