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;
020
021import java.io.IOException;
022
023import org.apache.hadoop.classification.InterfaceAudience.Public;
024import org.apache.hadoop.classification.InterfaceStability.Stable;
025import org.apache.hadoop.io.retry.AtMostOnce;
026import org.apache.hadoop.io.retry.Idempotent;
027import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest;
028import org.apache.hadoop.yarn.api.protocolrecords.AllocateResponse;
029import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterRequest;
030import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterResponse;
031import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest;
032import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterResponse;
033import org.apache.hadoop.yarn.api.records.Container;
034import org.apache.hadoop.yarn.api.records.ResourceRequest;
035import org.apache.hadoop.yarn.conf.YarnConfiguration;
036import org.apache.hadoop.yarn.exceptions.InvalidApplicationMasterRequestException;
037import org.apache.hadoop.yarn.exceptions.InvalidResourceBlacklistRequestException;
038import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException;
039import org.apache.hadoop.yarn.exceptions.YarnException;
040
041/**
042 * <p>The protocol between a live instance of <code>ApplicationMaster</code> 
043 * and the <code>ResourceManager</code>.</p>
044 * 
045 * <p>This is used by the <code>ApplicationMaster</code> to register/unregister
046 * and to request and obtain resources in the cluster from the
047 * <code>ResourceManager</code>.</p>
048 */
049@Public
050@Stable
051public interface ApplicationMasterProtocol {
052
053  /**
054   * <p>
055   * The interface used by a new <code>ApplicationMaster</code> to register with
056   * the <code>ResourceManager</code>.
057   * </p>
058   * 
059   * <p>
060   * The <code>ApplicationMaster</code> needs to provide details such as RPC
061   * Port, HTTP tracking url etc. as specified in
062   * {@link RegisterApplicationMasterRequest}.
063   * </p>
064   * 
065   * <p>
066   * The <code>ResourceManager</code> responds with critical details such as
067   * maximum resource capabilities in the cluster as specified in
068   * {@link RegisterApplicationMasterResponse}.
069   * </p>
070   * 
071   * @param request
072   *          registration request
073   * @return registration respose
074   * @throws YarnException
075   * @throws IOException
076   * @throws InvalidApplicationMasterRequestException
077   *           The exception is thrown when an ApplicationMaster tries to
078   *           register more then once.
079   * @see RegisterApplicationMasterRequest
080   * @see RegisterApplicationMasterResponse
081   */
082  @Public
083  @Stable
084  @Idempotent
085  public RegisterApplicationMasterResponse registerApplicationMaster(
086      RegisterApplicationMasterRequest request) 
087  throws YarnException, IOException;
088  
089  /**
090   * <p>The interface used by an <code>ApplicationMaster</code> to notify the 
091   * <code>ResourceManager</code> about its completion (success or failed).</p>
092   * 
093   * <p>The <code>ApplicationMaster</code> has to provide details such as 
094   * final state, diagnostics (in case of failures) etc. as specified in 
095   * {@link FinishApplicationMasterRequest}.</p>
096   * 
097   * <p>The <code>ResourceManager</code> responds with 
098   * {@link FinishApplicationMasterResponse}.</p>
099   * 
100   * @param request completion request
101   * @return completion response
102   * @throws YarnException
103   * @throws IOException
104   * @see FinishApplicationMasterRequest
105   * @see FinishApplicationMasterResponse
106   */
107  @Public
108  @Stable
109  @AtMostOnce
110  public FinishApplicationMasterResponse finishApplicationMaster(
111      FinishApplicationMasterRequest request) 
112  throws YarnException, IOException;
113
114  /**
115   * <p>
116   * The main interface between an <code>ApplicationMaster</code> and the
117   * <code>ResourceManager</code>.
118   * </p>
119   * 
120   * <p>
121   * The <code>ApplicationMaster</code> uses this interface to provide a list of
122   * {@link ResourceRequest} and returns unused {@link Container} allocated to
123   * it via {@link AllocateRequest}. Optionally, the
124   * <code>ApplicationMaster</code> can also <em>blacklist</em> resources which
125   * it doesn't want to use.
126   * </p>
127   * 
128   * <p>
129   * This also doubles up as a <em>heartbeat</em> to let the
130   * <code>ResourceManager</code> know that the <code>ApplicationMaster</code>
131   * is alive. Thus, applications should periodically make this call to be kept
132   * alive. The frequency depends on
133   * {@link YarnConfiguration#RM_AM_EXPIRY_INTERVAL_MS} which defaults to
134   * {@link YarnConfiguration#DEFAULT_RM_AM_EXPIRY_INTERVAL_MS}.
135   * </p>
136   * 
137   * <p>
138   * The <code>ResourceManager</code> responds with list of allocated
139   * {@link Container}, status of completed containers and headroom information
140   * for the application.
141   * </p>
142   * 
143   * <p>
144   * The <code>ApplicationMaster</code> can use the available headroom
145   * (resources) to decide how to utilized allocated resources and make informed
146   * decisions about future resource requests.
147   * </p>
148   * 
149   * @param request
150   *          allocation request
151   * @return allocation response
152   * @throws YarnException
153   * @throws IOException
154   * @throws InvalidApplicationMasterRequestException
155   *           This exception is thrown when an ApplicationMaster calls allocate
156   *           without registering first.
157   * @throws InvalidResourceBlacklistRequestException
158   *           This exception is thrown when an application provides an invalid
159   *           specification for blacklist of resources.
160   * @throws InvalidResourceRequestException
161   *           This exception is thrown when a {@link ResourceRequest} is out of
162   *           the range of the configured lower and upper limits on the
163   *           resources.
164   * @see AllocateRequest
165   * @see AllocateResponse
166   */
167  @Public
168  @Stable
169  @AtMostOnce
170  public AllocateResponse allocate(AllocateRequest request) 
171  throws YarnException, IOException;
172}