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