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