This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 8b80e23 Polish and cleanup documentation
8b80e23 is described below
commit 8b80e2372b228f23971199beb2834007127bb24f
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Tue Aug 10 09:53:22 2021 +0200
Polish and cleanup documentation
---
.../camel/component/jms/jmsRouteUsingSpring.xml | 43 --------
docs/user-manual/modules/ROOT/nav.adoc | 1 -
.../modules/ROOT/pages/configuring-camel.adoc | 80 ---------------
...ing-route-startup-ordering-and-autostartup.adoc | 114 +++++++++------------
.../modules/ROOT/pages/console-example.adoc | 62 -----------
docs/user-manual/modules/ROOT/pages/examples.adoc | 2 -
.../modules/ROOT/pages/getting-started.adoc | 5 +-
docs/user-manual/modules/ROOT/pages/index.adoc | 1 -
docs/user-manual/modules/faq/nav.adoc | 1 -
docs/user-manual/modules/faq/pages/index.adoc | 1 -
10 files changed, 51 insertions(+), 259 deletions(-)
diff --git
a/docs/user-manual/modules/ROOT/examples/components/camel-jms/src/test/resources/org/apache/camel/component/jms/jmsRouteUsingSpring.xml
b/docs/user-manual/modules/ROOT/examples/components/camel-jms/src/test/resources/org/apache/camel/component/jms/jmsRouteUsingSpring.xml
deleted file mode 100644
index 8cdb91b..0000000
---
a/docs/user-manual/modules/ROOT/examples/components/camel-jms/src/test/resources/org/apache/camel/component/jms/jmsRouteUsingSpring.xml
+++ /dev/null
@@ -1,43 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-
--->
-<beans xmlns="http://www.springframework.org/schema/beans";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="
- http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
- http://camel.apache.org/schema/spring
http://camel.apache.org/schema/spring/camel-spring.xsd
- ">
-
- <!-- tag::example[] -->
- <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";>
- <jmxAgent id="agent" disabled="true"/>
- </camelContext>
-
- <bean id="activemq" class="org.apache.camel.component.jms.JmsComponent">
- <property name="connectionFactory">
- <bean class="org.apache.activemq.ActiveMQConnectionFactory">
- <property name="brokerURL">
- <bean class="org.apache.camel.component.jms.CamelJmsTestHelper"
factory-method="createBrokerUrl"/>
- </property>
- </bean>
- </property>
- </bean>
- <!-- end::example[] -->
-
-</beans>
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index c98bc5f..d0cf80b 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -10,7 +10,6 @@
** xref:camel-component-maven-plugin.adoc[Camel Component Maven Plugin]
** xref:camel-report-maven-plugin.adoc[Camel Maven Report Plugin]
** xref:camel-maven-archetypes.adoc[Camel Maven Archetypes]
-** xref:configuring-camel.adoc[Configuring Camel]
** xref:configuring-route-startup-ordering-and-autostartup.adoc[Configuring
route startup ordering and autostartup]
** xref:creating-a-new-spring-based-camel-route.adoc[Creating a new Spring
based Camel Route]
** xref:component-dsl.adoc[Component-dsl]
diff --git a/docs/user-manual/modules/ROOT/pages/configuring-camel.adoc
b/docs/user-manual/modules/ROOT/pages/configuring-camel.adoc
deleted file mode 100644
index 128b184..0000000
--- a/docs/user-manual/modules/ROOT/pages/configuring-camel.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-[[ConfiguringCamel-ConfiguringCamel]]
-= Configuring Camel
-
-[[ConfiguringCamel-HowdoIaddacomponent]]
-== How do I add a component?
-
-You might first want to read xref:writing-components.adoc[Writing
-Components] for a background in how to implement a new component.
-Typically it means you write an implementation of the
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Component.html[Component]
-interface, usually deriving from
-https://www.javadoc.io/doc/org.apache.camel/camel-support/current/org/apache/camel/support/DefaultComponent.html[DefaultComponent].
-
-You can then register your component explicitly via:
-
-[source,java]
-----
-CamelContext context = new DefaultCamelContext();
-context.addComponent("foo", new FooComponent(context));
-----
-
-However you can use the auto-discovery feature of Camel where by Camel
-will automatically add a xref:component.adoc[Component] when an endpoint
-URI is used. To do this you would create a file called:
-
-....
-/META-INF/services/org/apache/camel/component/foo
-....
-
-with contents:
-
-[source,java]
-----
-class=org.acme.FooComponent
-----
-
-(You can add other property configurations in there too if you like.)
-
-Then if you refer to an endpoint as `foo://somethingOrOther` Camel
-will auto-discover your component and register it.
-
-The `FooComponent` can then be auto-injected with resources using the
-https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/spi/Injector.html[Injector],
-such as to support xref:components::spring-summary.adoc[Spring] based
auto-wiring, or to
-support `@Resource` (EJB3 style) injection or Guice style `@Inject`
-injection.
-
-
-[[ConfiguringCamel-WorkingwithSpringXML]]
-== Working with Spring XML
-
-You can configure a component via Spring using the following mechanism:
-
-[source,xml]
-----
-include::{examplesdir}/components/camel-jms/src/test/resources/org/apache/camel/component/jms/jmsRouteUsingSpring.xml[tags=example]
-----
-
-Which allows you to configure a component using some name (activemq in the
-above example), then you can refer to the component using
-`activemq:[queue:|topic:]destinationName`.
-
-If you want to add explicit Spring 2.x XML objects to your XML then you
-could use the `xbean-spring` which tries to automate most of the XML
-binding work for you; or you could look in camel-spring
-at `CamelNamespaceHandler` you'll see how we handle the Spring XML
-stuff (warning it's kinda hairy code to look at :smile:).
-If you wanted `<fooComponent>` to be a standard part of the core Camel
-schema then you'd hack that file to add your component &
-link:/community/contributing/[contribute a patch] to the camel XSD. Otherwise
-you could write your own namespace & schema if you prefer.
-
-[[ConfiguringCamel-PropertyBinding]]
-== Configuring using properties
-
-Camel is very configurable with properties using the following features:
-
-- xref:property-binding.adoc[Property Binding]
-- xref:using-propertyplaceholder.adoc[Property Placeholders]
-- xref:components::properties-component.adoc[Properties Component]
diff --git
a/docs/user-manual/modules/ROOT/pages/configuring-route-startup-ordering-and-autostartup.adoc
b/docs/user-manual/modules/ROOT/pages/configuring-route-startup-ordering-and-autostartup.adoc
index a291184..20b0688 100644
---
a/docs/user-manual/modules/ROOT/pages/configuring-route-startup-ordering-and-autostartup.adoc
+++
b/docs/user-manual/modules/ROOT/pages/configuring-route-startup-ordering-and-autostartup.adoc
@@ -1,52 +1,57 @@
-[[Configuringroutestartuporderingandautostartup-Configuringroutesstartuporderingandautostartup]]
-= Configuring routes startup ordering and autostartup
+= Configuring Routes Startup Ordering and Autostartup
-*Since Camel 2.1*
-
-Camel now supports configuring two aspects:
+Camel supports configuring two aspects:
* auto startup
* order of starting routes
-[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherCamelshouldbeautostartedornotinXMLDSL]]
-== Configuring whether Camel should be auto started or not in XML DSL
+== Autostartup
+
+The `autoStartup` option allows is to configure
+Camel to *not* auto start routes when Camel starts.
+
+The auto startup can be configured on two levels:
-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.
+- CamelContext - _Globally_
+- Route - _Individually per route_
-For example the route below we have configured `autoStartup=false` to
-prevent Camel starting when Spring starts.
+For example the CamelContext below we have configured `autoStartup=false` to
+prevent Camel starting all the routes 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"/>
+ <from uri="direct:foo"/>
+ <to uri="mock:foo"/>
+ </route>
+ <route>
+ <from uri="direct:bar"/>
+ <to uri="mock:bar"/>
</route>
</camelContext>
----
-So how do you start Camel then?
+So how do you start the routes?
The `autoStartup` option on the `<camelContext>` is only used once, so you
-can manually start Camel later by invoking its `start` method as shown
+can manually start Camel later by invoking its `start` method in Java as shown
below:
[source,java]
----
ApplicationContext ac = ...
- SpringCamelContext camel = (SpringCamelContext) ac.getBean("myCamel");
+ CamelContext camel = (CamelContext) ac.getBean("myCamel");
- // now start Camel manually
- camel.start();
+ // now start all the routes
+ camel.getRouteController().startAllRoutes();
----
-[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherarouteshouldbestartedornotinXMLDSL]]
-== Configuring whether a route should be started or not in XML DSL
+TIP: The routes can also be started via JMX (requires `camel-management` JAR
to be on the classpath) by invoking the `startAllRoutes` operation on the
CamelContext MBean.
+
+=== Autostartup per route level
-You can use the `autoStartup` option to configure if a given route
+You can also 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.
@@ -71,23 +76,21 @@ And to explicit state it should be started:
</route>
----
-[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherarouteshouldbestartedornotinJavaDSL]]
-== Configuring whether a route should be started or not in Java DSL
+=== Autostartup 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:
+Configuring auto startup on `CamelContext` is done as follows:
[source,java]
----
-from("activemq:queue:special").noAutoStartup().to("file://backup");
+camelCopntext.setAutoStartup(false);
----
-[[Configuringroutestartuporderingandautostartup-ConfiguringwhetherarouteshouldbestartedornotusingabooleanorStringinJavaDSL]]
-== Configuring whether a route should be started or not, using a boolean or
String, in Java DSL
+And on route level you can disable (is enabled by default):
-*Since Camel 2.9*
+[source,java]
+----
+from("activemq:queue:special").noAutoStartup().to("file://backup");
+----
To startup based on a boolean, String or
xref:components::properties-component.adoc[Property], do one of the following:
@@ -96,14 +99,13 @@ xref:components::properties-component.adoc[Property], do
one of the following:
----
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
@@ -133,31 +135,17 @@ 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?
+=== Why do you want to control the starting order?
-It can help in cases where routes are inter dependent on each other and
+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
+Camel will stop the routes in the *reverse* order that they were started.
Let's try a couple of examples.
-[[Configuringroutestartuporderingandautostartup-Simpleexample]]
-=== Simple example
+=== Startup ordering example
[source,java]
----
@@ -188,8 +176,7 @@ 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
+=== Startup ordering example with startupOrder and without
[source,java]
----
@@ -219,16 +206,17 @@ And the same example with XML DSL:
</route>
----
-In the route above we have *not* define a `startupOrder` on the last
+In the route above we have *not* defined 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
+which this case will be 1000; 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-Routestostartuplast]]
-=== Routes to start up last
+=== Configuring routes to start up last
+
+You can use a high number in `startupOrder` to have a specific route startup
last as shown below:
[source,java]
----
@@ -252,13 +240,9 @@ In the example above the order of startups of routes
should be:
3. `seda://bar`
4. `direct://bar`
-[[Configuringroutestartuporderingandautostartup-Shutdown]]
-== Shutdown
-
-*Camel 2.2:* Camel will shutdown the routes in the *same* order that
-they were started.
+=== Shutting down routes
-*Camel 2.3:* Camel will shutdown the routes in the *reverse* order that
+Camel will shutdown the routes in the *reverse* order that
they were started.
See also xref:graceful-shutdown.adoc[Graceful Shutdown].
diff --git a/docs/user-manual/modules/ROOT/pages/console-example.adoc
b/docs/user-manual/modules/ROOT/pages/console-example.adoc
deleted file mode 100644
index 235efd4..0000000
--- a/docs/user-manual/modules/ROOT/pages/console-example.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-= Console Example
-
-This is a beginner's example that demonstrates how to get started with
-Apache Camel.
-
-In this example we integrate with the console using the
-xref:components::stream-component.adoc[Stream] component. The example is
interactive - it
-reads input from the console, and then transforms the input to upper
-case and prints it back to the console.
-
-This is implemented with a Camel route defined in the Spring XML markup
-shown below:
-
-[source,xml]
-----
- <!-- camelContext is the Camel runtime, where we can host Camel routes -->
- <camelContext xmlns="http://camel.apache.org/schema/spring";>
- <route>
- <!-- read input from the console using the stream component -->
- <from uri="stream:in?promptMessage=Enter something: "/>
- <!-- transform the input to upper case using the simple language -->
- <!-- you can also use other languages such as groovy, ognl, mvel,
javascript etc. -->
- <transform>
- <simple>${body.toUpperCase()}</simple>
- </transform>
- <!-- and then print to the console -->
- <to uri="stream:out"/>
- </route>
- </camelContext>
-
-----
-
-This example can be launched from the command line using Maven:
-
-[source,shell]
-----
-mvn compile exec:java
-----
-
-In the console you can enter a message and press <ENTER>. Camel responds
-by echoing the input message in upper case, as shown below:
-
-----
-[onsole.CamelConsoleMain.main()] SpringCamelContext INFO Apache Camel 2.10
(CamelContext: camel-1) started in 0.455 seconds
-Enter something: camel rocks
-CAMEL ROCKS
-Enter something: and we have fun
-AND WE HAVE FUN
-Enter something:
-----
-
-To stop the example, strike Control+C
-
-You can also run this example from your editor. For example, from
-Eclipse you can import this project using: File → Import … → Existing
-Maven Project, and select `pom.xml` from the
-`examples\camel-example-console` directory.
-
-Next, navigate to the
-`org.apache.camel.example.console.CamelConsoleMain` class, right-click,
-and select Run As → Java Application.
-
diff --git a/docs/user-manual/modules/ROOT/pages/examples.adoc
b/docs/user-manual/modules/ROOT/pages/examples.adoc
index e8913e5..150182e 100644
--- a/docs/user-manual/modules/ROOT/pages/examples.adoc
+++ b/docs/user-manual/modules/ROOT/pages/examples.adoc
@@ -15,8 +15,6 @@ understand how things fit together using the Java
xref:dsl.adoc[DSL] to
set up some routes in a simple `main(...)` method.
* Walk through the xref:walk-through-another-example.adoc[Spring DSL
example] to look at XML-based routing.
-* Walk through the xref:console-example.adoc[Console Example] to
-practice reading input from the console.
[NOTE]
====
diff --git a/docs/user-manual/modules/ROOT/pages/getting-started.adoc
b/docs/user-manual/modules/ROOT/pages/getting-started.adoc
index cf19384..b7cde44 100644
--- a/docs/user-manual/modules/ROOT/pages/getting-started.adoc
+++ b/docs/user-manual/modules/ROOT/pages/getting-started.adoc
@@ -20,9 +20,8 @@ documentation before continuing:
To get started with Camel:
1. Create a xref:camelcontext.adoc[CamelContext].
-2. Optionally, xref:configuring-camel.adoc[configure components or endpoints].
-3. Add whatever routing rules you wish using the DSL and `RouteBuilder` or
using XML DSL.
-4. Start the Camel context.
+2. Add whatever routing rules you wish using the DSL and `RouteBuilder` or
using XML DSL.
+3. Start the Camel context.
When your application is closing you may wish to stop the context
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc
b/docs/user-manual/modules/ROOT/pages/index.adoc
index e486698..82aef7b 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -51,7 +51,6 @@ For a deeper and better understanding of Apache Camel, an
xref:faq:what-is-camel
* xref:spring.adoc[Working with Camel and Spring]
* xref:faq:how-do-i-configure-endpoints.adoc[How do I configure endpoints?]
* xref:bean-integration.adoc[Bean Integration]
-* xref:configuring-camel.adoc[Configuring Camel]
* xref:configuring-route-startup-ordering-and-autostartup.adoc[Configuring
route startup ordering and autostartup]
* xref:graceful-shutdown.adoc[Graceful Shutdown]
* xref:error-handling-in-camel.adoc[Error handling in Camel]
diff --git a/docs/user-manual/modules/faq/nav.adoc
b/docs/user-manual/modules/faq/nav.adoc
index fc40a1d..1b2e8be 100644
--- a/docs/user-manual/modules/faq/nav.adoc
+++ b/docs/user-manual/modules/faq/nav.adoc
@@ -21,7 +21,6 @@
** xref:how-can-i-stop-a-route-from-a-route.adoc[How can I stop a route from a
route?]
**
xref:how-can-webservice-clients-see-remote-faults-with-stacktraces-when-using-camel-cxf.adoc[How
can webservice clients see remote faults with stacktraces when using
camel-cxf?]
** xref:how-does-camel-look-up-beans-and-endpoints.adoc[How does Camel look up
beans and endpoints?]
-** xref:ROOT:configuring-camel.adoc[How do I add a component?]
** xref:how-do-i-change-the-logging.adoc[How do I change the logging?]
** xref:how-do-i-configure-endpoints.adoc[How do I configure endpoints?]
**
xref:how-do-i-configure-password-options-on-camel-endpoints-without-the-value-being-encoded.adoc[How
do I configure password options on Camel endpoints without the value being
encoded?]
diff --git a/docs/user-manual/modules/faq/pages/index.adoc
b/docs/user-manual/modules/faq/pages/index.adoc
index 6255a45..c90cf34 100644
--- a/docs/user-manual/modules/faq/pages/index.adoc
+++ b/docs/user-manual/modules/faq/pages/index.adoc
@@ -43,7 +43,6 @@ Questions on using Apache Camel
* xref:how-can-i-stop-a-route-from-a-route.adoc[How can I stop a route from a
route?]
*
xref:how-can-webservice-clients-see-remote-faults-with-stacktraces-when-using-camel-cxf.adoc[How
can webservice clients see remote faults with stacktraces when using
camel-cxf?]
* xref:how-does-camel-look-up-beans-and-endpoints.adoc[How does Camel look up
beans and endpoints?]
-* xref:ROOT:configuring-camel.adoc[How do I add a component?]
* xref:how-do-i-change-the-logging.adoc[How do I change the logging?]
* xref:how-do-i-configure-endpoints.adoc[How do I configure endpoints?]
*
xref:how-do-i-configure-password-options-on-camel-endpoints-without-the-value-being-encoded.adoc[How
do I configure password options on Camel endpoints without the value being
encoded?]
