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
019package org.apache.hadoop.yarn.api.protocolrecords;
020
021import org.apache.hadoop.classification.InterfaceAudience.Public;
022import org.apache.hadoop.classification.InterfaceStability.Stable;
023import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
024import 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
042public 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}