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 024 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationRequest; 025 import org.apache.hadoop.yarn.api.protocolrecords.KillApplicationResponse; 026 import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsRequest; 027 import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsResponse; 028 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest; 029 import org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportResponse; 030 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsRequest; 031 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterMetricsResponse; 032 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest; 033 import org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesResponse; 034 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationRequest; 035 import org.apache.hadoop.yarn.api.protocolrecords.GetNewApplicationResponse; 036 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest; 037 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoResponse; 038 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest; 039 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse; 040 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest; 041 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse; 042 import org.apache.hadoop.yarn.api.records.ApplicationId; 043 import org.apache.hadoop.yarn.api.records.ApplicationReport; 044 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext; 045 import org.apache.hadoop.yarn.api.records.NodeReport; 046 import org.apache.hadoop.yarn.api.records.Resource; 047 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics; 048 import org.apache.hadoop.yarn.exceptions.YarnRemoteException; 049 050 /** 051 * <p>The protocol between clients and the <code>ResourceManager</code> 052 * to submit/abort jobs and to get information on applications, cluster metrics, 053 * nodes, queues and ACLs.</p> 054 */ 055 @Public 056 @Stable 057 public interface ClientRMProtocol { 058 /** 059 * <p>The interface used by clients to obtain a new {@link ApplicationId} for 060 * submitting new applications.</p> 061 * 062 * <p>The <code>ResourceManager</code> responds with a new, monotonically 063 * increasing, {@link ApplicationId} which is used by the client to submit 064 * a new application.</p> 065 * 066 * <p>The <code>ResourceManager</code> also responds with details such 067 * as minimum and maximum resource capabilities in the cluster as specified in 068 * {@link GetNewApplicationResponse}.</p> 069 * 070 * @param request request to get a new <code>ApplicationId</code> 071 * @return new <code>ApplicationId</code> to be used to submit an application 072 * @throws YarnRemoteException 073 * @see #submitApplication(SubmitApplicationRequest) 074 */ 075 public GetNewApplicationResponse getNewApplication( 076 GetNewApplicationRequest request) 077 throws YarnRemoteException; 078 079 /** 080 * <p>The interface used by clients to submit a new application to the 081 * <code>ResourceManager.</code></p> 082 * 083 * <p>The client is required to provide details such as queue, 084 * {@link Resource} required to run the <code>ApplicationMaster</code>, 085 * the equivalent of {@link ContainerLaunchContext} for launching 086 * the <code>ApplicationMaster</code> etc. via the 087 * {@link SubmitApplicationRequest}.</p> 088 * 089 * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 090 * {@link SubmitApplicationResponse} on accepting the submission and throws 091 * an exception if it rejects the submission.</p> 092 * 093 * <p> In secure mode,the <code>ResourceManager</code> verifies access to 094 * queues etc. before accepting the application submission.</p> 095 * 096 * @param request request to submit a new application 097 * @return (empty) response on accepting the submission 098 * @throws YarnRemoteException 099 * @see #getNewApplication(GetNewApplicationRequest) 100 */ 101 public SubmitApplicationResponse submitApplication( 102 SubmitApplicationRequest request) 103 throws YarnRemoteException; 104 105 /** 106 * <p>The interface used by clients to request the 107 * <code>ResourceManager</code> to abort submitted application.</p> 108 * 109 * <p>The client, via {@link KillApplicationRequest} provides the 110 * {@link ApplicationId} of the application to be aborted.</p> 111 * 112 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 113 * application, queue etc. before terminating the application.</p> 114 * 115 * <p>Currently, the <code>ResourceManager</code> returns an empty response 116 * on success and throws an exception on rejecting the request.</p> 117 * 118 * @param request request to abort a submited application 119 * @return <code>ResourceManager</code> returns an empty response 120 * on success and throws an exception on rejecting the request 121 * @throws YarnRemoteException 122 * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 123 */ 124 public KillApplicationResponse forceKillApplication( 125 KillApplicationRequest request) 126 throws YarnRemoteException; 127 128 /** 129 * <p>The interface used by clients to get a report of an Application from 130 * the <code>ResourceManager</code>.</p> 131 * 132 * <p>The client, via {@link GetApplicationReportRequest} provides the 133 * {@link ApplicationId} of the application.</p> 134 * 135 * <p> In secure mode,the <code>ResourceManager</code> verifies access to the 136 * application, queue etc. before accepting the request.</p> 137 * 138 * <p>The <code>ResourceManager</code> responds with a 139 * {@link GetApplicationReportResponse} which includes the 140 * {@link ApplicationReport} for the application.</p> 141 * 142 * @param request request for an application report 143 * @return application report 144 * @throws YarnRemoteException 145 */ 146 public GetApplicationReportResponse getApplicationReport( 147 GetApplicationReportRequest request) 148 throws YarnRemoteException; 149 150 /** 151 * <p>The interface used by clients to get metrics about the cluster from 152 * the <code>ResourceManager</code>.</p> 153 * 154 * <p>The <code>ResourceManager</code> responds with a 155 * {@link GetClusterMetricsResponse} which includes the 156 * {@link YarnClusterMetrics} with details such as number of current 157 * nodes in the cluster.</p> 158 * 159 * @param request request for cluster metrics 160 * @return cluster metrics 161 * @throws YarnRemoteException 162 */ 163 public GetClusterMetricsResponse getClusterMetrics( 164 GetClusterMetricsRequest request) 165 throws YarnRemoteException; 166 167 /** 168 * <p>The interface used by clients to get a report of all Applications 169 * in the cluster from the <code>ResourceManager</code>.</p> 170 * 171 * <p>The <code>ResourceManager</code> responds with a 172 * {@link GetAllApplicationsResponse} which includes the 173 * {@link ApplicationReport} for all the applications.</p> 174 * 175 * @param request request for report on all running applications 176 * @return report on all running applications 177 * @throws YarnRemoteException 178 */ 179 public GetAllApplicationsResponse getAllApplications( 180 GetAllApplicationsRequest request) 181 throws YarnRemoteException; 182 183 /** 184 * <p>The interface used by clients to get a report of all nodes 185 * in the cluster from the <code>ResourceManager</code>.</p> 186 * 187 * <p>The <code>ResourceManager</code> responds with a 188 * {@link GetClusterNodesResponse} which includes the 189 * {@link NodeReport} for all the nodes in the cluster.</p> 190 * 191 * @param request request for report on all nodes 192 * @return report on all nodes 193 * @throws YarnRemoteException 194 */ 195 public GetClusterNodesResponse getClusterNodes( 196 GetClusterNodesRequest request) 197 throws YarnRemoteException; 198 199 /** 200 * <p>The interface used by clients to get information about <em>queues</em> 201 * from the <code>ResourceManager</code>.</p> 202 * 203 * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such 204 * as used/total resources, child queues, running applications etc.</p> 205 * 206 * <p> In secure mode,the <code>ResourceManager</code> verifies access before 207 * providing the information.</p> 208 * 209 * @param request request to get queue information 210 * @return queue information 211 * @throws YarnRemoteException 212 */ 213 public GetQueueInfoResponse getQueueInfo( 214 GetQueueInfoRequest request) 215 throws YarnRemoteException; 216 217 /** 218 * <p>The interface used by clients to get information about <em>queue 219 * acls</em> for <em>current users</em> from the <code>ResourceManager</code>. 220 * </p> 221 * 222 * <p>The <code>ResourceManager</code> responds with queue acls for all 223 * existing queues.</p> 224 * 225 * @param request request to get queue acls for <em>current user</em> 226 * @return queue acls for <em>current user</em> 227 * @throws YarnRemoteException 228 */ 229 public GetQueueUserAclsInfoResponse getQueueUserAcls( 230 GetQueueUserAclsInfoRequest request) 231 throws YarnRemoteException; 232 }