| /** |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package org.apache.hadoop.yarn.api; |
| |
| import java.io.IOException; |
| |
| import org.apache.hadoop.classification.InterfaceAudience.Public; |
| import org.apache.hadoop.classification.InterfaceStability.Stable; |
| import org.apache.hadoop.io.retry.AtMostOnce; |
| import org.apache.hadoop.io.retry.Idempotent; |
| import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest; |
| import org.apache.hadoop.yarn.api.protocolrecords.AllocateResponse; |
| import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterRequest; |
| import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterResponse; |
| import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest; |
| import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterResponse; |
| import org.apache.hadoop.yarn.api.records.Container; |
| import org.apache.hadoop.yarn.api.records.ResourceRequest; |
| import org.apache.hadoop.yarn.conf.YarnConfiguration; |
| import org.apache.hadoop.yarn.exceptions.InvalidApplicationMasterRequestException; |
| import org.apache.hadoop.yarn.exceptions.InvalidResourceBlacklistRequestException; |
| import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException; |
| import org.apache.hadoop.yarn.exceptions.YarnException; |
| |
| /** |
| * <p>The protocol between a live instance of <code>ApplicationMaster</code> |
| * and the <code>ResourceManager</code>.</p> |
| * |
| * <p>This is used by the <code>ApplicationMaster</code> to register/unregister |
| * and to request and obtain resources in the cluster from the |
| * <code>ResourceManager</code>.</p> |
| */ |
| @Public |
| @Stable |
| public interface ApplicationMasterProtocol { |
| |
| /** |
| * <p> |
| * The interface used by a new <code>ApplicationMaster</code> to register with |
| * the <code>ResourceManager</code>. |
| * </p> |
| * |
| * <p> |
| * The <code>ApplicationMaster</code> needs to provide details such as RPC |
| * Port, HTTP tracking url etc. as specified in |
| * {@link RegisterApplicationMasterRequest}. |
| * </p> |
| * |
| * <p> |
| * The <code>ResourceManager</code> responds with critical details such as |
| * maximum resource capabilities in the cluster as specified in |
| * {@link RegisterApplicationMasterResponse}. |
| * </p> |
| * |
| * <p> |
| * Re-register is only allowed for <code>Unmanaged Application Master</code> |
| * (UAM) HA, with |
| * {@link org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext#getKeepContainersAcrossApplicationAttempts()} |
| * set to true. |
| * </p> |
| * |
| * @param request registration request |
| * @return registration response |
| * @throws YarnException exceptions from yarn servers. |
| * @throws IOException io error occur. |
| * @throws InvalidApplicationMasterRequestException The exception is thrown |
| * when an ApplicationMaster tries to register more then once. |
| * @see RegisterApplicationMasterRequest |
| * @see RegisterApplicationMasterResponse |
| */ |
| @Public |
| @Stable |
| @Idempotent |
| public RegisterApplicationMasterResponse registerApplicationMaster( |
| RegisterApplicationMasterRequest request) |
| throws YarnException, IOException; |
| |
| /** |
| * <p>The interface used by an <code>ApplicationMaster</code> to notify the |
| * <code>ResourceManager</code> about its completion (success or failed).</p> |
| * |
| * <p>The <code>ApplicationMaster</code> has to provide details such as |
| * final state, diagnostics (in case of failures) etc. as specified in |
| * {@link FinishApplicationMasterRequest}.</p> |
| * |
| * <p>The <code>ResourceManager</code> responds with |
| * {@link FinishApplicationMasterResponse}.</p> |
| * |
| * @param request completion request |
| * @return completion response |
| * @throws YarnException exceptions from yarn servers. |
| * @throws IOException io error occur. |
| * @see FinishApplicationMasterRequest |
| * @see FinishApplicationMasterResponse |
| */ |
| @Public |
| @Stable |
| @AtMostOnce |
| public FinishApplicationMasterResponse finishApplicationMaster( |
| FinishApplicationMasterRequest request) |
| throws YarnException, IOException; |
| |
| /** |
| * <p> |
| * The main interface between an <code>ApplicationMaster</code> and the |
| * <code>ResourceManager</code>. |
| * </p> |
| * |
| * <p> |
| * The <code>ApplicationMaster</code> uses this interface to provide a list of |
| * {@link ResourceRequest} and returns unused {@link Container} allocated to |
| * it via {@link AllocateRequest}. Optionally, the |
| * <code>ApplicationMaster</code> can also <em>blacklist</em> resources which |
| * it doesn't want to use. |
| * </p> |
| * |
| * <p> |
| * This also doubles up as a <em>heartbeat</em> to let the |
| * <code>ResourceManager</code> know that the <code>ApplicationMaster</code> |
| * is alive. Thus, applications should periodically make this call to be kept |
| * alive. The frequency depends on |
| * {@link YarnConfiguration#RM_AM_EXPIRY_INTERVAL_MS} which defaults to |
| * {@link YarnConfiguration#DEFAULT_RM_AM_EXPIRY_INTERVAL_MS}. |
| * </p> |
| * |
| * <p> |
| * The <code>ResourceManager</code> responds with list of allocated |
| * {@link Container}, status of completed containers and headroom information |
| * for the application. |
| * </p> |
| * |
| * <p> |
| * The <code>ApplicationMaster</code> can use the available headroom |
| * (resources) to decide how to utilized allocated resources and make informed |
| * decisions about future resource requests. |
| * </p> |
| * |
| * @param request |
| * allocation request |
| * @return allocation response |
| * @throws YarnException exceptions from yarn servers. |
| * @throws IOException io error occur. |
| * @throws InvalidApplicationMasterRequestException |
| * This exception is thrown when an ApplicationMaster calls allocate |
| * without registering first. |
| * @throws InvalidResourceBlacklistRequestException |
| * This exception is thrown when an application provides an invalid |
| * specification for blacklist of resources. |
| * @throws InvalidResourceRequestException |
| * This exception is thrown when a {@link ResourceRequest} is out of |
| * the range of the configured lower and upper limits on the |
| * resources. |
| * @see AllocateRequest |
| * @see AllocateResponse |
| */ |
| @Public |
| @Stable |
| @AtMostOnce |
| public AllocateResponse allocate(AllocateRequest request) |
| throws YarnException, IOException; |
| } |