[2/3] camel git commit: Added controlbus component docs to Gitbook

[ac...@apache.org]

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 <an...@gmail.com>
Authored: Mon Jun 13 10:34:41 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
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)