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 }