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 }