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.Flushable;
022import java.io.IOException;
023
024import org.apache.hadoop.classification.InterfaceAudience.Private;
025import org.apache.hadoop.classification.InterfaceAudience.Public;
026import org.apache.hadoop.classification.InterfaceStability.Evolving;
027import org.apache.hadoop.security.UserGroupInformation;
028import org.apache.hadoop.security.token.Token;
029import org.apache.hadoop.service.AbstractService;
030import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
031import org.apache.hadoop.yarn.api.records.timeline.TimelineEntity;
032import org.apache.hadoop.yarn.api.records.timeline.TimelineDomain;
033import org.apache.hadoop.yarn.api.records.timeline.TimelineEntityGroupId;
034import org.apache.hadoop.yarn.api.records.timeline.TimelinePutResponse;
035import org.apache.hadoop.yarn.client.api.impl.TimelineClientImpl;
036import org.apache.hadoop.yarn.exceptions.YarnException;
037import org.apache.hadoop.yarn.security.client.TimelineDelegationTokenIdentifier;
038
039/**
040 * A client library that can be used to post some information in terms of a
041 * number of conceptual entities.
042 */
043@Public
044@Evolving
045public abstract class TimelineClient extends AbstractService implements
046    Flushable {
047
048  /**
049   * Create a timeline client. The current UGI when the user initialize the
050   * client will be used to do the put and the delegation token operations. The
051   * current user may use {@link UserGroupInformation#doAs} another user to
052   * construct and initialize a timeline client if the following operations are
053   * supposed to be conducted by that user.
054   *
055   * @return a timeline client
056   */
057  @Public
058  public static TimelineClient createTimelineClient() {
059    TimelineClient client = new TimelineClientImpl();
060    return client;
061  }
062
063  @Private
064  protected TimelineClient(String name) {
065    super(name);
066  }
067
068  /**
069   * <p>
070   * Send the information of a number of conceptual entities to the timeline
071   * server. It is a blocking API. The method will not return until it gets the
072   * response from the timeline server.
073   * </p>
074   * 
075   * @param entities
076   *          the collection of {@link TimelineEntity}
077   * @return the error information if the sent entities are not correctly stored
078   * @throws IOException
079   * @throws YarnException
080   */
081  @Public
082  public abstract TimelinePutResponse putEntities(
083      TimelineEntity... entities) throws IOException, YarnException;
084
085  /**
086   * <p>
087   * Send the information of a number of conceptual entities to the timeline
088   * server. It is a blocking API. The method will not return until it gets the
089   * response from the timeline server.
090   *
091   * This API is only for timeline service v1.5
092   * </p>
093   *
094   * @param appAttemptId {@link ApplicationAttemptId}
095   * @param groupId {@link TimelineEntityGroupId}
096   * @param entities
097   *          the collection of {@link TimelineEntity}
098   * @return the error information if the sent entities are not correctly stored
099   * @throws IOException
100   * @throws YarnException
101   */
102  @Public
103  public abstract TimelinePutResponse putEntities(
104      ApplicationAttemptId appAttemptId, TimelineEntityGroupId groupId,
105      TimelineEntity... entities) throws IOException, YarnException;
106
107  /**
108   * <p>
109   * Send the information of a domain to the timeline server. It is a
110   * blocking API. The method will not return until it gets the response from
111   * the timeline server.
112   * </p>
113   * 
114   * @param domain
115   *          an {@link TimelineDomain} object
116   * @throws IOException
117   * @throws YarnException
118   */
119  @Public
120  public abstract void putDomain(
121      TimelineDomain domain) throws IOException, YarnException;
122
123  /**
124   * <p>
125   * Send the information of a domain to the timeline server. It is a
126   * blocking API. The method will not return until it gets the response from
127   * the timeline server.
128   *
129   * This API is only for timeline service v1.5
130   * </p>
131   *
132   * @param domain
133   *          an {@link TimelineDomain} object
134   * @param appAttemptId {@link ApplicationAttemptId}
135   * @throws IOException
136   * @throws YarnException
137   */
138  @Public
139  public abstract void putDomain(ApplicationAttemptId appAttemptId,
140      TimelineDomain domain) throws IOException, YarnException;
141
142  /**
143   * <p>
144   * Get a delegation token so as to be able to talk to the timeline server in a
145   * secure way.
146   * </p>
147   * 
148   * @param renewer
149   *          Address of the renewer who can renew these tokens when needed by
150   *          securely talking to the timeline server
151   * @return a delegation token ({@link Token}) that can be used to talk to the
152   *         timeline server
153   * @throws IOException
154   * @throws YarnException
155   */
156  @Public
157  public abstract Token<TimelineDelegationTokenIdentifier> getDelegationToken(
158      String renewer) throws IOException, YarnException;
159
160  /**
161   * <p>
162   * Renew a timeline delegation token.
163   * </p>
164   * 
165   * @param timelineDT
166   *          the delegation token to renew
167   * @return the new expiration time
168   * @throws IOException
169   * @throws YarnException
170   */
171  @Public
172  public abstract long renewDelegationToken(
173      Token<TimelineDelegationTokenIdentifier> timelineDT)
174          throws IOException, YarnException;
175
176  /**
177   * <p>
178   * Cancel a timeline delegation token.
179   * </p>
180   * 
181   * @param timelineDT
182   *          the delegation token to cancel
183   * @throws IOException
184   * @throws YarnException
185   */
186  @Public
187  public abstract void cancelDelegationToken(
188      Token<TimelineDelegationTokenIdentifier> timelineDT)
189          throws IOException, YarnException;
190}