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}