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