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