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 org.apache.hadoop.classification.InterfaceAudience.Public; 022 import org.apache.hadoop.classification.InterfaceStability.Stable; 023 import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest; 024 import org.apache.hadoop.yarn.api.protocolrecords.AllocateResponse; 025 import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterRequest; 026 import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterResponse; 027 import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest; 028 import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterResponse; 029 import org.apache.hadoop.yarn.api.records.Container; 030 import org.apache.hadoop.yarn.api.records.ResourceRequest; 031 import org.apache.hadoop.yarn.exceptions.YarnRemoteException; 032 033 /** 034 * <p>The protocol between a live instance of <code>ApplicationMaster</code> 035 * and the <code>ResourceManager</code>.</p> 036 * 037 * <p>This is used by the <code>ApplicationMaster</code> to register/unregister 038 * and to request and obtain resources in the cluster from the 039 * <code>ResourceManager</code>.</p> 040 */ 041 @Public 042 @Stable 043 public interface AMRMProtocol { 044 045 /** 046 * <p>The interface used by a new <code>ApplicationMaster</code> to register 047 * with the <code>ResourceManager</code>.</p> 048 * 049 * <p>The <code>ApplicationMaster</code> needs to provide details such 050 * as RPC Port, HTTP tracking url etc. as specified in 051 * {@link RegisterApplicationMasterRequest}.</p> 052 * 053 * <p>The <code>ResourceManager</code> responds with critical details such 054 * as minimum and maximum resource capabilities in the cluster as specified in 055 * {@link RegisterApplicationMasterResponse}.</p> 056 * 057 * @param request registration request 058 * @return registration respose 059 * @throws YarnRemoteException 060 */ 061 public RegisterApplicationMasterResponse registerApplicationMaster( 062 RegisterApplicationMasterRequest request) 063 throws YarnRemoteException; 064 065 /** 066 * <p>The interface used by an <code>ApplicationMaster</code> to notify the 067 * <code>ResourceManager</code> about its completion (success or failed).</p> 068 * 069 * <p>The <code>ApplicationMaster</code> has to provide details such as 070 * final state, diagnostics (in case of failures) etc. as specified in 071 * {@link FinishApplicationMasterRequest}.</p> 072 * 073 * <p>The <code>ResourceManager</code> responds with 074 * {@link FinishApplicationMasterResponse}.</p> 075 * 076 * @param request completion request 077 * @return completion response 078 * @throws YarnRemoteException 079 */ 080 public FinishApplicationMasterResponse finishApplicationMaster( 081 FinishApplicationMasterRequest request) 082 throws YarnRemoteException; 083 084 /** 085 * <p>The main interface between an <code>ApplicationMaster</code> 086 * and the <code>ResourceManager</code>.</p> 087 * 088 * <p>The <code>ApplicationMaster</code> uses this interface to provide a list 089 * of {@link ResourceRequest} and returns unused {@link Container} allocated 090 * to it via {@link AllocateRequest}.</p> 091 * 092 * <p>This also doubles up as a <em>heartbeat</em> to let the 093 * <code>ResourceManager</code> know that the <code>ApplicationMaster</code> 094 * is alive. Thus, applications should periodically make this call to be kept 095 * alive. The frequency depends on ??</p> 096 * 097 * <p>The <code>ResourceManager</code> responds with list of allocated 098 * {@link Container}, status of completed containers and headroom information 099 * for the application.</p> 100 * 101 * <p>The <code>ApplicationMaster</code> can use the available headroom 102 * (resources) to decide how to utilized allocated resources and make 103 * informed decisions about future resource requests.</p> 104 * 105 * @param request allocation request 106 * @return allocation response 107 * @throws YarnRemoteException 108 */ 109 public AllocateResponse allocate(AllocateRequest request) 110 throws YarnRemoteException; 111 }