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