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