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 }