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 }