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.protocolrecords;
020
021import java.nio.ByteBuffer;
022import java.util.EnumSet;
023import java.util.List;
024import java.util.Map;
025
026import org.apache.hadoop.classification.InterfaceAudience.Private;
027import org.apache.hadoop.classification.InterfaceAudience.Public;
028import org.apache.hadoop.classification.InterfaceStability.Stable;
029import org.apache.hadoop.classification.InterfaceStability.Unstable;
030import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
031import org.apache.hadoop.yarn.api.records.ApplicationAccessType;
032import org.apache.hadoop.yarn.api.records.Container;
033import org.apache.hadoop.yarn.api.records.NMToken;
034import org.apache.hadoop.yarn.api.records.Resource;
035import org.apache.hadoop.yarn.proto.YarnServiceProtos.SchedulerResourceTypes;
036import 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
054public 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}