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.DataFormatDefinition;
026    import org.apache.camel.model.RouteDefinition;
027    import org.apache.camel.spi.ClassResolver;
028    import org.apache.camel.spi.EndpointStrategy;
029    import org.apache.camel.spi.ExchangeConverter;
030    import org.apache.camel.spi.FactoryFinder;
031    import org.apache.camel.spi.FactoryFinderResolver;
032    import org.apache.camel.spi.Injector;
033    import org.apache.camel.spi.InterceptStrategy;
034    import org.apache.camel.spi.Language;
035    import org.apache.camel.spi.LifecycleStrategy;
036    import org.apache.camel.spi.PackageScanClassResolver;
037    import org.apache.camel.spi.Registry;
038    import org.apache.camel.spi.ServicePool;
039    import org.apache.camel.spi.TypeConverterRegistry;
040    
041    /**
042     * Interface used to represent the context used to configure routes and the
043     * policies to use during message exchanges between endpoints.
044     *
045     * @version $Revision: 782535 $
046     */
047    public interface CamelContext extends Service {
048    
049        /**
050         * Gets the name of the this context.
051         *
052         * @return the name
053         */
054        String getName();
055    
056        // Component Management Methods
057        //-----------------------------------------------------------------------
058    
059        /**
060         * Adds a component to the context.
061         *
062         * @param componentName  the name the component is registered as
063         * @param component      the component
064         */
065        void addComponent(String componentName, Component component);
066    
067        /**
068         * Gets a component from the context by name.
069         *
070         * @param componentName the name of the component
071         * @return the component
072         */
073        Component getComponent(String componentName);
074    
075        /**
076         * Gets a component from the context by name and specifying the expected type of component.
077         *
078         * @param name  the name to lookup
079         * @param componentType  the expected type
080         * @return the component
081         */
082        <T extends Component> T getComponent(String name, Class<T> componentType);
083    
084        /**
085         * Gets a readonly list of names of the components currently registered
086         *
087         * @return a readonly list with the names of the the components
088         */
089        List<String> getComponentNames();
090    
091        /**
092         * Removes a previously added component.
093         *
094         * @param componentName the component name to remove
095         * @return the previously added component or null if it had not been previously added.
096         */
097        Component removeComponent(String componentName);
098    
099        /**
100         * Gets the a previously added component by name or lazily creates the component
101         * using the factory Callback.
102         *
103         * @param componentName the name of the component
104         * @param factory       used to create a new component instance if the component was not previously added.
105         * @return the component
106         */
107        Component getOrCreateComponent(String componentName, Callable<Component> factory);
108    
109        // Endpoint Management Methods
110        //-----------------------------------------------------------------------
111    
112        /**
113         * Resolves the given URI to an {@link Endpoint}.  If the URI has a singleton endpoint
114         * registered, then the singleton is returned.  Otherwise, a new {@link Endpoint} is created
115         * and if the endpoint is a singleton it is registered as a singleton endpoint.
116         *
117         * @param uri  the URI of the endpoint
118         * @return  the endpoint
119         */
120        Endpoint getEndpoint(String uri);
121    
122        /**
123         * Resolves the given name to an {@link Endpoint} of the specified type.
124         * If the name has a singleton endpoint registered, then the singleton is returned.
125         * Otherwise, a new {@link Endpoint} is created and if the endpoint is a
126         * singleton it is registered as a singleton endpoint.
127         *
128         * @param name  the name of the endpoint
129         * @param endpointType  the expected type
130         * @return the endpoint
131         */
132        <T extends Endpoint> T getEndpoint(String name, Class<T> endpointType);
133    
134        /**
135         * Returns the collection of all registered endpoints.
136         *
137         * @return  all endpoints
138         */
139        Collection<Endpoint> getEndpoints();
140    
141        /**
142         * Returns a new Map containing all of the active endpoints with the key of the map being their
143         * unique key.
144         *
145         * @return map of active endpoints
146         */
147        Map<String, Endpoint> getEndpointMap();
148    
149        /**
150         * Returns the collection of all registered endpoints for a uri or an empty collection.
151         * For a singleton endpoint the collection will contain exactly one element.
152         *
153         * @param uri  the URI of the endpoints
154         * @return  collection of endpoints
155         */
156        Collection<Endpoint> getEndpoints(String uri);
157    
158        /**
159         * Returns the collection of all registered singleton endpoints.
160         *
161         * @return  all the singleton endpoints
162         */
163        Collection<Endpoint> getSingletonEndpoints();
164    
165        /**
166         * Adds the endpoint to the context using the given URI.
167         *
168         * @param uri the URI to be used to resolve this endpoint
169         * @param endpoint the endpoint to be added to the context
170         * @return the old endpoint that was previously registered to the context if 
171         * there was already an singleton endpoint for that URI or null
172         * @throws Exception if the new endpoint could not be started or the old 
173         * singleton endpoint could not be stopped
174         */
175        Endpoint addEndpoint(String uri, Endpoint endpoint) throws Exception;
176    
177        /**
178         * Removes all endpoints with the given URI
179         *
180         * @param uri the URI to be used to remove
181         * @return a collection of endpoints removed or null if there are no endpoints for this URI
182         * @throws Exception if at least one endpoint could not be stopped
183         */
184        Collection<Endpoint> removeEndpoints(String uri) throws Exception;
185    
186        /**
187         * Registers a {@link org.apache.camel.spi.EndpointStrategy callback} to allow you to do custom
188         * logic when an {@link Endpoint} is about to be registered to the {@link CamelContext} endpoint registry.
189         * <p/>
190         * When a callback is added it will be executed on the already registered endpoints allowing you to catch-up
191         *
192         * @param strategy  callback to be invoked
193         */
194        void addRegisterEndpointCallback(EndpointStrategy strategy);
195    
196        // Route Management Methods
197        //-----------------------------------------------------------------------
198    
199        /**
200         * Returns a list of the current route definitions
201         *
202         * @return list of the current route definitions
203         */
204        List<RouteDefinition> getRouteDefinitions();
205    
206        /**
207         * Returns the current routes in this context
208         *
209         * @return the current routes
210         */
211        List<Route> getRoutes();
212    
213        /**
214         * Adds a collection of routes to this context using the given builder
215         * to build them
216         *
217         * @param builder the builder which will create the routes and add them to this context
218         * @throws Exception if the routes could not be created for whatever reason
219         */
220        void addRoutes(Routes builder) throws Exception;
221    
222        /**
223         * Adds a collection of route definitions to the context
224         *
225         * @param routeDefinitions the route definitions to add
226         * @throws Exception if the route definition could not be created for whatever reason
227         */
228        void addRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
229    
230        /**
231         * Removes a collection of route definitions from the context - stopping any previously running
232         * routes if any of them are actively running
233         *
234         * @param routeDefinitions route definitions
235         * @throws Exception if the route definition could not be removed for whatever reason
236         */
237        void removeRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
238    
239        /**
240         * Starts the given route if it has been previously stopped
241         *
242         * @param route the route to start
243         * @throws Exception is thrown if the route could not be started for whatever reason
244         */
245        void startRoute(RouteDefinition route) throws Exception;
246    
247        /**
248         * Stops the given route. It will remain in the list of route definitions return by {@link #getRouteDefinitions()}
249         * unless you use the {@link #removeRouteDefinitions(java.util.Collection)}
250         *
251         * @param route the route to stop
252         * @throws Exception is thrown if the route could not be stopped for whatever reason
253         */
254        void stopRoute(RouteDefinition route) throws Exception;
255    
256    
257        // Properties
258        //-----------------------------------------------------------------------
259    
260        /**
261         * Returns the converter of exchanges from one type to another
262         *
263         * @return the converter
264         */
265        ExchangeConverter getExchangeConverter();
266    
267        /**
268         * Returns the type converter used to coerce types from one type to another
269         *
270         * @return the converter
271         */
272        TypeConverter getTypeConverter();
273    
274        /**
275         * Returns the type converter registry where type converters can be added or looked up
276         *
277         * @return the type converter registry
278         */
279        TypeConverterRegistry getTypeConverterRegistry();
280        
281        /**
282         * Returns the registry used to lookup components by name and type such as the Spring ApplicationContext,
283         * JNDI or the OSGi Service Registry
284         *
285         * @return the registry
286         */
287        Registry getRegistry();
288    
289        /**
290         * Returns the injector used to instantiate objects by type
291         *
292         * @return the injector
293         */
294        Injector getInjector();
295    
296        /**
297         * Returns the lifecycle strategy used to handle lifecycle notification
298         *
299         * @return the lifecycle strategy
300         */
301        LifecycleStrategy getLifecycleStrategy();
302    
303        /**
304         * Resolves a language for creating expressions
305         *
306         * @param language  name of the language
307         * @return the resolved language
308         */
309        Language resolveLanguage(String language);
310    
311        /**
312         * Gets a readonly list with the names of the languages currently registered.
313         *
314         * @return a readonly list with the names of the the languages
315         */
316        List<String> getLanguageNames();
317    
318        /**
319         * Creates a new ProducerTemplate.
320         * <p/>
321         * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
322         * Why does Camel use too many threads with ProducerTemplate?</a>
323         *
324         * @return the template
325         */
326        ProducerTemplate createProducerTemplate();
327    
328        /**
329         * Creates a new ConsumerTemplate.
330         * <p/>
331         * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
332         * Why does Camel use too many threads with ProducerTemplate?</a> as it also applies for ConsumerTemplate.
333         *
334         * @return the template
335         */
336        ConsumerTemplate createConsumerTemplate();
337    
338        /**
339         * Adds the given interceptor strategy
340         *
341         * @param interceptStrategy the strategy
342         */
343        void addInterceptStrategy(InterceptStrategy interceptStrategy);
344    
345        /**
346         * Gets the interceptor strategies
347         *
348         * @return the list of current interceptor strategies
349         */
350        List<InterceptStrategy> getInterceptStrategies();
351    
352        /**
353         * Gets the default error handler builder which is inherited by the routes
354         *
355         * @return the builder
356         */
357        ErrorHandlerBuilder getErrorHandlerBuilder();
358    
359        /**
360         * Sets the default error handler builder which is inherited by the routes
361         *
362         * @param errorHandlerBuilder  the builder
363         */
364        void setErrorHandlerBuilder(ErrorHandlerBuilder errorHandlerBuilder);
365    
366        /**
367         * Sets the data formats that can be referenced in the routes.
368         * @param dataFormats the data formats
369         */
370        void setDataFormats(Map<String, DataFormatDefinition> dataFormats);
371    
372        /**
373         * Gets the data formats that can be referenced in the routes.
374         *
375         * @return the data formats available
376         */
377        Map<String, DataFormatDefinition> getDataFormats();
378        
379        /**
380         * Sets the properties that can be referenced in the camel context
381         *
382         * @param properties properties
383         */
384        void setProperties(Map<String, String> properties);
385        
386        /**
387         * Gets the properties that can be referenced in the camel context
388         *
389         * @return the properties
390         */
391        Map<String, String> getProperties();
392        
393        /**
394         * Gets the default FactoryFinder which will be used for the loading the factory class from META-INF
395         *
396         * @return the default factory finder
397         */
398        FactoryFinder getDefaultFactoryFinder();
399    
400        /**
401         * Sets the factory finder resolver to use.
402         *
403         * @param resolver the factory finder resolver
404         */
405        void setFactoryFinderResolver(FactoryFinderResolver resolver);
406        
407        /**
408         * Gets the FactoryFinder which will be used for the loading the factory class from META-INF in the given path
409         *
410         * @param path the META-INF path
411         * @return the factory finder
412         * @throws NoFactoryAvailableException is thrown if a factory could not be found
413         */
414        FactoryFinder getFactoryFinder(String path) throws NoFactoryAvailableException;
415    
416        /**
417         * Returns the current status of the given route
418         *
419         * @param route the route
420         * @return the status for the route
421         */
422        ServiceStatus getRouteStatus(RouteDefinition route);
423    
424        /**
425         * Returns the class resolver to be used for loading/lookup of classes.
426         *
427         * @return the resolver
428         */
429        ClassResolver getClassResolver();
430    
431        /**
432         * Returns the package scanning class resolver
433         *
434         * @return the resolver
435         */
436        PackageScanClassResolver getPackageScanClassResolver();
437    
438        /**
439         * Sets the class resolver to be use
440         *
441         * @param resolver the resolver
442         */
443        void setClassResolver(ClassResolver resolver);
444    
445        /**
446         * Sets the package scanning class resolver to use
447         *
448         * @param resolver the resolver
449         */
450        void setPackageScanClassResolver(PackageScanClassResolver resolver);
451    
452        /**
453         * Sets a pluggable service pool to use for {@link Producer} pooling.
454         *
455         * @param servicePool the pool
456         */
457        void setProducerServicePool(ServicePool<Endpoint, Producer> servicePool);
458    
459        /**
460         * Gets the service pool for {@link Producer} pooling.
461         *
462         * @return the service pool
463         */
464        ServicePool<Endpoint, Producer> getProducerServicePool();
465    
466    }