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    }