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