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}