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