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.client.api;
020
021import java.io.IOException;
022import java.util.List;
023
024import org.apache.hadoop.classification.InterfaceAudience;
025import org.apache.hadoop.classification.InterfaceAudience.Private;
026import org.apache.hadoop.classification.InterfaceAudience.Public;
027import org.apache.hadoop.classification.InterfaceStability;
028import org.apache.hadoop.service.AbstractService;
029import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
030import org.apache.hadoop.yarn.api.records.ApplicationAttemptReport;
031import org.apache.hadoop.yarn.api.records.ApplicationId;
032import org.apache.hadoop.yarn.api.records.ApplicationReport;
033import org.apache.hadoop.yarn.api.records.ContainerId;
034import org.apache.hadoop.yarn.api.records.ContainerReport;
035import org.apache.hadoop.yarn.client.api.impl.AHSClientImpl;
036import org.apache.hadoop.yarn.exceptions.ApplicationAttemptNotFoundException;
037import org.apache.hadoop.yarn.exceptions.ContainerNotFoundException;
038import org.apache.hadoop.yarn.exceptions.YarnException;
039
040@InterfaceAudience.Public
041@InterfaceStability.Stable
042public abstract class AHSClient extends AbstractService {
043
044  /**
045   * Create a new instance of AHSClient.
046   */
047  @Public
048  public static AHSClient createAHSClient() {
049    AHSClient client = new AHSClientImpl();
050    return client;
051  }
052
053  @Private
054  public AHSClient(String name) {
055    super(name);
056  }
057
058  /**
059   * Get a report of the given Application.
060   * <p>
061   * In secure mode, <code>YARN</code> verifies access to the application, queue
062   * etc. before accepting the request.
063   * <p>
064   * If the user does not have <code>VIEW_APP</code> access then the following
065   * fields in the report will be set to stubbed values:
066   * <ul>
067   *   <li>host - set to "N/A"</li>
068   *   <li>RPC port - set to -1</li>
069   *   <li>client token - set to "N/A"</li>
070   *   <li>diagnostics - set to "N/A"</li>
071   *   <li>tracking URL - set to "N/A"</li>
072   *   <li>original tracking URL - set to "N/A"</li>
073   *   <li>resource usage report - all values are -1</li>
074   * </ul>
075   * 
076   * @param appId
077   *          {@link ApplicationId} of the application that needs a report
078   * @return application report
079   * @throws YarnException
080   * @throws IOException
081   */
082  public abstract ApplicationReport getApplicationReport(ApplicationId appId)
083      throws YarnException, IOException;
084
085  /**
086   * <p>
087   * Get a report (ApplicationReport) of all Applications in the cluster.
088   * </p>
089   * 
090   * <p>
091   * If the user does not have <code>VIEW_APP</code> access for an application
092   * then the corresponding report will be filtered as described in
093   * {@link #getApplicationReport(ApplicationId)}.
094   * </p>
095   * 
096   * @return a list of reports for all applications
097   * @throws YarnException
098   * @throws IOException
099   */
100  public abstract List<ApplicationReport> getApplications()
101      throws YarnException, IOException;
102
103  /**
104   * <p>
105   * Get a report of the given ApplicationAttempt.
106   * </p>
107   * 
108   * <p>
109   * In secure mode, <code>YARN</code> verifies access to the application, queue
110   * etc. before accepting the request.
111   * </p>
112   * 
113   * @param applicationAttemptId
114   *          {@link ApplicationAttemptId} of the application attempt that needs
115   *          a report
116   * @return application attempt report
117   * @throws YarnException
118   * @throws ApplicationAttemptNotFoundException if application attempt
119   *         not found
120   * @throws IOException
121   */
122  public abstract ApplicationAttemptReport getApplicationAttemptReport(
123      ApplicationAttemptId applicationAttemptId) throws YarnException,
124      IOException;
125
126  /**
127   * <p>
128   * Get a report of all (ApplicationAttempts) of Application in the cluster.
129   * </p>
130   * 
131   * @param applicationId
132   * @return a list of reports for all application attempts for specified
133   *         application
134   * @throws YarnException
135   * @throws IOException
136   */
137  public abstract List<ApplicationAttemptReport> getApplicationAttempts(
138      ApplicationId applicationId) throws YarnException, IOException;
139
140  /**
141   * <p>
142   * Get a report of the given Container.
143   * </p>
144   * 
145   * <p>
146   * In secure mode, <code>YARN</code> verifies access to the application, queue
147   * etc. before accepting the request.
148   * </p>
149   * 
150   * @param containerId
151   *          {@link ContainerId} of the container that needs a report
152   * @return container report
153   * @throws YarnException
154   * @throws ContainerNotFoundException if container not found
155   * @throws IOException
156   */
157  public abstract ContainerReport getContainerReport(ContainerId containerId)
158      throws YarnException, IOException;
159
160  /**
161   * <p>
162   * Get a report of all (Containers) of ApplicationAttempt in the cluster.
163   * </p>
164   * 
165   * @param applicationAttemptId
166   * @return a list of reports of all containers for specified application
167   *         attempt
168   * @throws YarnException
169   * @throws IOException
170   */
171  public abstract List<ContainerReport> getContainers(
172      ApplicationAttemptId applicationAttemptId) throws YarnException,
173      IOException;
174}