001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.camel;
018    
019    import java.util.Collection;
020    import java.util.List;
021    import java.util.Map;
022    import java.util.concurrent.Callable;
023    
024    import org.apache.camel.builder.ErrorHandlerBuilder;
025    import org.apache.camel.model.RouteDefinition;
026    import org.apache.camel.model.dataformat.DataFormatDefinition;
027    import org.apache.camel.spi.ClassResolver;
028    import org.apache.camel.spi.ExchangeConverter;
029    import org.apache.camel.spi.Injector;
030    import org.apache.camel.spi.InterceptStrategy;
031    import org.apache.camel.spi.Language;
032    import org.apache.camel.spi.LifecycleStrategy;
033    import org.apache.camel.spi.PackageScanClassResolver;
034    import org.apache.camel.spi.Registry;
035    import org.apache.camel.spi.TypeConverterRegistry;
036    import org.apache.camel.util.FactoryFinder;
037    
038    /**
039     * Interface used to represent the context used to configure routes and the
040     * policies to use during message exchanges between endpoints.
041     *
042     * @version $Revision: 752893 $
043     */
044    public interface CamelContext extends Service {
045    
046        /**
047         * Gets the name of the this context.
048         *
049         * @return the name
050         */
051        String getName();
052    
053        // Component Management Methods
054        //-----------------------------------------------------------------------
055    
056        /**
057         * Adds a component to the context.
058         *
059         * @param componentName  the name the component is registered as
060         * @param component      the component
061         */
062        void addComponent(String componentName, Component component);
063    
064        /**
065         * Gets a component from the context by name.
066         *
067         * @param componentName the name of the component
068         * @return the component
069         */
070        Component getComponent(String componentName);
071    
072        /**
073         * Gets a component from the context by name and specifying the expected type of component.
074         *
075         * @param name  the name to lookup
076         * @param componentType  the expected type
077         * @return the component
078         */
079        <T extends Component> T getComponent(String name, Class<T> componentType);
080    
081        /**
082         * Gets a readonly list of names of the components currently registered
083         *
084         * @return a readonly list with the names of the the componens.
085         */
086        List<String> getComponentNames();
087    
088        /**
089         * Removes a previously added component.
090         *
091         * @param componentName the component name to remove
092         * @return the previously added component or null if it had not been previously added.
093         */
094        Component removeComponent(String componentName);
095    
096        /**
097         * Gets the a previously added component by name or lazily creates the component
098         * using the factory Callback.
099         *
100         * @param componentName the name of the component
101         * @param factory       used to create a new component instance if the component was not previously added.
102         * @return the component
103         */
104        Component getOrCreateComponent(String componentName, Callable<Component> factory);
105    
106        // Endpoint Management Methods
107        //-----------------------------------------------------------------------
108    
109        /**
110         * Resolves the given URI to an {@link Endpoint}.  If the URI has a singleton endpoint
111         * registered, then the singleton is returned.  Otherwise, a new {@link Endpoint} is created
112         * and if the endpoint is a singleton it is registered as a singleton endpoint.
113         *
114         * @param uri  the URI of the endpoint
115         * @return  the endpoint
116         */
117        Endpoint getEndpoint(String uri);
118    
119        /**
120         * Resolves the given name to an {@link Endpoint} of the specified type.
121         * If the name has a singleton endpoint registered, then the singleton is returned.
122         * Otherwise, a new {@link Endpoint} is created and if the endpoint is a
123         * singleton it is registered as a singleton endpoint.
124         *
125         * @param name  the name of the endpoint
126         * @param endpointType  the expected type
127         * @return the endpoint
128         */
129        <T extends Endpoint> T getEndpoint(String name, Class<T> endpointType);
130    
131        /**
132         * Returns the collection of all registered endpoints.
133         *
134         * @return  all endpoints
135         */
136        Collection<Endpoint> getEndpoints();
137    
138        /**
139         * Returns a new Map containing all of the active endpoints with the key of the map being their
140         * unique key.
141         *
142         * @return map of active endpoints
143         */
144        Map<String, Endpoint> getEndpointMap();
145    
146        /**
147         * Returns the collection of all registered endpoints for a uri or an empty collection.
148         * For a singleton endpoint the collection will contain exactly one element.
149         *
150         * @param uri  the URI of the endpoints
151         * @return  collection of endpoints
152         */
153        Collection<Endpoint> getEndpoints(String uri);
154    
155        /**
156         * Returns the collection of all registered singleton endpoints.
157         *
158         * @return  all the singleton endpoints
159         */
160        Collection<Endpoint> getSingletonEndpoints();
161    
162        /**
163         * Adds the endpoint to the context using the given URI.
164         *
165         * @param uri the URI to be used to resolve this endpoint
166         * @param endpoint the endpoint to be added to the context
167         * @return the old endpoint that was previously registered to the context if 
168         * there was already an singleton endpoint for that URI or null
169         * @throws Exception if the new endpoint could not be started or the old 
170         * singleton endpoint could not be stopped
171         */
172        Endpoint addEndpoint(String uri, Endpoint endpoint) throws Exception;
173    
174        /**
175         * Removes all endpoints with the given URI
176         *
177         * @param uri the URI to be used to remove
178         * @return a collection of endpoints removed or null if there are no endpoints for this URI
179         * @throws Exception if at least one endpoint could not be stopped
180         */
181        Collection<Endpoint> removeEndpoints(String uri) throws Exception;
182    
183        // Route Management Methods
184        //-----------------------------------------------------------------------
185    
186        /**
187         * Returns a list of the current route definitions
188         *
189         * @return list of the current route definitions
190         */
191        List<RouteDefinition> getRouteDefinitions();
192    
193        /**
194         * Returns the current routes in this context
195         *
196         * @return the current routes
197         */
198        List<Route> getRoutes();
199    
200        /**
201         * Adds a collection of routes to this context using the given builder
202         * to build them
203         *
204         * @param builder the builder which will create the routes and add them to this context
205         * @throws Exception if the routes could not be created for whatever reason
206         */
207        void addRoutes(Routes builder) throws Exception;
208    
209        /**
210         * Adds a collection of route definitions to the context
211         *
212         * @param routeDefinitions the route definitions to add
213         * @throws Exception if the route definition could not be created for whatever reason
214         */
215        void addRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
216    
217        /**
218         * Removes a collection of route definitions from the context - stopping any previously running
219         * routes if any of them are actively running
220         */
221        void removeRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
222    
223        /**
224         * Starts the given route if it has been previously stopped
225         */
226        void startRoute(RouteDefinition route) throws Exception;
227    
228        /**
229         * Stops the given route. It will remain in the list of route definitions return by {@link #getRouteDefinitions()}
230         * unless you use the {@link #removeRouteDefinitions(java.util.Collection)}
231         */
232        void stopRoute(RouteDefinition route) throws Exception;
233    
234    
235        // Properties
236        //-----------------------------------------------------------------------
237    
238        /**
239         * Returns the converter of exchanges from one type to another
240         *
241         * @return the converter
242         */
243        ExchangeConverter getExchangeConverter();
244    
245        /**
246         * Returns the type converter used to coerce types from one type to another
247         *
248         * @return the converter
249         */
250        TypeConverter getTypeConverter();
251    
252        /**
253         * Returns the type converter registry where type converters can be added or looked up
254         *
255         * @return the type converter registry
256         */
257        TypeConverterRegistry getTypeConverterRegistry();
258    
259        /**
260         * Returns the registry used to lookup components by name and type such as the Spring ApplicationContext,
261         * JNDI or the OSGi Service Registry
262         *
263         * @return the registry
264         */
265        Registry getRegistry();
266    
267        /**
268         * Returns the injector used to instantiate objects by type
269         *
270         * @return the injector
271         */
272        Injector getInjector();
273    
274        /**
275         * Returns the lifecycle strategy used to handle lifecycle notification
276         *
277         * @return the lifecycle strategy
278         */
279        LifecycleStrategy getLifecycleStrategy();
280    
281        /**
282         * Resolves a language for creating expressions
283         *
284         * @param language  name of the language
285         * @return the resolved language
286         */
287        Language resolveLanguage(String language);
288    
289        /**
290         * Gets a readonly list with the names of the languages currently registered.
291         *
292         * @return a readonly list with the names of the the languages. 
293         */
294        List<String> getLanguageNames();
295    
296        /**
297         * Creates a new ProducerTemplate.
298         * <p/>
299         * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
300         * Why does Camel use too many threads with ProducerTemplate?</a>
301         *
302         * @return the template
303         */
304        ProducerTemplate createProducerTemplate();
305    
306        /**
307         * Adds the given interceptor strategy
308         *
309         * @param interceptStrategy the strategy
310         */
311        void addInterceptStrategy(InterceptStrategy interceptStrategy);
312    
313        /**
314         * Gets the interceptor strategies
315         *
316         * @return the list of current interceptor strategies
317         */
318        List<InterceptStrategy> getInterceptStrategies();
319    
320        /**
321         * Gets the default error handler builder which is inherited by the routes
322         *
323         * @return the builder
324         */
325        ErrorHandlerBuilder getErrorHandlerBuilder();
326    
327        /**
328         * Sets the default error handler builder which is inherited by the routes
329         *
330         * @param errorHandlerBuilder  the builder
331         */
332        void setErrorHandlerBuilder(ErrorHandlerBuilder errorHandlerBuilder);
333    
334        /**
335         * Sets the data formats that can be referenced in the routes.
336         * @param dataFormats the data formats
337         */
338        void setDataFormats(Map<String, DataFormatDefinition> dataFormats);
339    
340        /**
341         * Gets the data formats that can be referenced in the routes.
342         *
343         * @return the data formats available
344         */
345        Map<String, DataFormatDefinition> getDataFormats();
346        
347        /**
348         * Sets the properties that can be referenced in the camel context
349         */
350        void setProperties(Map<String, String> properties);
351        
352        /**
353         * Gets the properties that can be referenced in the camel context
354         */
355        Map<String, String> getProperties();
356        
357        /**
358         * Create a FactoryFinder which will be used for the loading the factory class from META-INF
359         * @return the factory finder
360         */
361        FactoryFinder createFactoryFinder();
362        
363        /**
364         * Create a FactoryFinder which will be used for the loading the factory class from META-INF
365         * @param path the META-INF path
366         * @return the factory finder
367         */
368        FactoryFinder createFactoryFinder(String path);
369    
370        /**
371         * Returns the current status of the given route
372         */
373        ServiceStatus getRouteStatus(RouteDefinition route);
374    
375        /**
376         * Returns the class resolver to be used for loading/lookup of classes.
377         */
378        ClassResolver getClassResolver();
379    
380        /**
381         * Returns the package scanning class resolver
382         */
383        PackageScanClassResolver getPackageScanClassResolver();
384    
385        /**
386         * Sets the class resolver to be use
387         */
388        void setClassResolver(ClassResolver resolver);
389    
390        /**
391         * Sets the package scanning class resolver to use
392         */
393        void setPackageScanClassResolver(PackageScanClassResolver resolver);
394    
395    }