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.DataFormat;
029    import org.apache.camel.spi.DataFormatResolver;
030    import org.apache.camel.spi.EndpointStrategy;
031    import org.apache.camel.spi.FactoryFinder;
032    import org.apache.camel.spi.FactoryFinderResolver;
033    import org.apache.camel.spi.InflightRepository;
034    import org.apache.camel.spi.Injector;
035    import org.apache.camel.spi.InterceptStrategy;
036    import org.apache.camel.spi.Language;
037    import org.apache.camel.spi.LifecycleStrategy;
038    import org.apache.camel.spi.ManagementStrategy;
039    import org.apache.camel.spi.NodeIdFactory;
040    import org.apache.camel.spi.PackageScanClassResolver;
041    import org.apache.camel.spi.Registry;
042    import org.apache.camel.spi.ServicePool;
043    import org.apache.camel.spi.ShutdownStrategy;
044    import org.apache.camel.spi.TypeConverterRegistry;
045    
046    /**
047     * Interface used to represent the context used to configure routes and the
048     * policies to use during message exchanges between endpoints.
049     *
050     * @version $Revision: 17082 $
051     */
052    public interface CamelContext extends Service, RuntimeConfiguration {
053    
054        /**
055         * Gets the name of the this context.
056         *
057         * @return the name
058         */
059        String getName();
060    
061        /**
062         * Gets the version of the this context.
063         *
064         * @return the version
065         */
066        String getVersion();
067    
068        // Service Methods
069        //-----------------------------------------------------------------------
070    
071        /**
072         * Adds a service, starting it so that it will be stopped with this context
073         *
074         * @param object the service
075         * @throws Exception can be thrown when starting the service
076         */
077        void addService(Object object) throws Exception;
078    
079        /**
080         * Has the given service already been added?
081         *
082         * @param object the service
083         * @return <tt>true</tt> if already added, <tt>false</tt> if not.
084         */
085        boolean hasService(Object object);
086    
087        // Component Management Methods
088        //-----------------------------------------------------------------------
089    
090        /**
091         * Adds a component to the context.
092         *
093         * @param componentName  the name the component is registered as
094         * @param component      the component
095         */
096        void addComponent(String componentName, Component component);
097    
098        /**
099         * Is the given component already registered?
100         *
101         * @param componentName the name of the component
102         * @return the registered Component or <tt>null</tt> if not registered
103         */
104        Component hasComponent(String componentName);
105    
106        /**
107         * Gets a component from the context by name.
108         *
109         * @param componentName the name of the component
110         * @return the component
111         */
112        Component getComponent(String componentName);
113    
114        /**
115         * Gets a component from the context by name and specifying the expected type of component.
116         *
117         * @param name  the name to lookup
118         * @param componentType  the expected type
119         * @return the component
120         */
121        <T extends Component> T getComponent(String name, Class<T> componentType);
122    
123        /**
124         * Gets a readonly list of names of the components currently registered
125         *
126         * @return a readonly list with the names of the the components
127         */
128        List<String> getComponentNames();
129    
130        /**
131         * Removes a previously added component.
132         *
133         * @param componentName the component name to remove
134         * @return the previously added component or null if it had not been previously added.
135         */
136        Component removeComponent(String componentName);
137    
138        /**
139         * Gets the a previously added component by name or lazily creates the component
140         * using the factory Callback.
141         *
142         * @param componentName the name of the component
143         * @param factory       used to create a new component instance if the component was not previously added.
144         * @return the component
145         * @deprecated will be removed in Camel 2.3.
146         */
147        @Deprecated
148        Component getOrCreateComponent(String componentName, Callable<Component> factory);
149    
150        // Endpoint Management Methods
151        //-----------------------------------------------------------------------
152    
153        /**
154         * Resolves the given name to an {@link Endpoint} of the specified type.
155         * If the name has a singleton endpoint registered, then the singleton is returned.
156         * Otherwise, a new {@link Endpoint} is created and registered.
157         *
158         * @param uri  the URI of the endpoint
159         * @return  the endpoint
160         */
161        Endpoint getEndpoint(String uri);
162    
163        /**
164         * Resolves the given name to an {@link Endpoint} of the specified type.
165         * If the name has a singleton endpoint registered, then the singleton is returned.
166         * Otherwise, a new {@link Endpoint} is created and registered.
167         *
168         * @param name  the name of the endpoint
169         * @param endpointType  the expected type
170         * @return the endpoint
171         */
172        <T extends Endpoint> T getEndpoint(String name, Class<T> endpointType);
173    
174        /**
175         * Returns the collection of all registered endpoints.
176         *
177         * @return  all endpoints
178         */
179        Collection<Endpoint> getEndpoints();
180    
181        /**
182         * Returns a new Map containing all of the active endpoints with the key of the map being their
183         * unique key.
184         *
185         * @return map of active endpoints
186         */
187        Map<String, Endpoint> getEndpointMap();
188    
189        /**
190         * Is the given endpoint already registered?
191         *
192         * @param uri  the URI of the endpoint
193         * @return the registered endpoint or <tt>null</tt> if not registered
194         */
195        Endpoint hasEndpoint(String uri);
196    
197        /**
198         * Returns the collection of all registered endpoints for a uri or an empty collection.
199         * For a singleton endpoint the collection will contain exactly one element.
200         *
201         * @param uri  the URI of the endpoints
202         * @return  collection of endpoints
203         * @deprecated not used will be removed in Camel 2.3.
204         */
205        @Deprecated
206        Collection<Endpoint> getEndpoints(String uri);
207    
208        /**
209         * Returns the collection of all registered singleton endpoints.
210         *
211         * @return  all the singleton endpoints
212         * @deprecated not used will be removed in Camel 2.3.
213         */
214        @Deprecated
215        Collection<Endpoint> getSingletonEndpoints();
216    
217        /**
218         * Adds the endpoint to the context using the given URI.
219         *
220         * @param uri the URI to be used to resolve this endpoint
221         * @param endpoint the endpoint to be added to the context
222         * @return the old endpoint that was previously registered or <tt>null</tt> if none was registered
223         * @throws Exception if the new endpoint could not be started or the old endpoint could not be stopped
224         */
225        Endpoint addEndpoint(String uri, Endpoint endpoint) throws Exception;
226    
227        /**
228         * Removes all endpoints with the given URI
229         *
230         * @param uri the URI to be used to remove
231         * @return a collection of endpoints removed or null if there are no endpoints for this URI
232         * @throws Exception if at least one endpoint could not be stopped
233         * @deprecated not used will be removed in Camel 2.3.
234         */
235        @Deprecated
236        Collection<Endpoint> removeEndpoints(String uri) throws Exception;
237    
238        /**
239         * Registers a {@link org.apache.camel.spi.EndpointStrategy callback} to allow you to do custom
240         * logic when an {@link Endpoint} is about to be registered to the {@link CamelContext} endpoint registry.
241         * <p/>
242         * When a callback is added it will be executed on the already registered endpoints allowing you to catch-up
243         *
244         * @param strategy  callback to be invoked
245         */
246        void addRegisterEndpointCallback(EndpointStrategy strategy);
247    
248        // Route Management Methods
249        //-----------------------------------------------------------------------
250    
251        /**
252         * Returns a list of the current route definitions
253         *
254         * @return list of the current route definitions
255         */
256        List<RouteDefinition> getRouteDefinitions();
257    
258        /**
259         * Gets the route definition with the given id
260         *
261         * @param id id of the route
262         * @return the route definition or <tt>null</tt> if not found
263         */
264        RouteDefinition getRouteDefinition(String id);
265    
266        /**
267         * Returns the current routes in this context
268         *
269         * @return the current routes
270         */
271        List<Route> getRoutes();
272    
273        /**
274         * Adds a collection of routes to this context using the given builder
275         * to build them
276         *
277         * @param builder the builder which will create the routes and add them to this context
278         * @throws Exception if the routes could not be created for whatever reason
279         */
280        void addRoutes(RoutesBuilder builder) throws Exception;
281    
282        /**
283         * Adds a collection of route definitions to the context
284         *
285         * @param routeDefinitions the route definitions to add
286         * @throws Exception if the route definition could not be created for whatever reason
287         */
288        void addRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
289    
290        /**
291         * Removes a collection of route definitions from the context - stopping any previously running
292         * routes if any of them are actively running
293         *
294         * @param routeDefinitions route definitions
295         * @throws Exception if the route definition could not be removed for whatever reason
296         */
297        void removeRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
298    
299        /**
300         * Starts the given route if it has been previously stopped
301         *
302         * @param route the route to start
303         * @throws Exception is thrown if the route could not be started for whatever reason
304         */
305        void startRoute(RouteDefinition route) throws Exception;
306    
307        /**
308         * Starts the given route if it has been previously stopped
309         *
310         * @param routeId the route id
311         * @throws Exception is thrown if the route could not be started for whatever reason
312         */
313        void startRoute(String routeId) throws Exception;
314    
315        /**
316         * Stops the given route. It will remain in the list of route definitions return by {@link #getRouteDefinitions()}
317         * unless you use the {@link #removeRouteDefinitions(java.util.Collection)}
318         *
319         * @param route the route to stop
320         * @throws Exception is thrown if the route could not be stopped for whatever reason
321         */
322        void stopRoute(RouteDefinition route) throws Exception;
323    
324        /**
325         * Stops the given route. It will remain in the list of route definitions return by {@link #getRouteDefinitions()}
326         * unless you use the {@link #removeRouteDefinitions(java.util.Collection)}
327         *
328         * @param routeId the route id
329         * @throws Exception is thrown if the route could not be stopped for whatever reason
330         */
331        void stopRoute(String routeId) throws Exception;
332    
333        /**
334         * Returns the current status of the given route
335         *
336         * @param routeId the route id
337         * @return the status for the route
338         */
339        ServiceStatus getRouteStatus(String routeId);
340    
341        /**
342         * Returns the current status of the given route
343         *
344         * @param route the route
345         * @return the status for the route
346         * @deprecated will be removed in Camel 2.3.
347         */
348        @Deprecated
349        ServiceStatus getRouteStatus(RouteDefinition route);
350    
351        // Properties
352        //-----------------------------------------------------------------------
353    
354        /**
355         * Returns the type converter used to coerce types from one type to another
356         *
357         * @return the converter
358         */
359        TypeConverter getTypeConverter();
360    
361        /**
362         * Returns the type converter registry where type converters can be added or looked up
363         *
364         * @return the type converter registry
365         */
366        TypeConverterRegistry getTypeConverterRegistry();
367        
368        /**
369         * Returns the registry used to lookup components by name and type such as the Spring ApplicationContext,
370         * JNDI or the OSGi Service Registry
371         *
372         * @return the registry
373         */
374        Registry getRegistry();
375    
376        /**
377         * Returns the injector used to instantiate objects by type
378         *
379         * @return the injector
380         */
381        Injector getInjector();
382    
383        /**
384         * Returns the lifecycle strategies used to handle lifecycle notifications
385         *
386         * @return the lifecycle strategies
387         */
388        List<LifecycleStrategy> getLifecycleStrategies();
389    
390        /**
391         * Adds the given lifecycle strategy to be used.
392         *
393         * @param lifecycleStrategy  the strategy
394         */
395        void addLifecycleStrategy(LifecycleStrategy lifecycleStrategy);
396    
397        /**
398         * Resolves a language for creating expressions
399         *
400         * @param language  name of the language
401         * @return the resolved language
402         */
403        Language resolveLanguage(String language);
404    
405        /**
406         * Gets a readonly list with the names of the languages currently registered.
407         *
408         * @return a readonly list with the names of the the languages
409         */
410        List<String> getLanguageNames();
411    
412        /**
413         * Creates a new ProducerTemplate.
414         * <p/>
415         * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
416         * Why does Camel use too many threads with ProducerTemplate?</a>
417         *
418         * @return the template
419         */
420        ProducerTemplate createProducerTemplate();
421    
422        /**
423         * Creates a new ConsumerTemplate.
424         * <p/>
425         * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
426         * Why does Camel use too many threads with ProducerTemplate?</a> as it also applies for ConsumerTemplate.
427         *
428         * @return the template
429         */
430        ConsumerTemplate createConsumerTemplate();
431    
432        /**
433         * Adds the given interceptor strategy
434         *
435         * @param interceptStrategy the strategy
436         */
437        void addInterceptStrategy(InterceptStrategy interceptStrategy);
438    
439        /**
440         * Gets the interceptor strategies
441         *
442         * @return the list of current interceptor strategies
443         */
444        List<InterceptStrategy> getInterceptStrategies();
445    
446        /**
447         * Gets the default error handler builder which is inherited by the routes
448         *
449         * @return the builder
450         */
451        ErrorHandlerBuilder getErrorHandlerBuilder();
452    
453        /**
454         * Sets the default error handler builder which is inherited by the routes
455         *
456         * @param errorHandlerBuilder  the builder
457         */
458        void setErrorHandlerBuilder(ErrorHandlerBuilder errorHandlerBuilder);
459    
460        /**
461         * Sets the data formats that can be referenced in the routes.
462         *
463         * @param dataFormats the data formats
464         */
465        void setDataFormats(Map<String, DataFormatDefinition> dataFormats);
466    
467        /**
468         * Gets the data formats that can be referenced in the routes.
469         *
470         * @return the data formats available
471         */
472        Map<String, DataFormatDefinition> getDataFormats();
473        
474        /**
475         * Resolve a data format given its name
476         *
477         * @param name the data format name or a reference to it in the {@link Registry}
478         * @return the resolved data format, or <tt>null</tt> if not found
479         */
480        DataFormat resolveDataFormat(String name);
481    
482        /**
483         * Resolve a data format definition given its name
484         *
485         * @param name the data format definition name or a reference to it in the {@link Registry}
486         * @return the resolved data format definition, or <tt>null</tt> if not found
487         */
488        DataFormatDefinition resolveDataFormatDefinition(String name);
489    
490        /**
491         * Gets the current data format resolver
492         *
493         * @return the resolver
494         */
495        DataFormatResolver getDataFormatResolver();
496    
497        /**
498         * Sets a custom data format resolver
499         *
500         * @param dataFormatResolver  the resolver
501         */
502        void setDataFormatResolver(DataFormatResolver dataFormatResolver);
503    
504        /**
505         * Sets the properties that can be referenced in the camel context
506         *
507         * @param properties properties
508         */
509        void setProperties(Map<String, String> properties);
510        
511        /**
512         * Gets the properties that can be referenced in the camel context
513         *
514         * @return the properties
515         */
516        Map<String, String> getProperties();
517        
518        /**
519         * Gets the default FactoryFinder which will be used for the loading the factory class from META-INF
520         *
521         * @return the default factory finder
522         */
523        FactoryFinder getDefaultFactoryFinder();
524    
525        /**
526         * Sets the factory finder resolver to use.
527         *
528         * @param resolver the factory finder resolver
529         */
530        void setFactoryFinderResolver(FactoryFinderResolver resolver);
531        
532        /**
533         * Gets the FactoryFinder which will be used for the loading the factory class from META-INF in the given path
534         *
535         * @param path the META-INF path
536         * @return the factory finder
537         * @throws NoFactoryAvailableException is thrown if a factory could not be found
538         */
539        FactoryFinder getFactoryFinder(String path) throws NoFactoryAvailableException;
540    
541        /**
542         * Returns the class resolver to be used for loading/lookup of classes.
543         *
544         * @return the resolver
545         */
546        ClassResolver getClassResolver();
547    
548        /**
549         * Returns the package scanning class resolver
550         *
551         * @return the resolver
552         */
553        PackageScanClassResolver getPackageScanClassResolver();
554    
555        /**
556         * Sets the class resolver to be use
557         *
558         * @param resolver the resolver
559         */
560        void setClassResolver(ClassResolver resolver);
561    
562        /**
563         * Sets the package scanning class resolver to use
564         *
565         * @param resolver the resolver
566         */
567        void setPackageScanClassResolver(PackageScanClassResolver resolver);
568    
569        /**
570         * Sets a pluggable service pool to use for {@link Producer} pooling.
571         *
572         * @param servicePool the pool
573         */
574        void setProducerServicePool(ServicePool<Endpoint, Producer> servicePool);
575    
576        /**
577         * Gets the service pool for {@link Producer} pooling.
578         *
579         * @return the service pool
580         */
581        ServicePool<Endpoint, Producer> getProducerServicePool();
582    
583        /**
584         * Uses a custom node id factory when generating auto assigned ids to the nodes in the route definitions
585         *
586         * @param factory  custom factory to use
587         */
588        void setNodeIdFactory(NodeIdFactory factory);
589    
590        /**
591         * Gets the node id factory
592         *
593         * @return  the node id factory
594         */
595        NodeIdFactory getNodeIdFactory();
596    
597        /**
598         * Gets the management strategy
599         *
600         * @return the management strategy
601         */
602        ManagementStrategy getManagementStrategy();
603    
604        /**
605         * Sets the management strategy to use
606         *
607         * @param strategy the management strategy
608         */
609        void setManagementStrategy(ManagementStrategy strategy);
610    
611        /**
612         * Gets the default tracer
613         *
614         * @return the default tracer
615         */
616        InterceptStrategy getDefaultTracer();
617    
618        /**
619         * Disables using JMX as {@link org.apache.camel.spi.ManagementStrategy}.
620         */
621        void disableJMX();
622    
623        /**
624         * Gets the inflight repository
625         *
626         * @return the repository
627         */
628        InflightRepository getInflightRepository();
629    
630        /**
631         * Sets a custom inflight repository to use
632         *
633         * @param repository the repository
634         */
635        void setInflightRepository(InflightRepository repository);
636        
637        /**
638         * Gets the the application context class loader which may be helpful for running camel in other containers
639         *
640         * @return the application context class loader
641         */
642        ClassLoader getApplicationContextClassLoader();
643    
644        /**
645         * Sets the application context class loader
646         *
647         * @param classLoader the class loader
648         */
649        void setApplicationContextClassLoader(ClassLoader classLoader);
650    
651        /**
652         * Gets the current shutdown strategy
653         *
654         * @return the strategy
655         */
656        ShutdownStrategy getShutdownStrategy();
657    
658        /**
659         * Sets a custom shutdown strategy
660         *
661         * @param shutdownStrategy the custom strategy
662         */
663        void setShutdownStrategy(ShutdownStrategy shutdownStrategy);
664    
665    }