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 */
017package org.apache.camel;
018
019import java.io.IOException;
020import java.io.InputStream;
021import java.util.Collection;
022import java.util.List;
023import java.util.Map;
024import java.util.Properties;
025import java.util.concurrent.ScheduledExecutorService;
026import java.util.concurrent.TimeUnit;
027
028import org.apache.camel.api.management.mbean.ManagedCamelContextMBean;
029import org.apache.camel.api.management.mbean.ManagedProcessorMBean;
030import org.apache.camel.api.management.mbean.ManagedRouteMBean;
031import org.apache.camel.builder.ErrorHandlerBuilder;
032import org.apache.camel.model.DataFormatDefinition;
033import org.apache.camel.model.ProcessorDefinition;
034import org.apache.camel.model.RouteDefinition;
035import org.apache.camel.model.RoutesDefinition;
036import org.apache.camel.model.remote.ServiceCallConfigurationDefinition;
037import org.apache.camel.model.rest.RestDefinition;
038import org.apache.camel.model.rest.RestsDefinition;
039import org.apache.camel.spi.AsyncProcessorAwaitManager;
040import org.apache.camel.spi.CamelContextNameStrategy;
041import org.apache.camel.spi.ClassResolver;
042import org.apache.camel.spi.DataFormat;
043import org.apache.camel.spi.DataFormatResolver;
044import org.apache.camel.spi.Debugger;
045import org.apache.camel.spi.EndpointRegistry;
046import org.apache.camel.spi.EndpointStrategy;
047import org.apache.camel.spi.ExecutorServiceManager;
048import org.apache.camel.spi.FactoryFinder;
049import org.apache.camel.spi.FactoryFinderResolver;
050import org.apache.camel.spi.InflightRepository;
051import org.apache.camel.spi.Injector;
052import org.apache.camel.spi.InterceptStrategy;
053import org.apache.camel.spi.Language;
054import org.apache.camel.spi.LifecycleStrategy;
055import org.apache.camel.spi.ManagementMBeanAssembler;
056import org.apache.camel.spi.ManagementNameStrategy;
057import org.apache.camel.spi.ManagementStrategy;
058import org.apache.camel.spi.MessageHistoryFactory;
059import org.apache.camel.spi.ModelJAXBContextFactory;
060import org.apache.camel.spi.NodeIdFactory;
061import org.apache.camel.spi.PackageScanClassResolver;
062import org.apache.camel.spi.ProcessorFactory;
063import org.apache.camel.spi.Registry;
064import org.apache.camel.spi.RestConfiguration;
065import org.apache.camel.spi.RestRegistry;
066import org.apache.camel.spi.RoutePolicyFactory;
067import org.apache.camel.spi.RouteStartupOrder;
068import org.apache.camel.spi.RuntimeEndpointRegistry;
069import org.apache.camel.spi.ServicePool;
070import org.apache.camel.spi.ShutdownStrategy;
071import org.apache.camel.spi.StreamCachingStrategy;
072import org.apache.camel.spi.TypeConverterRegistry;
073import org.apache.camel.spi.UnitOfWorkFactory;
074import org.apache.camel.spi.UuidGenerator;
075import org.apache.camel.util.LoadPropertiesException;
076
077/**
078 * Interface used to represent the context used to configure routes and the
079 * policies to use during message exchanges between endpoints.
080 * <p/>
081 * The context offers the following methods to control the lifecycle:
082 * <ul>
083 *   <li>{@link #start()}  - to start (<b>important:</b> the start method is not blocked, see more details
084 *     <a href="http://camel.apache.org/running-camel-standalone-and-have-it-keep-running.html">here</a>)</li>
085 *   <li>{@link #stop()} - to shutdown (will stop all routes/components/endpoints etc and clear internal state/cache)</li>
086 *   <li>{@link #suspend()} - to pause routing messages</li>
087 *   <li>{@link #resume()} - to resume after a suspend</li>
088 * </ul>
089 * <p/>
090 * <b>Notice:</b> {@link #stop()} and {@link #suspend()} will gracefully stop/suspend routes ensuring any messages
091 * in progress will be given time to complete. See more details at {@link org.apache.camel.spi.ShutdownStrategy}.
092 * <p/>
093 * If you are doing a hot restart then it's advised to use the suspend/resume methods which ensure a faster
094 * restart but also allows any internal state to be kept as is.
095 * The stop/start approach will do a <i>cold</i> restart of Camel, where all internal state is reset.
096 * <p/>
097 * End users are advised to use suspend/resume. Using stop is for shutting down Camel and it's not guaranteed that
098 * when it's being started again using the start method that Camel will operate consistently.
099 *
100 * @version 
101 */
102public interface CamelContext extends SuspendableService, RuntimeConfiguration {
103
104    /**
105     * Adapts this {@link org.apache.camel.CamelContext} to the specialized type.
106     * <p/>
107     * For example to adapt to {@link org.apache.camel.model.ModelCamelContext},
108     * or <tt>SpringCamelContext</tt>, or <tt>CdiCamelContext</tt>, etc.
109     *
110     * @param type the type to adapt to
111     * @return this {@link org.apache.camel.CamelContext} adapted to the given type
112     */
113    <T extends CamelContext> T adapt(Class<T> type);
114
115    /**
116     * If CamelContext during the start procedure was vetoed, and therefore causing Camel to not start.
117     */
118    boolean isVetoStarted();
119
120    /**
121     * Starts the {@link CamelContext} (<b>important:</b> the start method is not blocked, see more details
122     *     <a href="http://camel.apache.org/running-camel-standalone-and-have-it-keep-running.html">here</a>)</li>.
123     * <p/>
124     * See more details at the class-level javadoc of this class.
125     *
126     * @throws Exception is thrown if starting failed
127     */
128    void start() throws Exception;
129
130    /**
131     * Stop and shutdown the {@link CamelContext} (will stop all routes/components/endpoints etc and clear internal state/cache).
132     * <p/>
133     * See more details at the class-level javadoc of this class.
134     *
135     * @throws Exception is thrown if stopping failed
136     */
137    void stop() throws Exception;
138
139    /**
140     * Gets the name (id) of the this context.
141     *
142     * @return the name
143     */
144    String getName();
145
146    /**
147     * Gets the current name strategy
148     *
149     * @return name strategy
150     */
151    CamelContextNameStrategy getNameStrategy();
152
153    /**
154     * Sets a custom name strategy
155     *
156     * @param nameStrategy name strategy
157     */
158    void setNameStrategy(CamelContextNameStrategy nameStrategy);
159
160    /**
161     * Gets the current management name strategy
162     *
163     * @return management name strategy
164     */
165    ManagementNameStrategy getManagementNameStrategy();
166
167    /**
168     * Sets a custom management name strategy
169     *
170     * @param nameStrategy name strategy
171     */
172    void setManagementNameStrategy(ManagementNameStrategy nameStrategy);
173
174    /**
175     * Gets the name this {@link CamelContext} was registered in JMX.
176     * <p/>
177     * The reason that a {@link CamelContext} can have a different name in JMX is the fact to remedy for name clash
178     * in JMX when having multiple {@link CamelContext}s in the same JVM. Camel will automatic reassign and use
179     * a free name to avoid failing to start.
180     *
181     * @return the management name
182     */
183    String getManagementName();
184
185    /**
186     * Gets the version of the this context.
187     *
188     * @return the version
189     */
190    String getVersion();
191
192    /**
193     * Get the status of this context
194     *
195     * @return the status
196     */
197    ServiceStatus getStatus();
198
199    /**
200     * Gets the uptime in a human readable format
201     *
202     * @return the uptime in days/hours/minutes
203     */
204    String getUptime();
205
206    /**
207     * Gets the uptime in milli seconds
208     *
209     * @return the uptime in millis seconds
210     */
211    long getUptimeMillis();
212
213    // Service Methods
214    //-----------------------------------------------------------------------
215
216    /**
217     * Adds a service to this context, which allows this context to control the lifecycle, ensuring
218     * the service is stopped when the context stops.
219     * <p/>
220     * The service will also have {@link CamelContext} injected if its {@link CamelContextAware}.
221     * The service will also be enlisted in JMX for management (if JMX is enabled).
222     * The service will be started, if its not already started.
223     *
224     * @param object the service
225     * @throws Exception can be thrown when starting the service
226     */
227    void addService(Object object) throws Exception;
228
229    /**
230     * Adds a service to this context.
231     * <p/>
232     * The service will also have {@link CamelContext} injected if its {@link CamelContextAware}.
233     * The service will also be enlisted in JMX for management (if JMX is enabled).
234     * The service will be started, if its not already started.
235     * <p/>
236     * If the option <tt>closeOnShutdown</tt> is <tt>true</tt> then this context will control the lifecycle, ensuring
237     * the service is stopped when the context stops.
238     * If the option <tt>closeOnShutdown</tt> is <tt>false</tt> then this context will not stop the service when the context stops.
239     *
240     * @param object the service
241     * @param stopOnShutdown whether to stop the service when this CamelContext shutdown.
242     * @throws Exception can be thrown when starting the service
243     */
244    void addService(Object object, boolean stopOnShutdown) throws Exception;
245
246    /**
247     * Adds a service to this context.
248     * <p/>
249     * The service will also have {@link CamelContext} injected if its {@link CamelContextAware}.
250     * The service will also be enlisted in JMX for management (if JMX is enabled).
251     * The service will be started, if its not already started.
252     * <p/>
253     * If the option <tt>closeOnShutdown</tt> is <tt>true</tt> then this context will control the lifecycle, ensuring
254     * the service is stopped when the context stops.
255     * If the option <tt>closeOnShutdown</tt> is <tt>false</tt> then this context will not stop the service when the context stops.
256     *
257     * @param object the service
258     * @param stopOnShutdown whether to stop the service when this CamelContext shutdown.
259     * @param forceStart whether to force starting the service right now, as otherwise the service may be deferred being started
260     *                   to later using {@link #deferStartService(Object, boolean)}
261     * @throws Exception can be thrown when starting the service
262     */
263    void addService(Object object, boolean stopOnShutdown, boolean forceStart) throws Exception;
264
265    /**
266     * Removes a service from this context.
267     * <p/>
268     * The service is assumed to have been previously added using {@link #addService(Object)} method.
269     * This method will <b>not</b> change the service lifecycle.
270     *
271     * @param object the service
272     * @throws Exception can be thrown if error removing the service
273     * @return <tt>true</tt> if the service was removed, <tt>false</tt> if no service existed
274     */
275    boolean removeService(Object object) throws Exception;
276
277    /**
278     * Has the given service already been added to this context?
279     *
280     * @param object the service
281     * @return <tt>true</tt> if already added, <tt>false</tt> if not.
282     */
283    boolean hasService(Object object);
284
285    /**
286     * Has the given service type already been added to this context?
287     *
288     * @param type the class type
289     * @return the service instance or <tt>null</tt> if not already added.
290     */
291    <T> T hasService(Class<T> type);
292
293    /**
294     * Defers starting the service until {@link CamelContext} is (almost started) or started and has initialized all its prior services and routes.
295     * <p/>
296     * If {@link CamelContext} is already started then the service is started immediately.
297     *
298     * @param object the service
299     * @param stopOnShutdown whether to stop the service when this CamelContext shutdown. Setting this to <tt>true</tt> will keep a reference to the service in
300     *                       this {@link CamelContext} until the context is stopped. So do not use it for short lived services.
301     * @throws Exception can be thrown when starting the service, which is only attempted if {@link CamelContext} has already been started when calling this method.
302     */
303    void deferStartService(Object object, boolean stopOnShutdown) throws Exception;
304
305    /**
306     * Adds the given listener to be invoked when {@link CamelContext} have just been started.
307     * <p/>
308     * This allows listeners to do any custom work after the routes and other services have been started and are running.
309     * <p/><b>Important:</b> The listener will always be invoked, also if the {@link CamelContext} has already been
310     * started, see the {@link org.apache.camel.StartupListener#onCamelContextStarted(CamelContext, boolean)} method.
311     *
312     * @param listener the listener
313     * @throws Exception can be thrown if {@link CamelContext} is already started and the listener is invoked
314     *                   and cause an exception to be thrown
315     */
316    void addStartupListener(StartupListener listener) throws Exception;
317
318    // Component Management Methods
319    //-----------------------------------------------------------------------
320
321    /**
322     * Adds a component to the context.
323     *
324     * @param componentName the name the component is registered as
325     * @param component     the component
326     */
327    void addComponent(String componentName, Component component);
328
329    /**
330     * Is the given component already registered?
331     *
332     * @param componentName the name of the component
333     * @return the registered Component or <tt>null</tt> if not registered
334     */
335    Component hasComponent(String componentName);
336
337    /**
338     * Gets a component from the context by name.
339     * <p/>
340     * Notice the returned component will be auto-started. If you do not intend to do that
341     * then use {@link #getComponent(String, boolean, boolean)}.
342     *
343     * @param componentName the name of the component
344     * @return the component
345     */
346    Component getComponent(String componentName);
347
348    /**
349     * Gets a component from the context by name.
350     * <p/>
351     * Notice the returned component will be auto-started. If you do not intend to do that
352     * then use {@link #getComponent(String, boolean, boolean)}.
353     *
354     * @param name                 the name of the component
355     * @param autoCreateComponents whether or not the component should
356     *                             be lazily created if it does not already exist
357     * @return the component
358     */
359    Component getComponent(String name, boolean autoCreateComponents);
360
361    /**
362     * Gets a component from the context by name.
363     *
364     * @param name                 the name of the component
365     * @param autoCreateComponents whether or not the component should
366     *                             be lazily created if it does not already exist
367     * @param autoStart            whether to auto start the component if {@link CamelContext} is already started.
368     * @return the component
369     */
370    Component getComponent(String name, boolean autoCreateComponents, boolean autoStart);
371
372    /**
373     * Gets a component from the context by name and specifying the expected type of component.
374     *
375     * @param name          the name to lookup
376     * @param componentType the expected type
377     * @return the component
378     */
379    <T extends Component> T getComponent(String name, Class<T> componentType);
380
381    /**
382     * Gets a readonly list of names of the components currently registered
383     *
384     * @return a readonly list with the names of the the components
385     */
386    List<String> getComponentNames();
387
388    /**
389     * Removes a previously added component.
390     * <p/>
391     * The component being removed will be stopped first.
392     *
393     * @param componentName the component name to remove
394     * @return the previously added component or null if it had not been previously added.
395     */
396    Component removeComponent(String componentName);
397
398    // Endpoint Management Methods
399    //-----------------------------------------------------------------------
400
401    /**
402     * Gets the {@link org.apache.camel.spi.EndpointRegistry}
403     */
404    EndpointRegistry<String> getEndpointRegistry();
405
406    /**
407     * Resolves the given name to an {@link Endpoint} of the specified type.
408     * If the name has a singleton endpoint registered, then the singleton is returned.
409     * Otherwise, a new {@link Endpoint} is created and registered in the {@link org.apache.camel.spi.EndpointRegistry}.
410     *
411     * @param uri the URI of the endpoint
412     * @return the endpoint
413     */
414    Endpoint getEndpoint(String uri);
415
416    /**
417     * Resolves the given name to an {@link Endpoint} of the specified type.
418     * If the name has a singleton endpoint registered, then the singleton is returned.
419     * Otherwise, a new {@link Endpoint} is created and registered in the {@link org.apache.camel.spi.EndpointRegistry}.
420     *
421     * @param name         the name of the endpoint
422     * @param endpointType the expected type
423     * @return the endpoint
424     */
425    <T extends Endpoint> T getEndpoint(String name, Class<T> endpointType);
426
427    /**
428     * Returns a new {@link Collection} of all of the endpoints from the {@link org.apache.camel.spi.EndpointRegistry}
429     *
430     * @return all endpoints
431     */
432    Collection<Endpoint> getEndpoints();
433
434    /**
435     * Returns a new {@link Map} containing all of the endpoints from the {@link org.apache.camel.spi.EndpointRegistry}
436     *
437     * @return map of endpoints
438     */
439    Map<String, Endpoint> getEndpointMap();
440
441    /**
442     * Is the given endpoint already registered in the {@link org.apache.camel.spi.EndpointRegistry}
443     *
444     * @param uri the URI of the endpoint
445     * @return the registered endpoint or <tt>null</tt> if not registered
446     */
447    Endpoint hasEndpoint(String uri);
448
449    /**
450     * Adds the endpoint to the {@link org.apache.camel.spi.EndpointRegistry} using the given URI.
451     *
452     * @param uri      the URI to be used to resolve this endpoint
453     * @param endpoint the endpoint to be added to the registry
454     * @return the old endpoint that was previously registered or <tt>null</tt> if none was registered
455     * @throws Exception if the new endpoint could not be started or the old endpoint could not be stopped
456     */
457    Endpoint addEndpoint(String uri, Endpoint endpoint) throws Exception;
458
459    /**
460     * Removes the endpoint from the {@link org.apache.camel.spi.EndpointRegistry}.
461     * <p/>
462     * The endpoint being removed will be stopped first.
463     *
464     * @param endpoint  the endpoint
465     * @throws Exception if the endpoint could not be stopped
466     */
467    void removeEndpoint(Endpoint endpoint) throws Exception;
468
469    /**
470     * Removes all endpoints with the given URI from the {@link org.apache.camel.spi.EndpointRegistry}.
471     * <p/>
472     * The endpoints being removed will be stopped first.
473     *
474     * @param pattern an uri or pattern to match
475     * @return a collection of endpoints removed which could be empty if there are no endpoints found for the given <tt>pattern</tt>
476     * @throws Exception if at least one endpoint could not be stopped
477     * @see org.apache.camel.util.EndpointHelper#matchEndpoint(CamelContext, String, String) for pattern
478     */
479    Collection<Endpoint> removeEndpoints(String pattern) throws Exception;
480
481    /**
482     * Registers a {@link org.apache.camel.spi.EndpointStrategy callback} to allow you to do custom
483     * logic when an {@link Endpoint} is about to be registered to the {@link org.apache.camel.spi.EndpointRegistry}.
484     * <p/>
485     * When a callback is added it will be executed on the already registered endpoints allowing you to catch-up
486     *
487     * @param strategy callback to be invoked
488     */
489    void addRegisterEndpointCallback(EndpointStrategy strategy);
490
491    // Route Management Methods
492    //-----------------------------------------------------------------------
493
494    /**
495     * Method to signal to {@link CamelContext} that the process to initialize setup routes is in progress.
496     *
497     * @param done <tt>false</tt> to start the process, call again with <tt>true</tt> to signal its done.
498     * @see #isSetupRoutes()
499     */
500    void setupRoutes(boolean done);
501
502    /**
503     * Returns a list of the current route definitions
504     *
505     * @return list of the current route definitions
506     */
507    List<RouteDefinition> getRouteDefinitions();
508
509    /**
510     * Gets the route definition with the given id
511     *
512     * @param id id of the route
513     * @return the route definition or <tt>null</tt> if not found
514     */
515    RouteDefinition getRouteDefinition(String id);
516
517    /**
518     * Returns a list of the current REST definitions
519     *
520     * @return list of the current REST definitions
521     */
522    List<RestDefinition> getRestDefinitions();
523
524    /**
525     * Adds a collection of rest definitions to the context
526     *
527     * @param restDefinitions the rest(s) definition to add
528     */
529    void addRestDefinitions(Collection<RestDefinition> restDefinitions) throws Exception;
530
531    /**
532     * Sets a custom {@link org.apache.camel.spi.RestConfiguration}
533     *
534     * @param restConfiguration the REST configuration
535     */
536    void setRestConfiguration(RestConfiguration restConfiguration);
537
538    /**
539     * Gets the default REST configuration
540     *
541     * @return the configuration, or <tt>null</tt> if none has been configured.
542     */
543    RestConfiguration getRestConfiguration();
544    
545    /**
546     * Sets a custom {@link org.apache.camel.spi.RestConfiguration}
547     *
548     * @param restConfiguration the REST configuration
549     */
550    void addRestConfiguration(RestConfiguration restConfiguration);
551
552    /**
553     * Gets the REST configuration for the given component
554     *
555     * @param component the component name to get the configuration
556     * @param defaultIfNotFound determine if the default configuration is returned if there isn't a 
557     *        specific configuration for the given component  
558     * @return the configuration, or <tt>null</tt> if none has been configured.
559     */
560    RestConfiguration getRestConfiguration(String component, boolean defaultIfNotFound);
561    
562    /**
563     * Gets all the RestConfiguration's
564     */
565    Collection<RestConfiguration> getRestConfigurations();
566
567    /**
568     * Gets the service call configuration by the given name. If no name is given and there is only one configuration
569     * which matches the type then this configuration is returned.
570     *
571     * @param serviceName name of service, or <tt>null</tt> to return the default configuration
572     * @param type implementation of the configuration such as kubernetes, ribbon etc.
573     * @return the configuration, or <tt>null</tt> if no configuration has been registered
574     */
575    <T extends ServiceCallConfigurationDefinition> T getServiceCallConfiguration(String serviceName, Class<T> type);
576
577    /**
578     * Sets the default service call configuration
579     *
580     * @param configuration the configuration
581     */
582    void setServiceCallConfiguration(ServiceCallConfigurationDefinition configuration);
583
584    /**
585     * Adds the service call configuration
586     *
587     * @param serviceName name of the service
588     * @param configuration the configuration
589     */
590    void addServiceCallConfiguration(String serviceName, ServiceCallConfigurationDefinition configuration);
591
592    /**
593     * Returns the order in which the route inputs was started.
594     * <p/>
595     * The order may not be according to the startupOrder defined on the route.
596     * For example a route could be started manually later, or new routes added at runtime.
597     *
598     * @return a list in the order how routes was started
599     */
600    List<RouteStartupOrder> getRouteStartupOrder();
601
602    /**
603     * Returns the current routes in this context
604     *
605     * @return the current routes
606     */
607    List<Route> getRoutes();
608
609    /**
610     * Gets the route with the given id
611     *
612     * @param id id of the route
613     * @return the route or <tt>null</tt> if not found
614     */
615    Route getRoute(String id);
616
617    /**
618     * Gets the processor from any of the routes which with the given id
619     *
620     * @param id id of the processor
621     * @return the processor or <tt>null</tt> if not found
622     */
623    Processor getProcessor(String id);
624
625    /**
626     * Gets the processor from any of the routes which with the given id
627     *
628     * @param id id of the processor
629     * @param type the processor type
630     * @return the processor or <tt>null</tt> if not found
631     * @throws java.lang.ClassCastException is thrown if the type is not correct type
632     */
633    <T extends Processor> T getProcessor(String id, Class<T> type);
634
635    /**
636     * Gets the managed processor client api from any of the routes which with the given id
637     *
638     * @param id id of the processor
639     * @param type the managed processor type from the {@link org.apache.camel.api.management.mbean} package.
640     * @return the processor or <tt>null</tt> if not found
641     * @throws IllegalArgumentException if the type is not compliant
642     */
643    <T extends ManagedProcessorMBean> T getManagedProcessor(String id, Class<T> type);
644
645    /**
646     * Gets the managed route client api with the given route id
647     *
648     * @param routeId id of the route
649     * @param type the managed route type from the {@link org.apache.camel.api.management.mbean} package.
650     * @return the route or <tt>null</tt> if not found
651     * @throws IllegalArgumentException if the type is not compliant
652     */
653    <T extends ManagedRouteMBean> T getManagedRoute(String routeId, Class<T> type);
654
655    /**
656     * Gets the managed Camel context client api
657     */
658    ManagedCamelContextMBean getManagedCamelContext();
659
660    /**
661     * Gets the processor definition from any of the routes which with the given id
662     *
663     * @param id id of the processor definition
664     * @return the processor definition or <tt>null</tt> if not found
665     */
666    ProcessorDefinition getProcessorDefinition(String id);
667
668    /**
669     * Gets the processor definition from any of the routes which with the given id
670     *
671     * @param id id of the processor definition
672     * @param type the processor definition type
673     * @return the processor definition or <tt>null</tt> if not found
674     * @throws java.lang.ClassCastException is thrown if the type is not correct type
675     */
676    <T extends ProcessorDefinition> T getProcessorDefinition(String id, Class<T> type);
677
678    /**
679     * Adds a collection of routes to this context using the given builder
680     * to build them.
681     * <p/>
682     * <b>Important:</b> The added routes will <b>only</b> be started, if {@link CamelContext}
683     * is already started. You may want to check the state of {@link CamelContext} before
684     * adding the routes, using the {@link org.apache.camel.CamelContext#getStatus()} method.
685     * <p/>
686     * <b>Important: </b> Each route in the same {@link org.apache.camel.CamelContext} must have an <b>unique</b> route id.
687     * If you use the API from {@link org.apache.camel.CamelContext} or {@link org.apache.camel.model.ModelCamelContext} to add routes, then any
688     * new routes which has a route id that matches an old route, then the old route is replaced by the new route.
689     *
690     * @param builder the builder which will create the routes and add them to this context
691     * @throws Exception if the routes could not be created for whatever reason
692     */
693    void addRoutes(RoutesBuilder builder) throws Exception;
694
695    /**
696     * Loads a collection of route definitions from the given {@link java.io.InputStream}.
697     *
698     * @param is input stream with the route(s) definition to add
699     * @throws Exception if the route definitions could not be loaded for whatever reason
700     * @return the route definitions
701     */
702    RoutesDefinition loadRoutesDefinition(InputStream is) throws Exception;
703
704    /**
705     * Loads a collection of rest definitions from the given {@link java.io.InputStream}.
706     *
707     * @param is input stream with the rest(s) definition to add
708     * @throws Exception if the rest definitions could not be loaded for whatever reason
709     * @return the rest definitions
710     */
711    RestsDefinition loadRestsDefinition(InputStream is) throws Exception;
712    
713    /**
714     * Adds a collection of route definitions to the context
715     *
716     * @param routeDefinitions the route(s) definition to add
717     * @throws Exception if the route definitions could not be created for whatever reason
718     */
719    void addRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
720
721    /**
722     * Add a route definition to the context
723     *
724     * @param routeDefinition the route definition to add
725     * @throws Exception if the route definition could not be created for whatever reason
726     */
727    void addRouteDefinition(RouteDefinition routeDefinition) throws Exception;
728
729    /**
730     * Removes a collection of route definitions from the context - stopping any previously running
731     * routes if any of them are actively running
732     *
733     * @param routeDefinitions route(s) definitions to remove
734     * @throws Exception if the route definitions could not be removed for whatever reason
735     */
736    void removeRouteDefinitions(Collection<RouteDefinition> routeDefinitions) throws Exception;
737
738    /**
739     * Removes a route definition from the context - stopping any previously running
740     * routes if any of them are actively running
741     *
742     * @param routeDefinition route definition to remove
743     * @throws Exception if the route definition could not be removed for whatever reason
744     */
745    void removeRouteDefinition(RouteDefinition routeDefinition) throws Exception;
746
747    /**
748     * Starts the given route if it has been previously stopped
749     *
750     * @param route the route to start
751     * @throws Exception is thrown if the route could not be started for whatever reason
752     * @deprecated favor using {@link CamelContext#startRoute(String)}
753     */
754    @Deprecated
755    void startRoute(RouteDefinition route) throws Exception;
756
757    /**
758     * Starts all the routes which currently is not started.
759     *
760     * @throws Exception is thrown if a route could not be started for whatever reason
761     */
762    void startAllRoutes() throws Exception;
763
764    /**
765     * Starts the given route if it has been previously stopped
766     *
767     * @param routeId the route id
768     * @throws Exception is thrown if the route could not be started for whatever reason
769     */
770    void startRoute(String routeId) throws Exception;
771
772    /**
773     * Stops the given route.
774     *
775     * @param route the route to stop
776     * @throws Exception is thrown if the route could not be stopped for whatever reason
777     * @deprecated favor using {@link CamelContext#stopRoute(String)}
778     */
779    @Deprecated
780    void stopRoute(RouteDefinition route) throws Exception;
781
782    /**
783     * Stops the given route using {@link org.apache.camel.spi.ShutdownStrategy}.
784     *
785     * @param routeId the route id
786     * @throws Exception is thrown if the route could not be stopped for whatever reason
787     * @see #suspendRoute(String)
788     */
789    void stopRoute(String routeId) throws Exception;
790
791    /**
792     * Stops the given route using {@link org.apache.camel.spi.ShutdownStrategy} with a specified timeout.
793     *
794     * @param routeId the route id
795     * @param timeout  timeout
796     * @param timeUnit the unit to use
797     * @throws Exception is thrown if the route could not be stopped for whatever reason
798     * @see #suspendRoute(String, long, java.util.concurrent.TimeUnit)
799     */
800    void stopRoute(String routeId, long timeout, TimeUnit timeUnit) throws Exception;
801
802    /**
803     * Stops the given route using {@link org.apache.camel.spi.ShutdownStrategy} with a specified timeout 
804     * and optional abortAfterTimeout mode.
805     *
806     * @param routeId the route id
807     * @param timeout  timeout
808     * @param timeUnit the unit to use
809     * @param abortAfterTimeout should abort shutdown after timeout
810     * @return <tt>true</tt> if the route is stopped before the timeout
811     * @throws Exception is thrown if the route could not be stopped for whatever reason
812     * @see #suspendRoute(String, long, java.util.concurrent.TimeUnit)
813     */
814    boolean stopRoute(String routeId, long timeout, TimeUnit timeUnit, boolean abortAfterTimeout) throws Exception;
815    
816    /**
817     * Shutdown and <b>removes</b> the given route using {@link org.apache.camel.spi.ShutdownStrategy}.
818     *
819     * @param routeId the route id
820     * @throws Exception is thrown if the route could not be shutdown for whatever reason
821     * @deprecated use {@link #stopRoute(String)} and {@link #removeRoute(String)}
822     */
823    @Deprecated
824    void shutdownRoute(String routeId) throws Exception;
825
826    /**
827     * Shutdown and <b>removes</b> the given route using {@link org.apache.camel.spi.ShutdownStrategy} with a specified timeout.
828     *
829     * @param routeId  the route id
830     * @param timeout  timeout
831     * @param timeUnit the unit to use
832     * @throws Exception is thrown if the route could not be shutdown for whatever reason
833     * @deprecated use {@link #stopRoute(String, long, java.util.concurrent.TimeUnit)} and {@link #removeRoute(String)}
834     */
835    @Deprecated
836    void shutdownRoute(String routeId, long timeout, TimeUnit timeUnit) throws Exception;
837
838    /**
839     * Removes the given route (the route <b>must</b> be stopped before it can be removed).
840     * <p/>
841     * A route which is removed will be unregistered from JMX, have its services stopped/shutdown and the route
842     * definition etc. will also be removed. All the resources related to the route will be stopped and cleared.
843     * <p/>
844     * <b>Important:</b> When removing a route, the {@link Endpoint}s which are in the static cache of
845     * {@link org.apache.camel.spi.EndpointRegistry} and are <b>only</b> used by the route (not used by other routes)
846     * will also be removed. But {@link Endpoint}s which may have been created as part of routing messages by the route,
847     * and those endpoints are enlisted in the dynamic cache of {@link org.apache.camel.spi.EndpointRegistry} are
848     * <b>not</b> removed. To remove those dynamic kind of endpoints, use the {@link #removeEndpoints(String)} method.
849     * If not removing those endpoints, they will be kept in the dynamic cache of {@link org.apache.camel.spi.EndpointRegistry},
850     * but my eventually be removed (evicted) when they have not been in use for a longer period of time; and the
851     * dynamic cache upper limit is hit, and it evicts the least used endpoints.
852     * <p/>
853     * End users can use this method to remove unwanted routes or temporary routes which no longer is in demand.
854     *
855     * @param routeId the route id
856     * @return <tt>true</tt> if the route was removed, <tt>false</tt> if the route could not be removed because its not stopped
857     * @throws Exception is thrown if the route could not be shutdown for whatever reason
858     */
859    boolean removeRoute(String routeId) throws Exception;
860
861    /**
862     * Resumes the given route if it has been previously suspended
863     * <p/>
864     * If the route does <b>not</b> support suspension the route will be started instead
865     *
866     * @param routeId the route id
867     * @throws Exception is thrown if the route could not be resumed for whatever reason
868     */
869    void resumeRoute(String routeId) throws Exception;
870
871    /**
872     * Suspends the given route using {@link org.apache.camel.spi.ShutdownStrategy}.
873     * <p/>
874     * Suspending a route is more gently than stopping, as the route consumers will be suspended (if they support)
875     * otherwise the consumers will be stopped.
876     * <p/>
877     * By suspending the route services will be kept running (if possible) and therefore its faster to resume the route.
878     * <p/>
879     * If the route does <b>not</b> support suspension the route will be stopped instead
880     *
881     * @param routeId the route id
882     * @throws Exception is thrown if the route could not be suspended for whatever reason
883     */
884    void suspendRoute(String routeId) throws Exception;
885
886    /**
887     * Suspends the given route using {@link org.apache.camel.spi.ShutdownStrategy} with a specified timeout.
888     * <p/>
889     * Suspending a route is more gently than stopping, as the route consumers will be suspended (if they support)
890     * otherwise the consumers will be stopped.
891     * <p/>
892     * By suspending the route services will be kept running (if possible) and therefore its faster to resume the route.
893     * <p/>
894     * If the route does <b>not</b> support suspension the route will be stopped instead
895     *
896     * @param routeId  the route id
897     * @param timeout  timeout
898     * @param timeUnit the unit to use
899     * @throws Exception is thrown if the route could not be suspended for whatever reason
900     */
901    void suspendRoute(String routeId, long timeout, TimeUnit timeUnit) throws Exception;
902
903    /**
904     * Returns the current status of the given route
905     *
906     * @param routeId the route id
907     * @return the status for the route
908     */
909    ServiceStatus getRouteStatus(String routeId);
910
911    /**
912     * Indicates whether current thread is starting route(s).
913     * <p/>
914     * This can be useful to know by {@link LifecycleStrategy} or the likes, in case
915     * they need to react differently.
916     *
917     * @return <tt>true</tt> if current thread is starting route(s), or <tt>false</tt> if not.
918     */
919    boolean isStartingRoutes();
920
921    /**
922     * Indicates whether current thread is setting up route(s) as part of starting Camel from spring/blueprint.
923     * <p/>
924     * This can be useful to know by {@link LifecycleStrategy} or the likes, in case
925     * they need to react differently.
926     * <p/>
927     * As the startup procedure of {@link CamelContext} is slightly different when using plain Java versus
928     * Spring or Blueprint, then we need to know when Spring/Blueprint is setting up the routes, which
929     * can happen after the {@link CamelContext} itself is in started state, due the asynchronous event nature
930     * of especially Blueprint.
931     *
932     * @return <tt>true</tt> if current thread is setting up route(s), or <tt>false</tt> if not.
933     */
934    boolean isSetupRoutes();
935
936    // Properties
937    //-----------------------------------------------------------------------
938
939    /**
940     * Returns the type converter used to coerce types from one type to another
941     *
942     * @return the converter
943     */
944    TypeConverter getTypeConverter();
945
946    /**
947     * Returns the type converter registry where type converters can be added or looked up
948     *
949     * @return the type converter registry
950     */
951    TypeConverterRegistry getTypeConverterRegistry();
952
953    /**
954     * Returns the registry used to lookup components by name and type such as the Spring ApplicationContext,
955     * JNDI or the OSGi Service Registry
956     *
957     * @return the registry
958     */
959    Registry getRegistry();
960
961    /**
962     * Returns the registry used to lookup components by name and as the given type
963     *
964     * @param type the registry type such as {@link org.apache.camel.impl.JndiRegistry}
965     * @return the registry, or <tt>null</tt> if the given type was not found as a registry implementation
966     */
967    <T> T getRegistry(Class<T> type);
968
969    /**
970     * Returns the injector used to instantiate objects by type
971     *
972     * @return the injector
973     */
974    Injector getInjector();
975
976    /**
977     * Returns the management mbean assembler
978     *
979     * @return the mbean assembler
980     */
981    ManagementMBeanAssembler getManagementMBeanAssembler();
982
983    /**
984     * Returns the lifecycle strategies used to handle lifecycle notifications
985     *
986     * @return the lifecycle strategies
987     */
988    List<LifecycleStrategy> getLifecycleStrategies();
989
990    /**
991     * Adds the given lifecycle strategy to be used.
992     *
993     * @param lifecycleStrategy the strategy
994     */
995    void addLifecycleStrategy(LifecycleStrategy lifecycleStrategy);
996
997    /**
998     * Resolves a language for creating expressions
999     *
1000     * @param language name of the language
1001     * @return the resolved language
1002     */
1003    Language resolveLanguage(String language);
1004
1005    /**
1006     * Parses the given text and resolve any property placeholders - using {{key}}.
1007     *
1008     * @param text the text such as an endpoint uri or the likes
1009     * @return the text with resolved property placeholders
1010     * @throws Exception is thrown if property placeholders was used and there was an error resolving them
1011     */
1012    String resolvePropertyPlaceholders(String text) throws Exception;
1013    
1014    /**
1015     * Returns the configured property placeholder prefix token if and only if the context has
1016     * property placeholder abilities, otherwise returns {@code null}.
1017     * 
1018     * @return the prefix token or {@code null}
1019     */
1020    String getPropertyPrefixToken();
1021    
1022    /**
1023     * Returns the configured property placeholder suffix token if and only if the context has
1024     * property placeholder abilities, otherwise returns {@code null}.
1025     * 
1026     * @return the suffix token or {@code null}
1027     */
1028    String getPropertySuffixToken();
1029
1030    /**
1031     * Gets a readonly list with the names of the languages currently registered.
1032     *
1033     * @return a readonly list with the names of the the languages
1034     */
1035    List<String> getLanguageNames();
1036
1037    /**
1038     * Creates a new {@link ProducerTemplate} which is <b>started</b> and therefore ready to use right away.
1039     * <p/>
1040     * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
1041     * Why does Camel use too many threads with ProducerTemplate?</a>
1042     * <p/>
1043     * <b>Important:</b> Make sure to call {@link org.apache.camel.ProducerTemplate#stop()} when you are done using the template,
1044     * to clean up any resources.
1045     * <p/>
1046     * Will use cache size defined in Camel property with key {@link Exchange#MAXIMUM_CACHE_POOL_SIZE}.
1047     * If no key was defined then it will fallback to a default size of 1000.
1048     * You can also use the {@link org.apache.camel.ProducerTemplate#setMaximumCacheSize(int)} method to use a custom value
1049     * before starting the template.
1050     *
1051     * @return the template
1052     * @throws RuntimeCamelException is thrown if error starting the template
1053     */
1054    ProducerTemplate createProducerTemplate();
1055
1056    /**
1057     * Creates a new {@link ProducerTemplate} which is <b>started</b> and therefore ready to use right away.
1058     * <p/>
1059     * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
1060     * Why does Camel use too many threads with ProducerTemplate?</a>
1061     * <p/>
1062     * <b>Important:</b> Make sure to call {@link ProducerTemplate#stop()} when you are done using the template,
1063     * to clean up any resources.
1064     *
1065     * @param maximumCacheSize the maximum cache size
1066     * @return the template
1067     * @throws RuntimeCamelException is thrown if error starting the template
1068     */
1069    ProducerTemplate createProducerTemplate(int maximumCacheSize);
1070
1071    /**
1072     * Creates a new {@link FluentProducerTemplate} which is <b>started</b> and therefore ready to use right away.
1073     * <p/>
1074     * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
1075     * Why does Camel use too many threads with ProducerTemplate?</a>
1076     * <p/>
1077     * <b>Important:</b> Make sure to call {@link org.apache.camel.ProducerTemplate#stop()} when you are done using the template,
1078     * to clean up any resources.
1079     * <p/>
1080     * Will use cache size defined in Camel property with key {@link Exchange#MAXIMUM_CACHE_POOL_SIZE}.
1081     * If no key was defined then it will fallback to a default size of 1000.
1082     * You can also use the {@link org.apache.camel.FluentProducerTemplate#setMaximumCacheSize(int)} method to use a custom value
1083     * before starting the template.
1084     *
1085     * @return the template
1086     * @throws RuntimeCamelException is thrown if error starting the template
1087     */
1088    FluentProducerTemplate createFluentProducerTemplate();
1089
1090    /**
1091     * Creates a new {@link FluentProducerTemplate} which is <b>started</b> and therefore ready to use right away.
1092     * <p/>
1093     * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
1094     * Why does Camel use too many threads with ProducerTemplate?</a>
1095     * <p/>
1096     * <b>Important:</b> Make sure to call {@link FluentProducerTemplate#stop()} when you are done using the template,
1097     * to clean up any resources.
1098     *
1099     * @param maximumCacheSize the maximum cache size
1100     * @return the template
1101     * @throws RuntimeCamelException is thrown if error starting the template
1102     */
1103    FluentProducerTemplate createFluentProducerTemplate(int maximumCacheSize);
1104
1105    /**
1106     * Creates a new {@link ConsumerTemplate} which is <b>started</b> and therefore ready to use right away.
1107     * <p/>
1108     * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
1109     * Why does Camel use too many threads with ProducerTemplate?</a> as it also applies for ConsumerTemplate.
1110     * <p/>
1111     * <b>Important:</b> Make sure to call {@link ConsumerTemplate#stop()} when you are done using the template,
1112     * to clean up any resources.
1113     * <p/>
1114     * Will use cache size defined in Camel property with key {@link Exchange#MAXIMUM_CACHE_POOL_SIZE}.
1115     * If no key was defined then it will fallback to a default size of 1000.
1116     * You can also use the {@link org.apache.camel.ConsumerTemplate#setMaximumCacheSize(int)} method to use a custom value
1117     * before starting the template.
1118     *
1119     * @return the template
1120     * @throws RuntimeCamelException is thrown if error starting the template
1121     */
1122    ConsumerTemplate createConsumerTemplate();
1123
1124    /**
1125     * Creates a new {@link ConsumerTemplate} which is <b>started</b> and therefore ready to use right away.
1126     * <p/>
1127     * See this FAQ before use: <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">
1128     * Why does Camel use too many threads with ProducerTemplate?</a> as it also applies for ConsumerTemplate.
1129     * <p/>
1130     * <b>Important:</b> Make sure to call {@link ConsumerTemplate#stop()} when you are done using the template,
1131     * to clean up any resources.
1132     *
1133     * @param maximumCacheSize the maximum cache size
1134     * @return the template
1135     * @throws RuntimeCamelException is thrown if error starting the template
1136     */
1137    ConsumerTemplate createConsumerTemplate(int maximumCacheSize);
1138
1139    /**
1140     * Adds the given interceptor strategy
1141     *
1142     * @param interceptStrategy the strategy
1143     */
1144    void addInterceptStrategy(InterceptStrategy interceptStrategy);
1145
1146    /**
1147     * Gets the interceptor strategies
1148     *
1149     * @return the list of current interceptor strategies
1150     */
1151    List<InterceptStrategy> getInterceptStrategies();
1152
1153    /**
1154     * Gets the default error handler builder which is inherited by the routes
1155     *
1156     * @return the builder
1157     * @deprecated The return type will be switched to {@link ErrorHandlerFactory} in Camel 3.0
1158     */
1159    @Deprecated
1160    ErrorHandlerBuilder getErrorHandlerBuilder();
1161
1162    /**
1163     * Sets the default error handler builder which is inherited by the routes
1164     *
1165     * @param errorHandlerBuilder the builder
1166     */
1167    void setErrorHandlerBuilder(ErrorHandlerFactory errorHandlerBuilder);
1168
1169    /**
1170     * Gets the default shared thread pool for error handlers which
1171     * leverages this for asynchronous redelivery tasks.
1172     */
1173    ScheduledExecutorService getErrorHandlerExecutorService();
1174
1175    /**
1176     * Sets the data formats that can be referenced in the routes.
1177     *
1178     * @param dataFormats the data formats
1179     */
1180    void setDataFormats(Map<String, DataFormatDefinition> dataFormats);
1181
1182    /**
1183     * Gets the data formats that can be referenced in the routes.
1184     *
1185     * @return the data formats available
1186     */
1187    Map<String, DataFormatDefinition> getDataFormats();
1188
1189    /**
1190     * Resolve a data format given its name
1191     *
1192     * @param name the data format name or a reference to it in the {@link Registry}
1193     * @return the resolved data format, or <tt>null</tt> if not found
1194     */
1195    DataFormat resolveDataFormat(String name);
1196
1197    /**
1198     * Resolve a data format definition given its name
1199     *
1200     * @param name the data format definition name or a reference to it in the {@link Registry}
1201     * @return the resolved data format definition, or <tt>null</tt> if not found
1202     */
1203    DataFormatDefinition resolveDataFormatDefinition(String name);
1204
1205    /**
1206     * Gets the current data format resolver
1207     *
1208     * @return the resolver
1209     */
1210    DataFormatResolver getDataFormatResolver();
1211
1212    /**
1213     * Sets a custom data format resolver
1214     *
1215     * @param dataFormatResolver the resolver
1216     */
1217    void setDataFormatResolver(DataFormatResolver dataFormatResolver);
1218
1219    /**
1220     * Sets the properties that can be referenced in the camel context
1221     *
1222     * @param properties properties
1223     */
1224    void setProperties(Map<String, String> properties);
1225
1226    /**
1227     * Gets the properties that can be referenced in the camel context
1228     *
1229     * @return the properties
1230     */
1231    Map<String, String> getProperties();
1232
1233    /**
1234     * Gets the property value that can be referenced in the camel context
1235     *
1236     * @return the string value of property
1237     */
1238    String getProperty(String name);
1239    
1240    /**
1241     * Gets the default FactoryFinder which will be used for the loading the factory class from META-INF
1242     *
1243     * @return the default factory finder
1244     */
1245    FactoryFinder getDefaultFactoryFinder();
1246
1247    /**
1248     * Sets the factory finder resolver to use.
1249     *
1250     * @param resolver the factory finder resolver
1251     */
1252    void setFactoryFinderResolver(FactoryFinderResolver resolver);
1253
1254    /**
1255     * Gets the FactoryFinder which will be used for the loading the factory class from META-INF in the given path
1256     *
1257     * @param path the META-INF path
1258     * @return the factory finder
1259     * @throws NoFactoryAvailableException is thrown if a factory could not be found
1260     */
1261    FactoryFinder getFactoryFinder(String path) throws NoFactoryAvailableException;
1262
1263    /**
1264     * Returns the class resolver to be used for loading/lookup of classes.
1265     *
1266     * @return the resolver
1267     */
1268    ClassResolver getClassResolver();
1269
1270    /**
1271     * Returns the package scanning class resolver
1272     *
1273     * @return the resolver
1274     */
1275    PackageScanClassResolver getPackageScanClassResolver();
1276
1277    /**
1278     * Sets the class resolver to be use
1279     *
1280     * @param resolver the resolver
1281     */
1282    void setClassResolver(ClassResolver resolver);
1283
1284    /**
1285     * Sets the package scanning class resolver to use
1286     *
1287     * @param resolver the resolver
1288     */
1289    void setPackageScanClassResolver(PackageScanClassResolver resolver);
1290
1291    /**
1292     * Sets a pluggable service pool to use for {@link Producer} pooling.
1293     *
1294     * @param servicePool the pool
1295     */
1296    void setProducerServicePool(ServicePool<Endpoint, Producer> servicePool);
1297
1298    /**
1299     * Gets the service pool for {@link Producer} pooling.
1300     *
1301     * @return the service pool
1302     */
1303    ServicePool<Endpoint, Producer> getProducerServicePool();
1304    
1305    /**
1306     * Sets a pluggable service pool to use for {@link PollingConsumer} pooling.
1307     *
1308     * @param servicePool the pool
1309     */
1310    void setPollingConsumerServicePool(ServicePool<Endpoint, PollingConsumer> servicePool);
1311
1312    /**
1313     * Gets the service pool for {@link Producer} pooling.
1314     *
1315     * @return the service pool
1316     */
1317    ServicePool<Endpoint, PollingConsumer> getPollingConsumerServicePool();
1318    
1319    /**
1320     * Uses a custom node id factory when generating auto assigned ids to the nodes in the route definitions
1321     *
1322     * @param factory custom factory to use
1323     */
1324    void setNodeIdFactory(NodeIdFactory factory);
1325
1326    /**
1327     * Gets the node id factory
1328     *
1329     * @return the node id factory
1330     */
1331    NodeIdFactory getNodeIdFactory();
1332
1333    /**
1334     * Gets the management strategy
1335     *
1336     * @return the management strategy
1337     */
1338    ManagementStrategy getManagementStrategy();
1339
1340    /**
1341     * Sets the management strategy to use
1342     *
1343     * @param strategy the management strategy
1344     */
1345    void setManagementStrategy(ManagementStrategy strategy);
1346
1347    /**
1348     * Gets the default tracer
1349     *
1350     * @return the default tracer
1351     */
1352    InterceptStrategy getDefaultTracer();
1353
1354    /**
1355     * Sets a custom tracer to be used as the default tracer.
1356     * <p/>
1357     * <b>Note:</b> This must be set before any routes are created,
1358     * changing the default tracer for existing routes is not supported.
1359     *
1360     * @param tracer the custom tracer to use as default tracer
1361     */
1362    void setDefaultTracer(InterceptStrategy tracer);
1363
1364    /**
1365     * Gets the default backlog tracer
1366     *
1367     * @return the default backlog tracer
1368     */
1369    InterceptStrategy getDefaultBacklogTracer();
1370
1371    /**
1372     * Sets a custom backlog tracer to be used as the default backlog tracer.
1373     * <p/>
1374     * <b>Note:</b> This must be set before any routes are created,
1375     * changing the default backlog tracer for existing routes is not supported.
1376     *
1377     * @param backlogTracer the custom tracer to use as default backlog tracer
1378     */
1379    void setDefaultBacklogTracer(InterceptStrategy backlogTracer);
1380
1381    /**
1382     * Gets the default backlog debugger
1383     *
1384     * @return the default backlog debugger
1385     */
1386    InterceptStrategy getDefaultBacklogDebugger();
1387
1388    /**
1389     * Sets a custom backlog debugger to be used as the default backlog debugger.
1390     * <p/>
1391     * <b>Note:</b> This must be set before any routes are created,
1392     * changing the default backlog debugger for existing routes is not supported.
1393     *
1394     * @param backlogDebugger the custom debugger to use as default backlog debugger
1395     */
1396    void setDefaultBacklogDebugger(InterceptStrategy backlogDebugger);
1397
1398    /**
1399     * Disables using JMX as {@link org.apache.camel.spi.ManagementStrategy}.
1400     * <p/>
1401     * <b>Important:</b> This method must be called <b>before</b> the {@link CamelContext} is started.
1402     *
1403     * @throws IllegalStateException is thrown if the {@link CamelContext} is not in stopped state.
1404     */
1405    void disableJMX() throws IllegalStateException;
1406
1407    /**
1408     * Gets the inflight repository
1409     *
1410     * @return the repository
1411     */
1412    InflightRepository getInflightRepository();
1413
1414    /**
1415     * Sets a custom inflight repository to use
1416     *
1417     * @param repository the repository
1418     */
1419    void setInflightRepository(InflightRepository repository);
1420
1421    /**
1422     * Gets the {@link org.apache.camel.AsyncProcessor} await manager.
1423     *
1424     * @return the manager
1425     */
1426    AsyncProcessorAwaitManager getAsyncProcessorAwaitManager();
1427
1428    /**
1429     * Sets a custom  {@link org.apache.camel.AsyncProcessor} await manager.
1430     *
1431     * @param manager the manager
1432     */
1433    void setAsyncProcessorAwaitManager(AsyncProcessorAwaitManager manager);
1434
1435    /**
1436     * Gets the the application context class loader which may be helpful for running camel in other containers
1437     *
1438     * @return the application context class loader
1439     */
1440    ClassLoader getApplicationContextClassLoader();
1441
1442    /**
1443     * Sets the application context class loader
1444     *
1445     * @param classLoader the class loader
1446     */
1447    void setApplicationContextClassLoader(ClassLoader classLoader);
1448
1449    /**
1450     * Gets the current shutdown strategy
1451     *
1452     * @return the strategy
1453     */
1454    ShutdownStrategy getShutdownStrategy();
1455
1456    /**
1457     * Sets a custom shutdown strategy
1458     *
1459     * @param shutdownStrategy the custom strategy
1460     */
1461    void setShutdownStrategy(ShutdownStrategy shutdownStrategy);
1462
1463    /**
1464     * Gets the current {@link org.apache.camel.spi.ExecutorServiceManager}
1465     *
1466     * @return the manager
1467     */
1468    ExecutorServiceManager getExecutorServiceManager();
1469
1470    /**
1471     * Gets the current {@link org.apache.camel.spi.ExecutorServiceStrategy}
1472     *
1473     * @return the manager
1474     * @deprecated use {@link #getExecutorServiceManager()}
1475     */
1476    @Deprecated
1477    org.apache.camel.spi.ExecutorServiceStrategy getExecutorServiceStrategy();
1478
1479    /**
1480     * Sets a custom {@link org.apache.camel.spi.ExecutorServiceManager}
1481     *
1482     * @param executorServiceManager the custom manager
1483     */
1484    void setExecutorServiceManager(ExecutorServiceManager executorServiceManager);
1485
1486    /**
1487     * Gets the current {@link org.apache.camel.spi.ProcessorFactory}
1488     *
1489     * @return the factory, can be <tt>null</tt> if no custom factory has been set
1490     */
1491    ProcessorFactory getProcessorFactory();
1492
1493    /**
1494     * Sets a custom {@link org.apache.camel.spi.ProcessorFactory}
1495     *
1496     * @param processorFactory the custom factory
1497     */
1498    void setProcessorFactory(ProcessorFactory processorFactory);
1499
1500    /**
1501     * Gets the current {@link org.apache.camel.spi.MessageHistoryFactory}
1502     *
1503     * @return the factory
1504     */
1505    MessageHistoryFactory getMessageHistoryFactory();
1506
1507    /**
1508     * Sets a custom {@link org.apache.camel.spi.MessageHistoryFactory}
1509     *
1510     * @param messageHistoryFactory the custom factory
1511     */
1512    void setMessageHistoryFactory(MessageHistoryFactory messageHistoryFactory);
1513
1514    /**
1515     * Gets the current {@link Debugger}
1516     *
1517     * @return the debugger
1518     */
1519    Debugger getDebugger();
1520
1521    /**
1522     * Sets a custom {@link Debugger}
1523     *
1524     * @param debugger the debugger
1525     */
1526    void setDebugger(Debugger debugger);
1527
1528    /**
1529     * Gets the current {@link UuidGenerator}
1530     *
1531     * @return the uuidGenerator
1532     */
1533    UuidGenerator getUuidGenerator();
1534    
1535    /**
1536     * Sets a custom {@link UuidGenerator} (should only be set once) 
1537     *
1538     * @param uuidGenerator the UUID Generator
1539     */
1540    void setUuidGenerator(UuidGenerator uuidGenerator);
1541
1542    /**
1543     * Whether or not type converters should be loaded lazy
1544     *
1545     * @return <tt>true</tt> to load lazy, <tt>false</tt> to load on startup
1546     * @deprecated this option is no longer supported, will be removed in a future Camel release.
1547     */
1548    @Deprecated
1549    Boolean isLazyLoadTypeConverters();
1550
1551    /**
1552     * Sets whether type converters should be loaded lazy
1553     *
1554     * @param lazyLoadTypeConverters <tt>true</tt> to load lazy, <tt>false</tt> to load on startup
1555     * @deprecated this option is no longer supported, will be removed in a future Camel release.
1556     */
1557    @Deprecated
1558    void setLazyLoadTypeConverters(Boolean lazyLoadTypeConverters);
1559
1560    /**
1561     * Whether or not type converter statistics is enabled.
1562     * <p/>
1563     * By default the type converter utilization statistics is disabled.
1564     * <b>Notice:</b> If enabled then there is a slight performance impact under very heavy load.
1565     *
1566     * @return <tt>true</tt> if enabled, <tt>false</tt> if disabled (default).
1567     */
1568    Boolean isTypeConverterStatisticsEnabled();
1569
1570    /**
1571     * Sets whether or not type converter statistics is enabled.
1572     * <p/>
1573     * By default the type converter utilization statistics is disabled.
1574     * <b>Notice:</b> If enabled then there is a slight performance impact under very heavy load.
1575     * <p/>
1576     * You can enable/disable the statistics at runtime using the
1577     * {@link org.apache.camel.spi.TypeConverterRegistry#getStatistics()#setTypeConverterStatisticsEnabled(Boolean)} method,
1578     * or from JMX on the {@link org.apache.camel.api.management.mbean.ManagedTypeConverterRegistryMBean} mbean.
1579     *
1580     * @param typeConverterStatisticsEnabled <tt>true</tt> to enable, <tt>false</tt> to disable
1581     */
1582    void setTypeConverterStatisticsEnabled(Boolean typeConverterStatisticsEnabled);
1583
1584    /**
1585     * Whether or not <a href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a> logging is being enabled.
1586     *
1587     * @return <tt>true</tt> if MDC logging is enabled
1588     */
1589    Boolean isUseMDCLogging();
1590
1591    /**
1592     * Set whether <a href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a> is enabled.
1593     *
1594     * @param useMDCLogging <tt>true</tt> to enable MDC logging, <tt>false</tt> to disable
1595     */
1596    void setUseMDCLogging(Boolean useMDCLogging);
1597
1598    /**
1599     * Whether or not breadcrumb is enabled.
1600     *
1601     * @return <tt>true</tt> if breadcrumb is enabled
1602     */
1603    Boolean isUseBreadcrumb();
1604
1605    /**
1606     * Set whether breadcrumb is enabled.
1607     *
1608     * @param useBreadcrumb <tt>true</tt> to enable breadcrumb, <tt>false</tt> to disable
1609     */
1610    void setUseBreadcrumb(Boolean useBreadcrumb);
1611
1612    /**
1613     * Resolves a component's default name from its java type.
1614     * <p/>
1615     * A component may be used with a non default name such as <tt>activemq</tt>, <tt>wmq</tt> for the JMS component.
1616     * This method can resolve the default component name by its java type.
1617     *
1618     * @param javaType the FQN name of the java type
1619     * @return the default component name.
1620     */
1621    String resolveComponentDefaultName(String javaType);
1622
1623    /**
1624     * Find information about all the Camel components available in the classpath and {@link org.apache.camel.spi.Registry}.
1625     *
1626     * @return a map with the component name, and value with component details.
1627     * @throws LoadPropertiesException is thrown if error during classpath discovery of the components
1628     * @throws IOException is thrown if error during classpath discovery of the components
1629     */
1630    Map<String, Properties> findComponents() throws LoadPropertiesException, IOException;
1631
1632    /**
1633     * Find information about all the EIPs from camel-core.
1634     *
1635     * @return a map with node id, and value with EIP details.
1636     * @throws LoadPropertiesException is thrown if error during classpath discovery of the EIPs
1637     * @throws IOException is thrown if error during classpath discovery of the EIPs
1638     */
1639    Map<String, Properties> findEips() throws LoadPropertiesException, IOException;
1640
1641    /**
1642     * Returns the HTML documentation for the given Camel component
1643     *
1644     * @return the HTML or <tt>null</tt> if the component is <b>not</b> built with HTML document included.
1645     */
1646    String getComponentDocumentation(String componentName) throws IOException;
1647
1648    /**
1649     * Returns the JSON schema representation of the component and endpoint parameters for the given component name.
1650     *
1651     * @return the json or <tt>null</tt> if the component is <b>not</b> built with JSon schema support
1652     */
1653    String getComponentParameterJsonSchema(String componentName) throws IOException;
1654
1655    /**
1656     * Returns the JSON schema representation of the {@link DataFormat} parameters for the given data format name.
1657     *
1658     * @return the json or <tt>null</tt> if the data format does not exist
1659     */
1660    String getDataFormatParameterJsonSchema(String dataFormatName) throws IOException;
1661
1662    /**
1663     * Returns the JSON schema representation of the {@link Language} parameters for the given language name.
1664     *
1665     * @return the json or <tt>null</tt> if the language does not exist
1666     */
1667    String getLanguageParameterJsonSchema(String languageName) throws IOException;
1668
1669    /**
1670     * Returns the JSON schema representation of the EIP parameters for the given EIP name.
1671     *
1672     * @return the json or <tt>null</tt> if the EIP does not exist
1673     */
1674    String getEipParameterJsonSchema(String eipName) throws IOException;
1675
1676    /**
1677     * Returns a JSON schema representation of the EIP parameters for the given EIP by its id.
1678     *
1679     * @param nameOrId the name of the EIP ({@link NamedNode#getShortName()} or a node id to refer to a specific node from the routes.
1680     * @param includeAllOptions whether to include non configured options also (eg default options)
1681     * @return the json or <tt>null</tt> if the eipName or the id was not found
1682     */
1683    String explainEipJson(String nameOrId, boolean includeAllOptions);
1684
1685    /**
1686     * Returns a JSON schema representation of the component parameters (not endpoint parameters) for the given component by its id.
1687     *
1688     * @param componentName the name of the component.
1689     * @param includeAllOptions whether to include non configured options also (eg default options)
1690     * @return the json or <tt>null</tt> if the component was not found
1691     */
1692    String explainComponentJson(String componentName, boolean includeAllOptions);
1693
1694    /**
1695     * Returns a JSON schema representation of the component parameters (not endpoint parameters) for the given component by its id.
1696     *
1697     * @param dataFormat the data format instance.
1698     * @param includeAllOptions whether to include non configured options also (eg default options)
1699     * @return the json
1700     */
1701    String explainDataFormatJson(String dataFormatName, DataFormat dataFormat, boolean includeAllOptions);
1702
1703    /**
1704     * Returns a JSON schema representation of the endpoint parameters for the given endpoint uri.
1705     *
1706     * @param uri the endpoint uri
1707     * @param includeAllOptions whether to include non configured options also (eg default options)
1708     * @return the json or <tt>null</tt> if uri parameters is invalid, or the component is <b>not</b> built with JSon schema support
1709     */
1710    String explainEndpointJson(String uri, boolean includeAllOptions);
1711
1712    /**
1713     * Creates a JSON representation of all the <b>static</b> and <b>dynamic</b> configured endpoints defined in the given route(s).
1714     *
1715     * @param routeId for a particular route, or <tt>null</tt> for all routes
1716     * @return a JSON string
1717     */
1718    String createRouteStaticEndpointJson(String routeId);
1719
1720    /**
1721     * Creates a JSON representation of all the <b>static</b> (and possible <b>dynamic</b>) configured endpoints defined in the given route(s).
1722     *
1723     * @param routeId for a particular route, or <tt>null</tt> for all routes
1724     * @param includeDynamic whether to include dynamic endpoints
1725     * @return a JSON string
1726     */
1727    String createRouteStaticEndpointJson(String routeId, boolean includeDynamic);
1728
1729    /**
1730     * Gets the {@link StreamCachingStrategy} to use.
1731     */
1732    StreamCachingStrategy getStreamCachingStrategy();
1733
1734    /**
1735     * Sets a custom {@link StreamCachingStrategy} to use.
1736     */
1737    void setStreamCachingStrategy(StreamCachingStrategy streamCachingStrategy);
1738
1739    /**
1740     * Gets the {@link UnitOfWorkFactory} to use.
1741     */
1742    UnitOfWorkFactory getUnitOfWorkFactory();
1743
1744    /**
1745     * Sets a custom {@link UnitOfWorkFactory} to use.
1746     */
1747    void setUnitOfWorkFactory(UnitOfWorkFactory unitOfWorkFactory);
1748
1749    /**
1750     * Gets the {@link org.apache.camel.spi.RuntimeEndpointRegistry} to use, or <tt>null</tt> if none is in use.
1751     */
1752    RuntimeEndpointRegistry getRuntimeEndpointRegistry();
1753
1754    /**
1755     * Sets a custom {@link org.apache.camel.spi.RuntimeEndpointRegistry} to use.
1756     */
1757    void setRuntimeEndpointRegistry(RuntimeEndpointRegistry runtimeEndpointRegistry);
1758
1759    /**
1760     * Gets the {@link org.apache.camel.spi.RestRegistry} to use
1761     */
1762    RestRegistry getRestRegistry();
1763
1764    /**
1765     * Sets a custom {@link org.apache.camel.spi.RestRegistry} to use.
1766     */
1767    void setRestRegistry(RestRegistry restRegistry);
1768
1769    /**
1770     * Adds the given route policy factory
1771     *
1772     * @param routePolicyFactory the factory
1773     */
1774    void addRoutePolicyFactory(RoutePolicyFactory routePolicyFactory);
1775
1776    /**
1777     * Gets the route policy factories
1778     *
1779     * @return the list of current route policy factories
1780     */
1781    List<RoutePolicyFactory> getRoutePolicyFactories();
1782
1783    /**
1784     * Returns the JAXB Context factory used to create Models.
1785     *
1786     * @return the JAXB Context factory used to create Models.
1787     */
1788    ModelJAXBContextFactory getModelJAXBContextFactory();
1789
1790    /**
1791     * Sets a custom JAXB Context factory to be used
1792     *
1793     * @param modelJAXBContextFactory a JAXB Context factory
1794     */
1795    void setModelJAXBContextFactory(ModelJAXBContextFactory modelJAXBContextFactory);
1796
1797}