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   * @return ClientToAMToken master key
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   * @return the queue that the application was placed in.
123   */
124  @Public
125  @Stable
126  public abstract String getQueue();
127  
128  /**
129   * <p>Set the queue that the application was placed in.<p>
130   */
131  @Public
132  @Stable
133  public abstract void setQueue(String queue);
134  
135  /**
136   * <p>
137   * Get the list of running containers as viewed by
138   * <code>ResourceManager</code> from previous application attempts.
139   * </p>
140   * 
141   * @return the list of running containers as viewed by
142   *         <code>ResourceManager</code> from previous application attempts
143   * @see RegisterApplicationMasterResponse#getNMTokensFromPreviousAttempts()
144   */
145  @Public
146  @Unstable
147  public abstract List<Container> getContainersFromPreviousAttempts();
148
149  /**
150   * Set the list of running containers as viewed by
151   * <code>ResourceManager</code> from previous application attempts.
152   * 
153   * @param containersFromPreviousAttempt
154   *          the list of running containers as viewed by
155   *          <code>ResourceManager</code> from previous application attempts.
156   */
157  @Private
158  @Unstable
159  public abstract void setContainersFromPreviousAttempts(
160      List<Container> containersFromPreviousAttempt);
161
162  /**
163   * Get the list of NMTokens for communicating with the NMs where the
164   * containers of previous application attempts are running.
165   * 
166   * @return the list of NMTokens for communicating with the NMs where the
167   *         containers of previous application attempts are running.
168   * 
169   * @see RegisterApplicationMasterResponse#getContainersFromPreviousAttempts()
170   */
171  @Public
172  @Stable
173  public abstract List<NMToken> getNMTokensFromPreviousAttempts();
174
175  /**
176   * Set the list of NMTokens for communicating with the NMs where the the
177   * containers of previous application attempts are running.
178   * 
179   * @param nmTokens
180   *          the list of NMTokens for communicating with the NMs where the
181   *          containers of previous application attempts are running.
182   */
183  @Private
184  @Unstable
185  public abstract void setNMTokensFromPreviousAttempts(List<NMToken> nmTokens);
186
187  /**
188   * Get a set of the resource types considered by the scheduler.
189   *
190   * @return a Map of RM settings
191   */
192  @Public
193  @Unstable
194  public abstract EnumSet<SchedulerResourceTypes> getSchedulerResourceTypes();
195
196  /**
197   * Set the resource types used by the scheduler.
198   *
199   * @param types
200   *          a set of the resource types that the scheduler considers during
201   *          scheduling
202   */
203  @Private
204  @Unstable
205  public abstract void setSchedulerResourceTypes(
206      EnumSet<SchedulerResourceTypes> types);
207}