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.protocolrecords;
020    
021    import java.util.List;
022    
023    import org.apache.hadoop.classification.InterfaceAudience.Public;
024    import org.apache.hadoop.classification.InterfaceStability.Stable;
025    import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
026    import org.apache.hadoop.yarn.api.records.Container;
027    import org.apache.hadoop.yarn.api.records.ContainerId;
028    import org.apache.hadoop.yarn.api.records.ResourceBlacklistRequest;
029    import org.apache.hadoop.yarn.api.records.ResourceRequest;
030    import org.apache.hadoop.yarn.util.Records;
031    
032    /**
033     * <p>The core request sent by the <code>ApplicationMaster</code> to the 
034     * <code>ResourceManager</code> to obtain resources in the cluster.</p> 
035     *
036     * <p>The request includes:
037     *   <ul>
038     *     <li>A response id to track duplicate responses.</li>
039     *     <li>Progress information.</li>
040     *     <li>
041     *       A list of {@link ResourceRequest} to inform the 
042     *       <code>ResourceManager</code> about the application's 
043     *       resource requirements.
044     *     </li>
045     *     <li>
046     *       A list of unused {@link Container} which are being returned. 
047     *     </li>
048     *   </ul>
049     * </p>
050     * 
051     * @see ApplicationMasterProtocol#allocate(AllocateRequest)
052     */
053    @Public
054    @Stable
055    public abstract class AllocateRequest {
056    
057      @Public
058      @Stable
059      public static AllocateRequest newInstance(int responseID, float appProgress,
060          List<ResourceRequest> resourceAsk,
061          List<ContainerId> containersToBeReleased,
062          ResourceBlacklistRequest resourceBlacklistRequest) {
063        AllocateRequest allocateRequest = Records.newRecord(AllocateRequest.class);
064        allocateRequest.setResponseId(responseID);
065        allocateRequest.setProgress(appProgress);
066        allocateRequest.setAskList(resourceAsk);
067        allocateRequest.setReleaseList(containersToBeReleased);
068        allocateRequest.setResourceBlacklistRequest(resourceBlacklistRequest);
069        return allocateRequest;
070      }
071      
072      /**
073       * Get the <em>response id</em> used to track duplicate responses.
074       * @return <em>response id</em>
075       */
076      @Public
077      @Stable
078      public abstract int getResponseId();
079    
080      /**
081       * Set the <em>response id</em> used to track duplicate responses.
082       * @param id <em>response id</em>
083       */
084      @Public
085      @Stable
086      public abstract void setResponseId(int id);
087    
088      /**
089       * Get the <em>current progress</em> of application. 
090       * @return <em>current progress</em> of application
091       */
092      @Public
093      @Stable
094      public abstract float getProgress();
095      
096      /**
097       * Set the <em>current progress</em> of application
098       * @param progress <em>current progress</em> of application
099       */
100      @Public
101      @Stable
102      public abstract void setProgress(float progress);
103    
104      /**
105       * Get the list of <code>ResourceRequest</code> to update the 
106       * <code>ResourceManager</code> about the application's resource requirements.
107       * @return the list of <code>ResourceRequest</code>
108       * @see ResourceRequest
109       */
110      @Public
111      @Stable
112      public abstract List<ResourceRequest> getAskList();
113      
114      /**
115       * Set list of <code>ResourceRequest</code> to update the
116       * <code>ResourceManager</code> about the application's resource requirements.
117       * @param resourceRequests list of <code>ResourceRequest</code> to update the 
118       *                        <code>ResourceManager</code> about the application's 
119       *                        resource requirements
120       * @see ResourceRequest
121       */
122      @Public
123      @Stable
124      public abstract void setAskList(List<ResourceRequest> resourceRequests);
125    
126      /**
127       * Get the list of <code>ContainerId</code> of containers being 
128       * released by the <code>ApplicationMaster</code>.
129       * @return list of <code>ContainerId</code> of containers being 
130       *         released by the <code>ApplicationMaster</code> 
131       */
132      @Public
133      @Stable
134      public abstract List<ContainerId> getReleaseList();
135    
136      /**
137       * Set the list of <code>ContainerId</code> of containers being
138       * released by the <code>ApplicationMaster</code>
139       * @param releaseContainers list of <code>ContainerId</code> of 
140       *                          containers being released by the 
141       *                          <code>ApplicationMaster</code>
142       */
143      @Public
144      @Stable
145      public abstract void setReleaseList(List<ContainerId> releaseContainers);
146      
147      /**
148       * Get the <code>ResourceBlacklistRequest</code> being sent by the 
149       * <code>ApplicationMaster</code>.
150       * @return the <code>ResourceBlacklistRequest</code> being sent by the 
151       *         <code>ApplicationMaster</code>
152       * @see ResourceBlacklistRequest
153       */
154      @Public
155      @Stable
156      public abstract ResourceBlacklistRequest getResourceBlacklistRequest();
157      
158      /**
159       * Set the <code>ResourceBlacklistRequest</code> to inform the 
160       * <code>ResourceManager</code> about the blacklist additions and removals
161       * per the <code>ApplicationMaster</code>.
162       * 
163       * @param resourceBlacklistRequest the <code>ResourceBlacklistRequest</code>  
164       *                         to inform the <code>ResourceManager</code> about  
165       *                         the blacklist additions and removals
166       *                         per the <code>ApplicationMaster</code>
167       * @see ResourceBlacklistRequest
168       */
169      @Public
170      @Stable
171      public abstract void setResourceBlacklistRequest(
172          ResourceBlacklistRequest resourceBlacklistRequest);
173    }