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