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;
020    
021    import java.io.IOException;
022    
023    import org.apache.hadoop.classification.InterfaceAudience.Public;
024    import org.apache.hadoop.classification.InterfaceStability.Stable;
025    import org.apache.hadoop.io.retry.AtMostOnce;
026    import org.apache.hadoop.io.retry.Idempotent;
027    import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest;
028    import org.apache.hadoop.yarn.api.protocolrecords.AllocateResponse;
029    import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterRequest;
030    import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterResponse;
031    import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest;
032    import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterResponse;
033    import org.apache.hadoop.yarn.api.records.Container;
034    import org.apache.hadoop.yarn.api.records.ResourceRequest;
035    import org.apache.hadoop.yarn.conf.YarnConfiguration;
036    import org.apache.hadoop.yarn.exceptions.InvalidApplicationMasterRequestException;
037    import org.apache.hadoop.yarn.exceptions.InvalidResourceBlacklistRequestException;
038    import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException;
039    import 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
051    public 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    }