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 021 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.Unstable; 027import org.apache.hadoop.fs.Path; 028import org.apache.hadoop.service.AbstractService; 029import org.apache.hadoop.yarn.api.records.ApplicationId; 030import org.apache.hadoop.yarn.client.api.impl.SharedCacheClientImpl; 031import org.apache.hadoop.yarn.exceptions.YarnException; 032 033/** 034 * This is the client for YARN's shared cache. 035 */ 036@Public 037@Unstable 038public abstract class SharedCacheClient extends AbstractService { 039 040 @Public 041 public static SharedCacheClient createSharedCacheClient() { 042 SharedCacheClient client = new SharedCacheClientImpl(); 043 return client; 044 } 045 046 @Private 047 public SharedCacheClient(String name) { 048 super(name); 049 } 050 051 /** 052 * <p> 053 * The method to claim a resource with the <code>SharedCacheManager.</code> 054 * The client uses a checksum to identify the resource and an 055 * {@link ApplicationId} to identify which application will be using the 056 * resource. 057 * </p> 058 * 059 * <p> 060 * The <code>SharedCacheManager</code> responds with whether or not the 061 * resource exists in the cache. If the resource exists, a <code>Path</code> 062 * to the resource in the shared cache is returned. If the resource does not 063 * exist, null is returned instead. 064 * </p> 065 * 066 * @param applicationId ApplicationId of the application using the resource 067 * @param resourceKey the key (i.e. checksum) that identifies the resource 068 * @return Path to the resource, or null if it does not exist 069 */ 070 @Public 071 @Unstable 072 public abstract Path use(ApplicationId applicationId, String resourceKey) 073 throws YarnException; 074 075 /** 076 * <p> 077 * The method to release a resource with the <code>SharedCacheManager.</code> 078 * This method is called once an application is no longer using a claimed 079 * resource in the shared cache. The client uses a checksum to identify the 080 * resource and an {@link ApplicationId} to identify which application is 081 * releasing the resource. 082 * </p> 083 * 084 * <p> 085 * Note: This method is an optimization and the client is not required to call 086 * it for correctness. 087 * </p> 088 * 089 * @param applicationId ApplicationId of the application releasing the 090 * resource 091 * @param resourceKey the key (i.e. checksum) that identifies the resource 092 */ 093 @Public 094 @Unstable 095 public abstract void release(ApplicationId applicationId, String resourceKey) 096 throws YarnException; 097 098 /** 099 * A convenience method to calculate the checksum of a specified file. 100 * 101 * @param sourceFile A path to the input file 102 * @return A hex string containing the checksum digest 103 * @throws IOException 104 */ 105 @Public 106 @Unstable 107 public abstract String getFileChecksum(Path sourceFile) throws IOException; 108}