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 019package org.apache.hadoop.yarn.api; 020 021import java.io.IOException; 022 023import org.apache.hadoop.classification.InterfaceAudience.Public; 024import org.apache.hadoop.classification.InterfaceStability.Stable; 025import org.apache.hadoop.io.retry.AtMostOnce; 026import org.apache.hadoop.io.retry.Idempotent; 027import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest; 028import org.apache.hadoop.yarn.api.protocolrecords.AllocateResponse; 029import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterRequest; 030import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterResponse; 031import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest; 032import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterResponse; 033import org.apache.hadoop.yarn.api.records.Container; 034import org.apache.hadoop.yarn.api.records.ResourceRequest; 035import org.apache.hadoop.yarn.conf.YarnConfiguration; 036import org.apache.hadoop.yarn.exceptions.InvalidApplicationMasterRequestException; 037import org.apache.hadoop.yarn.exceptions.InvalidResourceBlacklistRequestException; 038import org.apache.hadoop.yarn.exceptions.InvalidResourceRequestException; 039import 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 051public 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}