[[ControlBus-ControlBus]]
ControlBus
^^^^^^^^^^

The http://www.eaipatterns.com/ControlBus.html[Control Bus] from the
link:enterprise-integration-patterns.html[EIP patterns] allows for the
integration system to be monitored and managed from within the
framework.

image:http://www.eaipatterns.com/img/ControlBus.gif[image]

Use a Control Bus to manage an enterprise integration system. The
Control Bus uses the same messaging mechanism used by the application
data, but uses separate channels to transmit data that is relevant to
the management of components involved in the message flow.

In Camel you can manage and monitor using link:camel-jmx.html[JMX], or
by using a Java API from the `CamelContext`, or from the
`org.apache.camel.api.management` package, +
 or use the event notifier which has an example
link:eventnotifier-to-log-details-about-all-sent-exchanges.html[here].

From Camel 2.11 onwards we have introduced a new
link:controlbus-component.html[ControlBus Component] that allows you to
send messages to a control bus link:endpoint.html[Endpoint] that reacts
accordingly.

[[ControlBus-ControlBusComponent]]
ControlBus Component
~~~~~~~~~~~~~~~~~~~~

*Available as of Camel 2.11*

The *controlbus:* component provides easy management of Camel
applications based on the link:controlbus.html[Control Bus] EIP
pattern. 
For example, by sending a message to an link:endpoint.html[Endpoint]
you can control the lifecycle of routes, or gather performance
statistics.

[source,java]
----------------------------
controlbus:command[?options]
----------------------------

Where *command* can be any string to identify which type of command to
use.

[[ControlBus-Commands]]
Commands
^^^^^^^^

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|Command |Description

|`route` |To control routes using the `routeId` and `action` parameter.

|`language` |Allows you to specify a link:language.html[Language] to use for
evaluating the message body. If there is any result from the evaluation,
then the result is put in the message body.
|=======================================================================

[[ControlBus-Options]]
Options
^^^^^^^


// component options: START
The Control Bus component has no options.
// component options: END



// endpoint options: START
The Control Bus component supports 7 endpoint options which are listed below:

{% raw %}
[width="100%",cols="2,1,1m,1m,5",options="header"]
|=======================================================================
| Name | Group | Default | Java Type | Description
| command | producer |  | String | *Required* Command can be either route or language
| language | producer |  | Language | Allows you to specify the name of a Language to use for evaluating the message body. If there is any result from the evaluation then the result is put in the message body.
| action | producer |  | String | To denote an action that can be either: start stop or status. To either start or stop a route or to get the status of the route as output in the message body. You can use suspend and resume from Camel 2.11.1 onwards to either suspend or resume a route. And from Camel 2.11.1 onwards you can use stats to get performance statics returned in XML format; the routeId option can be used to define which route to get the performance stats for if routeId is not defined then you get statistics for the entire CamelContext.
| async | producer | false | boolean | Whether to execute the control bus task asynchronously. Important: If this option is enabled then any result from the task is not set on the Exchange. This is only possible if executing tasks synchronously.
| loggingLevel | producer | INFO | LoggingLevel | Logging level used for logging when task is done or if any exceptions occurred during processing the task.
| routeId | producer |  | String | To specify a route by its id. The special keyword current indicates the current route.
| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
|=======================================================================
{% endraw %}
// endpoint options: END


You can append query options to the URI in the following format,
`?option=value&option=value&...`

[[ControlBus-Samples]]
Samples
^^^^^^^

[[ControlBus-Usingroutecommand]]
Using route command
+++++++++++++++++++

The route command allows you to do common tasks on a given route very
easily, for example to start a route, you can send an empty message to
this endpoint:

[source,java]
---------------------------------------------------------------------
template.sendBody("controlbus:route?routeId=foo&action=start", null);
---------------------------------------------------------------------

To get the status of the route, you can do:

[source,java]
-------------------------------------------------------------------------------------------------------
String status = template.requestBody("controlbus:route?routeId=foo&action=status", null, String.class);
-------------------------------------------------------------------------------------------------------

[[ControlBus-Gettingperformancestatistics]]
Getting performance statistics

*Available as of Camel 2.11.1*

This requires JMX to be enabled (is by default) then you can get the
performance statics per route, or for the
link:camelcontext.html[CamelContext]. For example to get the statics for
a route named foo, we can do:

[source,java]
---------------------------------------------------------------------------------------------------
String xml = template.requestBody("controlbus:route?routeId=foo&action=stats", null, String.class);
---------------------------------------------------------------------------------------------------

The returned statics is in XML format. Its the same data you can get
from JMX with the `dumpRouteStatsAsXml` operation on the
`ManagedRouteMBean`.

To get statics for the entire link:camelcontext.html[CamelContext] you
just omit the routeId parameter as shown below:

[source,java]
---------------------------------------------------------------------------------------
String xml = template.requestBody("controlbus:route?action=stats", null, String.class);
---------------------------------------------------------------------------------------

[[ControlBus-Usinglanguage]]
Using link:simple.html[Simple] language
+++++++++++++++++++++++++++++++++++++++

You can use the link:simple.html[Simple] language with the control bus,
for example to stop a specific route, you can send a message to the
`"controlbus:language:simple"` endpoint containing the following
message:

[source,java]
----------------------------------------------------------------------------------------
template.sendBody("controlbus:language:simple", "${camelContext.stopRoute('myRoute')}");
----------------------------------------------------------------------------------------

As this is a void operation, no result is returned. However, if you want
the route status you can do:

[source,java]
------------------------------------------------------------------------------------------------------------------------------
String status = template.requestBody("controlbus:language:simple", "${camelContext.getRouteStatus('myRoute')}", String.class);
------------------------------------------------------------------------------------------------------------------------------

*Notice:* its easier to use the `route` command to control lifecycle of
routes. The `language` command allows you to execute a language script
that has stronger powers such as link:groovy.html[Groovy] or to some
extend the link:simple.html[Simple] language.

For example to shutdown Camel itself you can do:

[source,java]
-------------------------------------------------------------------------------------
template.sendBody("controlbus:language:simple?async=true", "${camelContext.stop()}");
-------------------------------------------------------------------------------------

Notice we use `async=true` to stop Camel asynchronously as otherwise we
would be trying to stop Camel while it was in-flight processing the
message we sent to the control bus component.

TIP:You can also use other languages such as link:groovy.html[Groovy], etc.

[[ControlBus-SeeAlso]]
See Also
^^^^^^^^

* link:configuring-camel.html[Configuring Camel]
* link:component.html[Component]
* link:endpoint.html[Endpoint]
* link:getting-started.html[Getting Started]

* link:controlbus.html[ControlBus] EIP
* link:jmx.html[JMX] Component
* Using link:camel-jmx.html[JMX] with Camel

[[ControlBus-UsingThisPattern]]
Using This Pattern
++++++++++++++++++

If you would like to use this EIP Pattern then please read the
link:getting-started.html[Getting Started], you may also find the
link:architecture.html[Architecture] useful particularly the description
of link:endpoint.html[Endpoint] and link:uris.html[URIs]. Then you could
try out some of the link:examples.html[Examples] first before trying
this pattern out.
