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.client; 020 021 022 import org.apache.hadoop.classification.InterfaceAudience; 023 import org.apache.hadoop.classification.InterfaceStability; 024 import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterResponse; 025 import org.apache.hadoop.yarn.api.protocolrecords.AllocateResponse; 026 import org.apache.hadoop.yarn.api.records.ContainerId; 027 import org.apache.hadoop.yarn.api.records.FinalApplicationStatus; 028 import org.apache.hadoop.yarn.api.records.Priority; 029 import org.apache.hadoop.yarn.api.records.Resource; 030 import org.apache.hadoop.yarn.exceptions.YarnRemoteException; 031 import org.apache.hadoop.yarn.service.Service; 032 033 @InterfaceAudience.Public 034 @InterfaceStability.Unstable 035 public interface AMRMClient extends Service { 036 037 /** 038 * Value used to define no locality 039 */ 040 static final String ANY = "*"; 041 042 /** 043 * Object to represent container request for resources. 044 * Resources may be localized to nodes and racks. 045 * Resources may be assigned priorities. 046 * Can ask for multiple containers of a given type. 047 */ 048 public static class ContainerRequest { 049 Resource capability; 050 String[] hosts; 051 String[] racks; 052 Priority priority; 053 int containerCount; 054 055 public ContainerRequest(Resource capability, String[] hosts, 056 String[] racks, Priority priority, int containerCount) { 057 this.capability = capability; 058 this.hosts = (hosts != null ? hosts.clone() : null); 059 this.racks = (racks != null ? racks.clone() : null); 060 this.priority = priority; 061 this.containerCount = containerCount; 062 } 063 public String toString() { 064 StringBuilder sb = new StringBuilder(); 065 sb.append("Capability[").append(capability).append("]"); 066 sb.append("Priority[").append(priority).append("]"); 067 sb.append("ContainerCount[").append(containerCount).append("]"); 068 return sb.toString(); 069 } 070 } 071 072 /** 073 * Register the application master. This must be called before any 074 * other interaction 075 * @param appHostName Name of the host on which master is running 076 * @param appHostPort Port master is listening on 077 * @param appTrackingUrl URL at which the master info can be seen 078 * @return <code>RegisterApplicationMasterResponse</code> 079 * @throws YarnRemoteException 080 */ 081 public RegisterApplicationMasterResponse 082 registerApplicationMaster(String appHostName, 083 int appHostPort, 084 String appTrackingUrl) 085 throws YarnRemoteException; 086 087 /** 088 * Request additional containers and receive new container allocations. 089 * Requests made via <code>addContainerRequest</code> are sent to the 090 * <code>ResourceManager</code>. New containers assigned to the master are 091 * retrieved. Status of completed containers and node health updates are 092 * also retrieved. 093 * This also doubles up as a heartbeat to the ResourceManager and must be 094 * made periodically. 095 * The call may not always return any new allocations of containers. 096 * App should not make concurrent allocate requests. May cause request loss. 097 * @param progressIndicator Indicates progress made by the master 098 * @return the response of the allocate request 099 * @throws YarnRemoteException 100 */ 101 public AllocateResponse allocate(float progressIndicator) 102 throws YarnRemoteException; 103 104 /** 105 * Unregister the application master. This must be called in the end. 106 * @param appStatus Success/Failure status of the master 107 * @param appMessage Diagnostics message on failure 108 * @param appTrackingUrl New URL to get master info 109 * @throws YarnRemoteException 110 */ 111 public void unregisterApplicationMaster(FinalApplicationStatus appStatus, 112 String appMessage, 113 String appTrackingUrl) 114 throws YarnRemoteException; 115 116 /** 117 * Request containers for resources before calling <code>allocate</code> 118 * @param req Resource request 119 */ 120 public void addContainerRequest(ContainerRequest req); 121 122 /** 123 * Remove previous container request. The previous container request may have 124 * already been sent to the ResourceManager. So even after the remove request 125 * the app must be prepared to receive an allocation for the previous request 126 * even after the remove request 127 * @param req Resource request 128 */ 129 public void removeContainerRequest(ContainerRequest req); 130 131 /** 132 * Release containers assigned by the Resource Manager. If the app cannot use 133 * the container or wants to give up the container then it can release them. 134 * The app needs to make new requests for the released resource capability if 135 * it still needs it. eg. it released non-local resources 136 * @param containerId 137 */ 138 public void releaseAssignedContainer(ContainerId containerId); 139 140 /** 141 * Get the currently available resources in the cluster. 142 * A valid value is available after a call to allocate has been made 143 * @return Currently available resources 144 */ 145 public Resource getClusterAvailableResources(); 146 147 /** 148 * Get the current number of nodes in the cluster. 149 * A valid values is available after a call to allocate has been made 150 * @return Current number of nodes in the cluster 151 */ 152 public int getClusterNodeCount(); 153 }