Added controlbus component docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/d2418110 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/d2418110 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/d2418110 Branch: refs/heads/master Commit: d241811082fc5d963176e314abe88db0e59724db Parents: 3f72d00 Author: Andrea Cosentino <[email protected]> Authored: Mon Jun 13 10:34:41 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Mon Jun 13 10:44:12 2016 +0200 ---------------------------------------------------------------------- camel-core/src/main/docs/controlbus.adoc | 211 ++++++++++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 212 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/d2418110/camel-core/src/main/docs/controlbus.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/controlbus.adoc b/camel-core/src/main/docs/controlbus.adoc new file mode 100644 index 0000000..5aa3cea --- /dev/null +++ b/camel-core/src/main/docs/controlbus.adoc @@ -0,0 +1,211 @@ +[[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 8 endpoint options which are listed below: + +{% raw %} +[width="100%",cols="2s,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. +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange. +| 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. http://git-wip-us.apache.org/repos/asf/camel/blob/d2418110/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 41c8482..3b40998 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -78,6 +78,7 @@ * [Binding](binding.adoc) * [Browse](browse.adoc) * [Class](class.adoc) + * [Controlbus](controlbus.adoc) * [Mock](mock.adoc) * [Properties](properties.adoc)
