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 java.io.Serializable;
022
023import org.apache.hadoop.classification.InterfaceAudience.Public;
024import org.apache.hadoop.classification.InterfaceStability.Unstable;
025import org.apache.hadoop.yarn.util.Records;
026
027/**
028 * {@link ReservationRequest} represents the request made by an application to
029 * the {@code ResourceManager} to reserve {@link Resource}s.
030 * <p>
031 * It includes:
032 * <ul>
033 *   <li>{@link Resource} required for each request.</li>
034 *   <li>
035 *     Number of containers, of above specifications, which are required by the
036 *     application.
037 *   </li>
038 *   <li>Concurrency that indicates the gang size of the request.</li>
039 * </ul>
040 */
041@Public
042@Unstable
043public abstract class ReservationRequest implements
044    Comparable<ReservationRequest> {
045
046  @Public
047  @Unstable
048  public static ReservationRequest newInstance(Resource capability,
049      int numContainers) {
050    return newInstance(capability, numContainers, 1, -1);
051  }
052
053  @Public
054  @Unstable
055  public static ReservationRequest newInstance(Resource capability,
056      int numContainers, int concurrency, long duration) {
057    ReservationRequest request = Records.newRecord(ReservationRequest.class);
058    request.setCapability(capability);
059    request.setNumContainers(numContainers);
060    request.setConcurrency(concurrency);
061    request.setDuration(duration);
062    return request;
063  }
064
065  @Public
066  @Unstable
067  public static class ReservationRequestComparator implements
068      java.util.Comparator<ReservationRequest>, Serializable {
069
070    private static final long serialVersionUID = 1L;
071
072    @Override
073    public int compare(ReservationRequest r1, ReservationRequest r2) {
074      // Compare numContainers, concurrency and capability
075      int ret = r1.getNumContainers() - r2.getNumContainers();
076      if (ret == 0) {
077        ret = r1.getConcurrency() - r2.getConcurrency();
078      }
079      if (ret == 0) {
080        ret = r1.getCapability().compareTo(r2.getCapability());
081      }
082      return ret;
083    }
084  }
085
086  /**
087   * Get the {@link Resource} capability of the request.
088   * 
089   * @return {@link Resource} capability of the request
090   */
091  @Public
092  @Unstable
093  public abstract Resource getCapability();
094
095  /**
096   * Set the {@link Resource} capability of the request
097   * 
098   * @param capability {@link Resource} capability of the request
099   */
100  @Public
101  @Unstable
102  public abstract void setCapability(Resource capability);
103
104  /**
105   * Get the number of containers required with the given specifications.
106   * 
107   * @return number of containers required with the given specifications
108   */
109  @Public
110  @Unstable
111  public abstract int getNumContainers();
112
113  /**
114   * Set the number of containers required with the given specifications
115   * 
116   * @param numContainers number of containers required with the given
117   *          specifications
118   */
119  @Public
120  @Unstable
121  public abstract void setNumContainers(int numContainers);
122
123  /**
124   * Get the number of containers that need to be scheduled concurrently. The
125   * default value of 1 would fall back to the current non concurrency
126   * constraints on the scheduling behavior.
127   * 
128   * @return the number of containers to be concurrently scheduled
129   */
130  @Public
131  @Unstable
132  public abstract int getConcurrency();
133
134  /**
135   * Set the number of containers that need to be scheduled concurrently. The
136   * default value of 1 would fall back to the current non concurrency
137   * constraints on the scheduling behavior.
138   * 
139   * @param numContainers the number of containers to be concurrently scheduled
140   */
141  @Public
142  @Unstable
143  public abstract void setConcurrency(int numContainers);
144
145  /**
146   * Get the duration in milliseconds for which the resource is required. A
147   * default value of -1, indicates an unspecified lease duration, and fallback
148   * to current behavior.
149   * 
150   * @return the duration in milliseconds for which the resource is required
151   */
152  @Public
153  @Unstable
154  public abstract long getDuration();
155
156  /**
157   * Set the duration in milliseconds for which the resource is required.
158   * 
159   * @param duration the duration in milliseconds for which the resource is
160   *          required
161   */
162  @Public
163  @Unstable
164  public abstract void setDuration(long duration);
165
166  @Override
167  public int hashCode() {
168    final int prime = 2153;
169    int result = 2459;
170    Resource capability = getCapability();
171    result =
172        prime * result + ((capability == null) ? 0 : capability.hashCode());
173    result = prime * result + getNumContainers();
174    result = prime * result + getConcurrency();
175    return result;
176  }
177
178  @Override
179  public boolean equals(Object obj) {
180    if (this == obj)
181      return true;
182    if (obj == null)
183      return false;
184    if (getClass() != obj.getClass())
185      return false;
186    ReservationRequest other = (ReservationRequest) obj;
187    Resource capability = getCapability();
188    if (capability == null) {
189      if (other.getCapability() != null)
190        return false;
191    } else if (!capability.equals(other.getCapability()))
192      return false;
193    if (getNumContainers() != other.getNumContainers())
194      return false;
195    if (getConcurrency() != other.getConcurrency())
196      return false;
197    return true;
198  }
199
200  @Override
201  public int compareTo(ReservationRequest other) {
202    int numContainersComparison =
203        this.getNumContainers() - other.getNumContainers();
204    if (numContainersComparison == 0) {
205      int concurrencyComparison =
206          this.getConcurrency() - other.getConcurrency();
207      if (concurrencyComparison == 0) {
208        return this.getCapability().compareTo(other.getCapability());
209      } else {
210        return concurrencyComparison;
211      }
212    } else {
213      return numContainersComparison;
214    }
215  }
216
217}