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