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.protocolrecords;
020    
021    import org.apache.hadoop.classification.InterfaceAudience.Public;
022    import org.apache.hadoop.classification.InterfaceStability.Stable;
023    import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
024    import org.apache.hadoop.yarn.util.Records;
025    
026    /**
027     * <p>The request sent by the <code>ApplicationMaster</code> to 
028     * <code>ResourceManager</code> on registration.</p>
029     * 
030     * <p>The registration includes details such as:
031     *   <ul>
032     *     <li>Hostname on which the AM is running.</li>
033     *     <li>RPC Port</li>
034     *     <li>Tracking URL</li>
035     *   </ul>
036     * </p>
037     * 
038     * @see ApplicationMasterProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)
039     */
040    @Public
041    @Stable
042    public abstract class RegisterApplicationMasterRequest {
043    
044      /**
045       * Create a new instance of <code>RegisterApplicationMasterRequest</code>.
046       * If <em>port, trackingUrl</em> is not used, use the following default value:
047       * <ul>
048       *  <li>port: -1</li>
049       *  <li>trackingUrl: null</li>
050       * </ul>
051       * The port is allowed to be any integer larger than or equal to -1.
052       * @return the new instance of <code>RegisterApplicationMasterRequest</code>
053       */
054      @Public
055      @Stable
056      public static RegisterApplicationMasterRequest newInstance(String host,
057          int port, String trackingUrl) {
058        RegisterApplicationMasterRequest request =
059            Records.newRecord(RegisterApplicationMasterRequest.class);
060        request.setHost(host);
061        request.setRpcPort(port);
062        request.setTrackingUrl(trackingUrl);
063        return request;
064      }
065    
066      /**
067       * Get the <em>host</em> on which the <code>ApplicationMaster</code> is 
068       * running.
069       * @return <em>host</em> on which the <code>ApplicationMaster</code> is running
070       */
071      @Public
072      @Stable
073      public abstract String getHost();
074      
075      /**
076       * Set the <em>host</em> on which the <code>ApplicationMaster</code> is 
077       * running.
078       * @param host <em>host</em> on which the <code>ApplicationMaster</code> 
079       *             is running
080       */
081      @Public
082      @Stable
083      public abstract void setHost(String host);
084    
085      /**
086       * Get the <em>RPC port</em> on which the <code>ApplicationMaster</code> 
087       * is responding. 
088       * @return the <em>RPC port<em> on which the <code>ApplicationMaster</code> is 
089       *         responding
090       */
091      @Public
092      @Stable
093      public abstract int getRpcPort();
094      
095      /**
096       * Set the <em>RPC port<em> on which the <code>ApplicationMaster</code> is 
097       * responding.
098       * @param port <em>RPC port<em> on which the <code>ApplicationMaster</code> is 
099       *             responding
100       */
101      @Public
102      @Stable
103      public abstract void setRpcPort(int port);
104    
105      /**
106       * Get the <em>tracking URL</em> for the <code>ApplicationMaster</code>.
107       * This url if contains scheme then that will be used by resource manager
108       * web application proxy otherwise it will default to http.
109       * @return <em>tracking URL</em> for the <code>ApplicationMaster</code>
110       */
111      @Public
112      @Stable
113      public abstract String getTrackingUrl();
114      
115      /**
116       * Set the <em>tracking URL</em>for the <code>ApplicationMaster</code> while
117       * it is running. This is the web-URL to which ResourceManager or
118       * web-application proxy will redirect client/users while the application and
119       * the <code>ApplicationMaster</code> are still running.
120       * <p>
121       * If the passed url has a scheme then that will be used by the
122       * ResourceManager and web-application proxy, otherwise the scheme will
123       * default to http.
124       * </p>
125       * <p>
126       * Empty, null, "N/A" strings are all valid besides a real URL. In case an url
127       * isn't explicitly passed, it defaults to "N/A" on the ResourceManager.
128       * <p>
129       *
130       * @param trackingUrl
131       *          <em>tracking URL</em>for the <code>ApplicationMaster</code>
132       */
133      @Public
134      @Stable
135      public abstract void setTrackingUrl(String trackingUrl);
136    }