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.oozie.dependency; 020 021import java.net.URI; 022import java.util.List; 023import java.util.Set; 024 025import org.apache.hadoop.conf.Configuration; 026import org.apache.oozie.action.hadoop.LauncherURIHandler; 027 028public interface URIHandler { 029 030 /** 031 * Type of the dependency. PULL dependencies are those whose availability is determined by 032 * polling and PUSH dependencies are those whose availability is known from notifications 033 */ 034 enum DependencyType { 035 PULL, 036 PUSH; 037 } 038 039 /** 040 * Initialize the URIHandler 041 * 042 * @param conf Configuration for initialization 043 */ 044 void init(Configuration conf); 045 046 /** 047 * Get the list of uri schemes supported by this URIHandler 048 * 049 * @return supported list of uri schemes 050 */ 051 Set<String> getSupportedSchemes(); 052 053 /** 054 * Get the URIHandler that will be used to handle the supported schemes in launcher 055 * 056 * @return LauncherURIHandler that handles URI in the launcher 057 */ 058 Class<? extends LauncherURIHandler> getLauncherURIHandlerClass(); 059 060 /** 061 * Get list of classes to ship to launcher for LauncherURIHandler 062 * 063 * @return list of classes to ship to launcher 064 */ 065 List<Class<?>> getClassesForLauncher(); 066 067 /** 068 * Get the dependency type of the URI. When the availability of the 069 * URI is to be determined by polling the type is DependencyType.PULL, and 070 * when the availability is received through notifications from a external 071 * entity like a JMS server the type is DependencyType.PUSH 072 * 073 * @return dependency type of URI 074 */ 075 DependencyType getDependencyType(URI uri) throws URIHandlerException; 076 077 /** 078 * Register for notifications in case of a push dependency 079 * 080 * @param uri The URI to check for availability 081 * @param conf Configuration to access the URI 082 * @param user name of the user the URI should be accessed as 083 * @param actionID The id of action which depends on the availability of the uri 084 * 085 * @throws URIHandlerException 086 */ 087 void registerForNotification(URI uri, Configuration conf, String user, String actionID) 088 throws URIHandlerException; 089 090 /** 091 * Unregister from notifications in case of a push dependency 092 * 093 * @param uri The URI to be removed from missing dependency 094 * @param actionID The id of action which was dependent on the uri. 095 */ 096 boolean unregisterFromNotification(URI uri, String actionID); 097 098 /** 099 * Get the Context which can be used to access URI of the same scheme and 100 * host 101 * 102 * @param uri URI which identifies the scheme and host 103 * @param conf Configuration to access the URI 104 * @param user name of the user the URI should be accessed as 105 * @param readOnly indicate if operation is read-only 106 * @return Context to access URIs with same scheme and host 107 * 108 * @throws URIHandlerException 109 */ 110 Context getContext(URI uri, Configuration conf, String user, boolean readOnly) throws URIHandlerException; 111 112 /** 113 * Check if the dependency identified by the URI is available 114 * 115 * @param uri URI of the dependency 116 * @param context Context to access the URI 117 * 118 * @return <code>true</code> if the URI exists; <code>false</code> if the 119 * URI does not exist 120 * 121 * @throws URIHandlerException 122 */ 123 boolean exists(URI uri, Context context) throws URIHandlerException; 124 125 /** 126 * Check if the dependency identified by the URI is available 127 * 128 * @param uri URI of the dependency 129 * @param conf Configuration to access the URI 130 * @param user name of the user the URI should be accessed as. If null the 131 * logged in user is used. 132 * 133 * @return <code>true</code> if the URI exists; <code>false</code> if the 134 * URI does not exist 135 * 136 * @throws URIHandlerException 137 */ 138 boolean exists(URI uri, Configuration conf, String user) throws URIHandlerException; 139 140 /** 141 * Delete a URI 142 * 143 * @param uri URI 144 * @param context Context to access the URI 145 * @throws URIHandlerException 146 */ 147 void delete(URI uri, Context context) throws URIHandlerException; 148 149 /** 150 * Delete a URI 151 * 152 * @param uri URI 153 * @param conf Configuration to access the URI 154 * @param user name of the user the URI should be accessed as 155 * @throws URIHandlerException 156 */ 157 void delete(URI uri, Configuration conf, String user) throws URIHandlerException; 158 159 /** 160 * Get the URI based on the done flag 161 * 162 * @param uri URI of the dependency 163 * @param doneFlag flag that determines URI availability 164 * 165 * @return the final URI with the doneFlag incorporated 166 * 167 * @throws URIHandlerException 168 */ 169 String getURIWithDoneFlag(String uri, String doneFlag) throws URIHandlerException; 170 171 /** 172 * Get the URI path from path which has done flag 173 * 174 * @param uri URI of the dependency 175 * @param doneFlag flag that determines URI availability 176 * 177 * @return the final URI without the doneFlag incorporated 178 * 179 * @throws URIHandlerException 180 */ 181 String getURIWithoutDoneFlag(String uri, String doneFlag) throws URIHandlerException; 182 183 184 /** 185 * Check whether the URI is valid or not 186 * @param uri 187 * @throws URIHandlerException 188 */ 189 void validate(String uri) throws URIHandlerException; 190 191 /** 192 * Destroy the URIHandler 193 */ 194 void destroy(); 195 196 public static abstract class Context { 197 198 private Configuration conf; 199 private String user; 200 201 /** 202 * Create a Context that can be used to access a URI 203 * 204 * @param conf Configuration to access the URI 205 * @param user name of the user the URI should be accessed as 206 */ 207 public Context(Configuration conf, String user) { 208 this.conf = conf; 209 this.user = user; 210 } 211 212 /** 213 * Get the Configuration to access the URI 214 * @return Configuration to access the URI 215 */ 216 public Configuration getConfiguration() { 217 return conf; 218 } 219 220 /** 221 * Get the name of the user the URI will be accessed as 222 * @return the user name the URI will be accessed as 223 */ 224 public String getUser() { 225 return user; 226 } 227 228 /** 229 * Destroy the Context 230 */ 231 public void destroy() { 232 } 233 234 } 235 236 237}