This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 0baf58259c185c3a8a48a0e96ffed5a637ea0c8e
Author: Tadayoshi Sato <sato.tadayo...@gmail.com>
AuthorDate: Mon Dec 10 15:17:09 2018 +0900
CAMEL-11497: Migrate user guide - Configuring routes startup ordering and
autostartup
---
...ing-route-startup-ordering-and-autostartup.adoc | 237 +++++++++++++++++++++
docs/user-manual/en/getting-started.adoc | 2 +-
docs/user-manual/en/graceful-shutdown.adoc | 4 +-
3 files changed, 240 insertions(+), 3 deletions(-)
diff --git
a/docs/user-manual/en/configuring-route-startup-ordering-and-autostartup.adoc
b/docs/user-manual/en/configuring-route-startup-ordering-and-autostartup.adoc
new file mode 100644
index 0000000..b7dc5d0
--- /dev/null
+++
b/docs/user-manual/en/configuring-route-startup-ordering-and-autostartup.adoc
@@ -0,0 +1,237 @@
+[[Configuringroutestartuporderingandautostartup-Configuringroutesstartuporderingandautostartup]]
+=== Configuring routes startup ordering and autostartup
+
+*Available as of Camel 2.1*
+
+Camel now supports configuring two aspects:
+
+* auto startup
+* order of starting routes
+
+[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherCamelshouldbeautostartedornotinXMLDSL]]
+==== Configuring whether Camel should be auto started or not in XML DSL
+
+The old option `shouldStartContext` have been removed and replaced with
+this new `autoStartup` option instead. What it allows is to configure
+Camel to *not* auto start when Spring starts.
+
+For example the route below we have configured `autoStartup=false` to
+prevent Camel starting when Spring starts.
+
+[source,xml]
+----
+ <camelContext id="myCamel" xmlns="http://camel.apache.org/schema/spring";
autoStartup="false">
+ <route>
+ <from uri="direct:start"/>
+ <to uri="mock:result"/>
+ </route>
+ </camelContext>
+----
+
+So how do you start Camel then?
+
+The `autoStartup` option on the `<camelContext>` is only used once, so you
+can manually start Camel later by invoking its `start` method as shown
+below:
+
+[source,java]
+----
+ ApplicationContext ac = ...
+ SpringCamelContext camel = (SpringCamelContext) ac.getBean("myCamel");
+
+ // now start Camel manually
+ camel.start();
+----
+
+[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherarouteshouldbestartedornotinXMLDSL]]
+==== Configuring whether a route should be started or not in XML DSL
+
+You can use the `autoStartup` option to configure if a given route
+should be started when Camel starts. By default a route is auto started.
+
+You can disable or enable it as follows.
+
+In XML DSL you define it as follows:
+
+[source,xml]
+----
+<route autoStartup="false">
+ <from uri="activemq:queue:special"/>
+ <to uri="file://backup"/>
+</route>
+----
+
+And to explicit state it should be started:
+
+[source,xml]
+----
+<route autoStartup="true">
+ <from uri="activemq:queue:special"/>
+ <to uri="file://backup"/>
+</route>
+----
+
+[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherarouteshouldbestartedornotinJavaDSL]]
+==== Configuring whether a route should be started or not in Java DSL
+
+You can use the `autoStartup` option to configure if a given route
+should be started when Camel starts. By default a route is auto started.
+
+You can disable or enable it as follows:
+
+[source,java]
+----
+from("activemq:queue:special").noAutoStartup().to("file://backup");
+----
+
+[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherarouteshouldbestartedornotusingabooleanorStringinJavaDSL]]
+==== Configuring whether a route should be started or not, using a boolean or
String, in Java DSL
+
+*Available as of Camel 2.9*
+
+To startup based on a boolean, String or
+<<properties-component,Property>>, do one of the following:
+
+[source,java]
+----
+boolean startupRoute = true;
+from("activemq:queue:special").autoStartup(startupRoute).to("file://backup");
+...
+String startupRoute = "true";
+from("activemq:queue:special").autoStartup(startupRoute).to("file://backup");
+...
+from("activemq:queue:special").autoStartup("{{startupRouteProperty}}").to("file://backup");
+----
+
+[[Configuringroutestartuporderingandautostartup-Configuringstartingorderforroutes]]
+==== Configuring starting order for routes
+
+You can also configure the order in which routes are started. Previously
+Camel started the routes in a non deterministic order. Now you have fine
+grained control in which order the routes should be started. There is a
+new attribute `startupOrder` which is an `Integer` that states the order.
+Camel then sorts the routes before starting time. The routes with the
+lowest `startupOrder` is started first. All `startupOrder` defined must
+be unique among all routes in your
+link:camelcontext.adoc[CamelContext].
+
+You should also use numbers that are lower than 1000, as routes without
+an explicit `startupOrder` define will have a number starting from 1000
+auto assigned. So view numbers from 1000 upwards as reserved internally
+for Camel itself.
+
+In terms of the `startupOrder` there are no strict rules that it must
+start from 1 and increment by 1. You can for example use: 100, 200, 205,
+89 if you like. Only rule of thumb is that the numbers must be unique.
+
+[[Configuringroutestartuporderingandautostartup-Whydoyouwanttocontrolthestartingorder]]
+==== Why do you want to control the starting order?
+
+It can help in cases where routes are inter dependent on each other and
+also help with graceful shutting down Camel as Camel can stop the routes
+in the correct order as well.
+
+[NOTE]
+====
+**Stopping routes**
+
+*Camel 2.2:* Camel will stop the routes in the *same* order that they
+were started.
+
+*Camel 2.3:* Camel will stop the routes in the *reverse* order that they
+were started.
+====
+
+[[Configuringroutestartuporderingandautostartup-Examples]]
+==== Examples
+
+Let's try a couple of examples.
+
+[[Configuringroutestartuporderingandautostartup-Simpleexample]]
+==== Simple example
+
+[source,java]
+----
+ from("seda:foo").startupOrder(1).to("mock:result");
+ from("direct:start").startupOrder(2).to("seda:foo");
+----
+
+And the same example with XML DSL:
+
+[source,xml]
+----
+ <route startupOrder="1">
+ <from uri="seda:foo"/>
+ <to uri="mock:result"/>
+ </route>
+
+ <route startupOrder="2">
+ <from uri="direct:start"/>
+ <to uri="seda:foo"/>
+ </route>
+----
+
+In this example we have two routes in which we have started that the
+`direct:start` route should be started *after* the `seda:foo` route. +
+As `direct:start` is consider the input and we want that `seda:foo`
+route to be up and running beforehand.
+
+You can also mix and match routes with and without `startupOrder`
+define.
+
+[[Configuringroutestartuporderingandautostartup-RouteswithstartupOrdermixedwithrouteswithout]]
+===== Routes with startupOrder mixed with routes without
+
+[source,java]
+----
+ from("seda:foo").startupOrder(1).to("mock:result");
+ from("direct:start").startupOrder(2).to("seda:foo");
+
+ from("direct:bar").to("seda:bar");
+----
+
+And the same example with XML DSL:
+
+[source,xml]
+----
+ <route startupOrder="1">
+ <from uri="seda:foo"/>
+ <to uri="mock:result"/>
+ </route>
+
+ <route startupOrder="2">
+ <from uri="direct:start"/>
+ <to uri="seda:foo"/>
+ </route>
+
+ <route>
+ <from uri="direct:bar"/>
+ <to uri="seda:bar"/>
+ </route>
+----
+
+In the route above we have *not* define a `startupOrder` on the last
+route `direct:bar` in which Camel will auto assign a number for it, in
+which this case will be 1000. So therefore the route will be started
+last.
+
+So you can use this to your advantage to only assign a `startupOrder` on
+the routes which really needs it.
+
+[[Configuringroutestartuporderingandautostartup-Shutdown]]
+==== Shutdown
+
+*Camel 2.2:* Camel will shutdown the routes in the *same* order that
+they were started.
+
+*Camel 2.3:* Camel will shutdown the routes in the *reverse* order that
+they were started.
+
+See also link:graceful-shutdown.adoc[Graceful Shutdown].
+
+[[Configuringroutestartuporderingandautostartup-Seealso]]
+==== See also
+
+* link:configuring-camel.adoc[Configuring Camel]
+* link:graceful-shutdown.adoc[Graceful Shutdown]
+* link:user-guide.html[User Guide]
diff --git a/docs/user-manual/en/getting-started.adoc
b/docs/user-manual/en/getting-started.adoc
index 8a105cf..4715e4f 100644
--- a/docs/user-manual/en/getting-started.adoc
+++ b/docs/user-manual/en/getting-started.adoc
@@ -24,7 +24,7 @@ Working with CamelContexts and RouteBuilders
To get started with Camel:
1. Create a CamelContext.
-2. Optionally, link:configuring-camel.html[configure components or
+2. Optionally, link:configuring-camel.adoc[configure components or
endpoints].
3. Add whatever routing rules you wish using the DSL and
RouteBuilder or using
diff --git a/docs/user-manual/en/graceful-shutdown.adoc
b/docs/user-manual/en/graceful-shutdown.adoc
index b1a3dc1..ff8c232 100644
--- a/docs/user-manual/en/graceful-shutdown.adoc
+++ b/docs/user-manual/en/graceful-shutdown.adoc
@@ -128,7 +128,7 @@
context.getShutdownStrategy().setLogInflightExchangesOnTimeout(false);
You can configure the order in which routes should be started, and thus
also the same order they are being shutdown.
See more at
-link:configuring-route-startup-ordering-and-autostartup.html[Configuring
+link:configuring-route-startup-ordering-and-autostartup.adoc[Configuring
route startup ordering and autostartup].
[[GracefulShutdown-Finegrainedconfiguration]]
@@ -463,7 +463,7 @@ option. See `GenericFileConsumer` for an example.
[[GracefulShutdown-SeeAlso]]
==== See Also
-* link:configuring-route-startup-ordering-and-autostartup.html[Configuring
+* link:configuring-route-startup-ordering-and-autostartup.adoc[Configuring
route startup ordering and autostartup]
* link:advanced-configuration-of-camelcontext-using-spring.html[Advanced
configuration of CamelContext using Spring]
