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