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 }