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