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}