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