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
023 import org.apache.hadoop.classification.InterfaceAudience.Private;
024 import org.apache.hadoop.classification.InterfaceAudience.Public;
025 import org.apache.hadoop.classification.InterfaceStability.Unstable;
026 import org.apache.hadoop.security.token.Token;
027 import org.apache.hadoop.service.AbstractService;
028 import org.apache.hadoop.yarn.api.records.timeline.TimelineEntity;
029 import org.apache.hadoop.yarn.api.records.timeline.TimelineDomain;
030 import org.apache.hadoop.yarn.api.records.timeline.TimelinePutResponse;
031 import org.apache.hadoop.yarn.client.api.impl.TimelineClientImpl;
032 import org.apache.hadoop.yarn.exceptions.YarnException;
033 import 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
041 public 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 }