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.ApplicationId;
032import org.apache.hadoop.yarn.api.records.timeline.TimelineDomain;
033import org.apache.hadoop.yarn.api.records.timeline.TimelineEntity;
034import org.apache.hadoop.yarn.api.records.timeline.TimelineEntityGroupId;
035import org.apache.hadoop.yarn.api.records.timeline.TimelinePutResponse;
036import org.apache.hadoop.yarn.client.api.impl.TimelineClientImpl;
037import org.apache.hadoop.yarn.exceptions.YarnException;
038import org.apache.hadoop.yarn.security.client.TimelineDelegationTokenIdentifier;
039
040/**
041 * A client library that can be used to post some information in terms of a
042 * number of conceptual entities.
043 */
044@Public
045@Evolving
046public abstract class TimelineClient extends AbstractService implements
047    Flushable {
048
049  /**
050   * Create a timeline client. The current UGI when the user initialize the
051   * client will be used to do the put and the delegation token operations. The
052   * current user may use {@link UserGroupInformation#doAs} another user to
053   * construct and initialize a timeline client if the following operations are
054   * supposed to be conducted by that user.
055   */
056  private ApplicationId contextAppId;
057
058  /**
059   * Creates an instance of the timeline v.1.x client.
060   *
061   * @return the created timeline client instance
062   */
063  @Public
064  public static TimelineClient createTimelineClient() {
065    TimelineClient client = new TimelineClientImpl();
066    return client;
067  }
068
069  /**
070   * Creates an instance of the timeline v.2 client.
071   *
072   * @param appId the application id with which the timeline client is
073   * associated
074   * @return the created timeline client instance
075   */
076  @Public
077  public static TimelineClient createTimelineClient(ApplicationId appId) {
078    TimelineClient client = new TimelineClientImpl(appId);
079    return client;
080  }
081
082  @Private
083  protected TimelineClient(String name, ApplicationId appId) {
084    super(name);
085    setContextAppId(appId);
086  }
087
088  /**
089   * <p>
090   * Send the information of a number of conceptual entities to the timeline
091   * server. It is a blocking API. The method will not return until it gets the
092   * response from the timeline server.
093   * </p>
094   * 
095   * @param entities
096   *          the collection of {@link TimelineEntity}
097   * @return the error information if the sent entities are not correctly stored
098   * @throws IOException if there are I/O errors
099   * @throws YarnException if entities are incomplete/invalid
100   */
101  @Public
102  public abstract TimelinePutResponse putEntities(
103      TimelineEntity... entities) throws IOException, YarnException;
104
105  /**
106   * <p>
107   * Send the information of a number of conceptual entities to the timeline
108   * server. It is a blocking API. The method will not return until it gets the
109   * response from the timeline server.
110   *
111   * This API is only for timeline service v1.5
112   * </p>
113   *
114   * @param appAttemptId {@link ApplicationAttemptId}
115   * @param groupId {@link TimelineEntityGroupId}
116   * @param entities
117   *          the collection of {@link TimelineEntity}
118   * @return the error information if the sent entities are not correctly stored
119   * @throws IOException if there are I/O errors
120   * @throws YarnException if entities are incomplete/invalid
121   */
122  @Public
123  public abstract TimelinePutResponse putEntities(
124      ApplicationAttemptId appAttemptId, TimelineEntityGroupId groupId,
125      TimelineEntity... entities) throws IOException, YarnException;
126
127  /**
128   * <p>
129   * Send the information of a domain to the timeline server. It is a
130   * blocking API. The method will not return until it gets the response from
131   * the timeline server.
132   * </p>
133   * 
134   * @param domain
135   *          an {@link TimelineDomain} object
136   * @throws IOException
137   * @throws YarnException
138   */
139  @Public
140  public abstract void putDomain(
141      TimelineDomain domain) throws IOException, YarnException;
142
143  /**
144   * <p>
145   * Send the information of a domain to the timeline server. It is a
146   * blocking API. The method will not return until it gets the response from
147   * the timeline server.
148   *
149   * This API is only for timeline service v1.5
150   * </p>
151   *
152   * @param domain
153   *          an {@link TimelineDomain} object
154   * @param appAttemptId {@link ApplicationAttemptId}
155   * @throws IOException
156   * @throws YarnException
157   */
158  @Public
159  public abstract void putDomain(ApplicationAttemptId appAttemptId,
160      TimelineDomain domain) throws IOException, YarnException;
161
162  /**
163   * <p>
164   * Get a delegation token so as to be able to talk to the timeline server in a
165   * secure way.
166   * </p>
167   * 
168   * @param renewer
169   *          Address of the renewer who can renew these tokens when needed by
170   *          securely talking to the timeline server
171   * @return a delegation token ({@link Token}) that can be used to talk to the
172   *         timeline server
173   * @throws IOException
174   * @throws YarnException
175   */
176  @Public
177  public abstract Token<TimelineDelegationTokenIdentifier> getDelegationToken(
178      String renewer) throws IOException, YarnException;
179
180  /**
181   * <p>
182   * Renew a timeline delegation token.
183   * </p>
184   * 
185   * @param timelineDT
186   *          the delegation token to renew
187   * @return the new expiration time
188   * @throws IOException
189   * @throws YarnException
190   */
191  @Public
192  public abstract long renewDelegationToken(
193      Token<TimelineDelegationTokenIdentifier> timelineDT)
194          throws IOException, YarnException;
195
196  /**
197   * <p>
198   * Cancel a timeline delegation token.
199   * </p>
200   * 
201   * @param timelineDT
202   *          the delegation token to cancel
203   * @throws IOException
204   * @throws YarnException
205   */
206  @Public
207  public abstract void cancelDelegationToken(
208      Token<TimelineDelegationTokenIdentifier> timelineDT)
209          throws IOException, YarnException;
210
211  /**
212   * <p>
213   * Send the information of a number of conceptual entities to the timeline
214   * service v.2 collector. It is a blocking API. The method will not return
215   * until all the put entities have been persisted. If this method is invoked
216   * for a non-v.2 timeline client instance, a YarnException is thrown.
217   * </p>
218   *
219   * @param entities the collection of {@link
220   * org.apache.hadoop.yarn.api.records.timelineservice.TimelineEntity}
221   * @throws IOException
222   * @throws YarnException
223   */
224  @Public
225  public abstract void putEntities(
226      org.apache.hadoop.yarn.api.records.timelineservice.TimelineEntity...
227          entities) throws IOException, YarnException;
228
229  /**
230   * <p>
231   * Send the information of a number of conceptual entities to the timeline
232   * service v.2 collector. It is an asynchronous API. The method will return
233   * once all the entities are received. If this method is invoked for a
234   * non-v.2 timeline client instance, a YarnException is thrown.
235   * </p>
236   *
237   * @param entities the collection of {@link
238   * org.apache.hadoop.yarn.api.records.timelineservice.TimelineEntity}
239   * @throws IOException
240   * @throws YarnException
241   */
242  @Public
243  public abstract void putEntitiesAsync(
244      org.apache.hadoop.yarn.api.records.timelineservice.TimelineEntity...
245          entities) throws IOException, YarnException;
246
247  /**
248   * <p>
249   * Update the timeline service address where the request will be sent to.
250   * </p>
251   * @param address
252   *          the timeline service address
253   */
254  public abstract void setTimelineServiceAddress(String address);
255
256  protected ApplicationId getContextAppId() {
257    return contextAppId;
258  }
259
260  protected void setContextAppId(ApplicationId appId) {
261    this.contextAppId = appId;
262  }
263}