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 * @param uri the URI to get the dependency type from 074 * @return dependency type of URI 075 * @throws URIHandlerException in case of error 076 */ 077 DependencyType getDependencyType(URI uri) throws URIHandlerException; 078 079 /** 080 * Register for notifications in case of a push dependency 081 * 082 * @param uri The URI to check for availability 083 * @param conf Configuration to access the URI 084 * @param user name of the user the URI should be accessed as 085 * @param actionID The id of action which depends on the availability of the uri 086 * 087 * @throws URIHandlerException in case of error 088 */ 089 void registerForNotification(URI uri, Configuration conf, String user, String actionID) 090 throws URIHandlerException; 091 092 /** 093 * Unregister from notifications in case of a push dependency 094 * 095 * @param uri The URI to be removed from missing dependency 096 * @param actionID The id of action which was dependent on the uri. 097 */ 098 boolean unregisterFromNotification(URI uri, String actionID); 099 100 /** 101 * Get the Context which can be used to access URI of the same scheme and 102 * host 103 * 104 * @param uri URI which identifies the scheme and host 105 * @param conf Configuration to access the URI 106 * @param user name of the user the URI should be accessed as 107 * @param readOnly indicate if operation is read-only 108 * @return Context to access URIs with same scheme and host 109 * 110 * @throws URIHandlerException in case of error 111 */ 112 Context getContext(URI uri, Configuration conf, String user, boolean readOnly) throws URIHandlerException; 113 114 /** 115 * Check if the dependency identified by the URI is available 116 * 117 * @param uri URI of the dependency 118 * @param context Context to access the URI 119 * 120 * @return <code>true</code> if the URI exists; <code>false</code> if the 121 * URI does not exist 122 * 123 * @throws URIHandlerException in case of error 124 */ 125 boolean exists(URI uri, Context context) throws URIHandlerException; 126 127 /** 128 * Check if the dependency identified by the URI is available 129 * 130 * @param uri URI of the dependency 131 * @param conf Configuration to access the URI 132 * @param user name of the user the URI should be accessed as. If null the 133 * logged in user is used. 134 * 135 * @return <code>true</code> if the URI exists; <code>false</code> if the 136 * URI does not exist 137 * 138 * @throws URIHandlerException in case of error 139 */ 140 boolean exists(URI uri, Configuration conf, String user) throws URIHandlerException; 141 142 /** 143 * Delete a URI 144 * 145 * @param uri URI 146 * @param context Context to access the URI 147 * @throws URIHandlerException in case of error 148 */ 149 void delete(URI uri, Context context) throws URIHandlerException; 150 151 /** 152 * Delete a URI 153 * 154 * @param uri URI 155 * @param conf Configuration to access the URI 156 * @param user name of the user the URI should be accessed as 157 * @throws URIHandlerException in case of error 158 */ 159 void delete(URI uri, Configuration conf, String user) throws URIHandlerException; 160 161 /** 162 * Get the URI based on the done flag 163 * 164 * @param uri URI of the dependency 165 * @param doneFlag flag that determines URI availability 166 * 167 * @return the final URI with the doneFlag incorporated 168 * 169 * @throws URIHandlerException in case of error 170 */ 171 String getURIWithDoneFlag(String uri, String doneFlag) throws URIHandlerException; 172 173 /** 174 * Get the URI path from path which has done flag 175 * 176 * @param uri URI of the dependency 177 * @param doneFlag flag that determines URI availability 178 * 179 * @return the final URI without the doneFlag incorporated 180 * 181 * @throws URIHandlerException in case of error 182 */ 183 String getURIWithoutDoneFlag(String uri, String doneFlag) throws URIHandlerException; 184 185 186 /** 187 * Check whether the URI is valid or not 188 * @param uri the uri 189 * @throws URIHandlerException if the uri is not valid 190 */ 191 void validate(String uri) throws URIHandlerException; 192 193 /** 194 * Destroy the URIHandler 195 */ 196 void destroy(); 197 198 public static abstract class Context { 199 200 private Configuration conf; 201 private String user; 202 203 /** 204 * Create a Context that can be used to access a URI 205 * 206 * @param conf Configuration to access the URI 207 * @param user name of the user the URI should be accessed as 208 */ 209 public Context(Configuration conf, String user) { 210 this.conf = conf; 211 this.user = user; 212 } 213 214 /** 215 * Get the Configuration to access the URI 216 * @return Configuration to access the URI 217 */ 218 public Configuration getConfiguration() { 219 return conf; 220 } 221 222 /** 223 * Get the name of the user the URI will be accessed as 224 * @return the user name the URI will be accessed as 225 */ 226 public String getUser() { 227 return user; 228 } 229 230 /** 231 * Destroy the Context 232 */ 233 public void destroy() { 234 } 235 236 } 237 238 239}