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 }