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 org.apache.hadoop.classification.InterfaceAudience.Public;
022    import org.apache.hadoop.classification.InterfaceStability.Stable;
023    import org.apache.hadoop.yarn.api.AMRMProtocol;
024    
025    /**
026     * <p><code>ResourceRequest</code> represents the request made by an
027     * application to the <code>ResourceManager</code> to obtain various 
028     * <code>Container</code> allocations.</p>
029     * 
030     * <p>It includes:
031     *   <ul>
032     *     <li>{@link Priority} of the request.</li>
033     *     <li>
034     *       The <em>name</em> of the machine or rack on which the allocation is 
035     *       desired. A special value of <em>*</em> signifies that 
036     *       <em>any</em> host/rack is acceptable to the application.
037     *     </li>
038     *     <li>{@link Resource} required for each request.</li>
039     *     <li>
040     *       Number of containers of such specifications which are required 
041     *       by the application.
042     *     </li>
043     *   </ul>
044     * </p>
045     * 
046     * @see Resource
047     * @see AMRMProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest)
048     */
049    @Public
050    @Stable
051    public abstract class ResourceRequest implements Comparable<ResourceRequest> {
052    
053      /**
054       * The constant string representing no locality.
055       * It should be used by all references that want to pass an arbitrary host
056       * name in.
057       */
058      public static final String ANY = "*";
059    
060      /**
061       * Check whether the given <em>host/rack</em> string represents an arbitrary
062       * host name.
063       *
064       * @param hostName <em>host/rack</em> on which the allocation is desired
065       * @return whether the given <em>host/rack</em> string represents an arbitrary
066       * host name
067       */
068      public static boolean isAnyLocation(String hostName) {
069        return ANY.equals(hostName);
070      }
071    
072      /**
073       * Get the <code>Priority</code> of the request.
074       * @return <code>Priority</code> of the request
075       */
076      @Public
077      @Stable
078      public abstract Priority getPriority();
079    
080      /**
081       * Set the <code>Priority</code> of the request
082       * @param priority <code>Priority</code> of the request
083       */
084      @Public
085      @Stable
086      public abstract void setPriority(Priority priority);
087      
088      /**
089       * Get the <em>host/rack</em> on which the allocation is desired.
090       * 
091       * A special value of <em>*</em> signifies that <em>any</em> host/rack is 
092       * acceptable.
093       * 
094       * @return <em>host/rack</em> on which the allocation is desired
095       */
096      @Public
097      @Stable
098      public abstract String getHostName();
099    
100      /**
101       * Set <em>host/rack</em> on which the allocation is desired.
102       * 
103       * A special value of <em>*</em> signifies that <em>any</em> host/rack is 
104       * acceptable.
105       * 
106       * @param hostName <em>host/rack</em> on which the allocation is desired
107       */
108      @Public
109      @Stable
110      public abstract void setHostName(String hostName);
111      
112      /**
113       * Get the <code>Resource</code> capability of the request.
114       * @return <code>Resource</code> capability of the request
115       */
116      @Public
117      @Stable
118      public abstract Resource getCapability();
119      
120      /**
121       * Set the <code>Resource</code> capability of the request
122       * @param capability <code>Resource</code> capability of the request
123       */
124      @Public
125      @Stable
126      public abstract void setCapability(Resource capability);
127    
128      /**
129       * Get the number of containers required with the given specifications.
130       * @return number of containers required with the given specifications
131       */
132      @Public
133      @Stable
134      public abstract int getNumContainers();
135      
136      /**
137       * Set the number of containers required with the given specifications
138       * @param numContainers number of containers required with the given 
139       *                      specifications
140       */
141      @Public
142      @Stable
143      public abstract void setNumContainers(int numContainers);
144    
145      @Override
146      public int hashCode() {
147        final int prime = 31;
148        int result = 1;
149        Resource capability = getCapability();
150        String hostName = getHostName();
151        Priority priority = getPriority();
152        result =
153            prime * result + ((capability == null) ? 0 : capability.hashCode());
154        result = prime * result + ((hostName == null) ? 0 : hostName.hashCode());
155        result = prime * result + getNumContainers();
156        result = prime * result + ((priority == null) ? 0 : priority.hashCode());
157        return result;
158      }
159    
160      @Override
161      public boolean equals(Object obj) {
162        if (this == obj)
163          return true;
164        if (obj == null)
165          return false;
166        if (getClass() != obj.getClass())
167          return false;
168        ResourceRequest other = (ResourceRequest) obj;
169        Resource capability = getCapability();
170        if (capability == null) {
171          if (other.getCapability() != null)
172            return false;
173        } else if (!capability.equals(other.getCapability()))
174          return false;
175        String hostName = getHostName();
176        if (hostName == null) {
177          if (other.getHostName() != null)
178            return false;
179        } else if (!hostName.equals(other.getHostName()))
180          return false;
181        if (getNumContainers() != other.getNumContainers())
182          return false;
183        Priority priority = getPriority();
184        if (priority == null) {
185          if (other.getPriority() != null)
186            return false;
187        } else if (!priority.equals(other.getPriority()))
188          return false;
189        return true;
190      }
191    
192      @Override
193      public int compareTo(ResourceRequest other) {
194        int priorityComparison = this.getPriority().compareTo(other.getPriority());
195        if (priorityComparison == 0) {
196          int hostNameComparison =
197              this.getHostName().compareTo(other.getHostName());
198          if (hostNameComparison == 0) {
199            int capabilityComparison =
200                this.getCapability().compareTo(other.getCapability());
201            if (capabilityComparison == 0) {
202              int numContainersComparison =
203                  this.getNumContainers() - other.getNumContainers();
204              if (numContainersComparison == 0) {
205                return 0;
206              } else {
207                return numContainersComparison;
208              }
209            } else {
210              return capabilityComparison;
211            }
212          } else {
213            return hostNameComparison;
214          }
215        } else {
216          return priorityComparison;
217        }
218      }
219    }