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.nio.ByteBuffer;
022    import java.util.EnumSet;
023    import java.util.List;
024    import java.util.Map;
025    
026    import org.apache.hadoop.classification.InterfaceAudience.Private;
027    import org.apache.hadoop.classification.InterfaceAudience.Public;
028    import org.apache.hadoop.classification.InterfaceStability.Stable;
029    import org.apache.hadoop.classification.InterfaceStability.Unstable;
030    import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
031    import org.apache.hadoop.yarn.api.records.ApplicationAccessType;
032    import org.apache.hadoop.yarn.api.records.Container;
033    import org.apache.hadoop.yarn.api.records.NMToken;
034    import org.apache.hadoop.yarn.api.records.Resource;
035    import org.apache.hadoop.yarn.proto.YarnServiceProtos.SchedulerResourceTypes;
036    import org.apache.hadoop.yarn.util.Records;
037    
038    /**
039     * <p>The response sent by the <code>ResourceManager</code> to a new 
040     * <code>ApplicationMaster</code> on registration.</p>
041     * 
042     * <p>The response contains critical details such as:
043     * <ul>
044     *   <li>Maximum capability for allocated resources in the cluster.</li>
045     *   <li><code>ApplicationACL</code>s for the application.</li>
046     *   <li>ClientToAMToken master key.</li>
047     * </ul>
048     * </p>
049     * 
050     * @see ApplicationMasterProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)
051     */
052    @Public
053    @Stable
054    public abstract class RegisterApplicationMasterResponse {
055    
056      @Private
057      @Unstable
058      public static RegisterApplicationMasterResponse newInstance(
059          Resource minCapability, Resource maxCapability,
060          Map<ApplicationAccessType, String> acls, ByteBuffer key,
061          List<Container> containersFromPreviousAttempt, String queue,
062          List<NMToken> nmTokensFromPreviousAttempts) {
063        RegisterApplicationMasterResponse response =
064            Records.newRecord(RegisterApplicationMasterResponse.class);
065        response.setMaximumResourceCapability(maxCapability);
066        response.setApplicationACLs(acls);
067        response.setClientToAMTokenMasterKey(key);
068        response.setContainersFromPreviousAttempts(containersFromPreviousAttempt);
069        response.setNMTokensFromPreviousAttempts(nmTokensFromPreviousAttempts);
070        response.setQueue(queue);
071        return response;
072      }
073    
074      /**
075       * Get the maximum capability for any {@link Resource} allocated by the 
076       * <code>ResourceManager</code> in the cluster.
077       * @return maximum capability of allocated resources in the cluster
078       */
079      @Public
080      @Stable
081      public abstract Resource getMaximumResourceCapability();
082      
083      @Private
084      @Unstable
085      public abstract void setMaximumResourceCapability(Resource capability);
086    
087      /**
088       * Get the <code>ApplicationACL</code>s for the application. 
089       * @return all the <code>ApplicationACL</code>s
090       */
091      @Public
092      @Stable
093      public abstract Map<ApplicationAccessType, String> getApplicationACLs();
094    
095      /**
096       * Set the <code>ApplicationACL</code>s for the application. 
097       * @param acls
098       */
099      @Private
100      @Unstable
101      public abstract void setApplicationACLs(Map<ApplicationAccessType, String> acls);
102    
103      /**
104       * <p>Get ClientToAMToken master key.</p>
105       * <p>The ClientToAMToken master key is sent to <code>ApplicationMaster</code>
106       * by <code>ResourceManager</code> via {@link RegisterApplicationMasterResponse}
107       * , used to verify corresponding ClientToAMToken.</p>
108       */
109      @Public
110      @Stable
111      public abstract ByteBuffer getClientToAMTokenMasterKey();
112    
113      /**
114       * Set ClientToAMToken master key.
115       */
116      @Public
117      @Stable
118      public abstract void setClientToAMTokenMasterKey(ByteBuffer key);
119    
120      /**
121       * <p>Get the queue that the application was placed in.<p>
122       */
123      @Public
124      @Stable
125      public abstract String getQueue();
126      
127      /**
128       * <p>Set the queue that the application was placed in.<p>
129       */
130      @Public
131      @Stable
132      public abstract void setQueue(String queue);
133      
134      /**
135       * <p>
136       * Get the list of running containers as viewed by
137       * <code>ResourceManager</code> from previous application attempts.
138       * </p>
139       * 
140       * @return the list of running containers as viewed by
141       *         <code>ResourceManager</code> from previous application attempts
142       * @see RegisterApplicationMasterResponse#getNMTokensFromPreviousAttempts()
143       */
144      @Public
145      @Unstable
146      public abstract List<Container> getContainersFromPreviousAttempts();
147    
148      /**
149       * Set the list of running containers as viewed by
150       * <code>ResourceManager</code> from previous application attempts.
151       * 
152       * @param containersFromPreviousAttempt
153       *          the list of running containers as viewed by
154       *          <code>ResourceManager</code> from previous application attempts.
155       */
156      @Private
157      @Unstable
158      public abstract void setContainersFromPreviousAttempts(
159          List<Container> containersFromPreviousAttempt);
160    
161      /**
162       * Get the list of NMTokens for communicating with the NMs where the
163       * containers of previous application attempts are running.
164       * 
165       * @return the list of NMTokens for communicating with the NMs where the
166       *         containers of previous application attempts are running.
167       * 
168       * @see RegisterApplicationMasterResponse#getContainersFromPreviousAttempts()
169       */
170      @Public
171      @Stable
172      public abstract List<NMToken> getNMTokensFromPreviousAttempts();
173    
174      /**
175       * Set the list of NMTokens for communicating with the NMs where the the
176       * containers of previous application attempts are running.
177       * 
178       * @param nmTokens
179       *          the list of NMTokens for communicating with the NMs where the
180       *          containers of previous application attempts are running.
181       */
182      @Private
183      @Unstable
184      public abstract void setNMTokensFromPreviousAttempts(List<NMToken> nmTokens);
185    
186      /**
187       * Get a set of the resource types considered by the scheduler.
188       *
189       * @return a Map of RM settings
190       */
191      @Public
192      @Unstable
193      public abstract EnumSet<SchedulerResourceTypes> getSchedulerResourceTypes();
194    
195      /**
196       * Set the resource types used by the scheduler.
197       *
198       * @param types
199       *          a set of the resource types that the scheduler considers during
200       *          scheduling
201       */
202      @Private
203      @Unstable
204      public abstract void setSchedulerResourceTypes(
205          EnumSet<SchedulerResourceTypes> types);
206    }