[camel] 03/03: Polish and cleanup documentation

[da...@apache.org]

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

commit 582ef354aa7650f4d240f55fbc20d86eaf4b57dd
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Wed Aug 11 15:30:27 2021 +0200

    Polish and cleanup documentation
---
 .../ROOT/pages/pluggable-class-resolvers.adoc      |  73 ++--------
 .../modules/ROOT/pages/pojo-consuming.adoc         | 154 +++++----------------
 2 files changed, 49 insertions(+), 178 deletions(-)

diff --git a/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc b/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc
index 81cc1d0..b54fdd1 100644
--- a/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc
+++ b/docs/user-manual/modules/ROOT/pages/pluggable-class-resolvers.adoc
@@ -2,70 +2,25 @@
 
 Camel provides pluggable class resolvers allowing third party platforms
 and containers to provide their own resolvers in case the default ones
-would not fit. For example we provide a
-`WebSpherePackageScanClassResolver` out of the box to
-integrate Camel with IBM WebSphere.
+would not fit.
 
-Platform providers should look in the `org.apache.camel.spi` package for
-the pluggable resolvers below:
-
-* `PackageScanClassResolver`
-* `ClassResolver`
-* `FactoryFinderResolver`
-
-In *camel-osgi* we provide OSGi aware class resolver allowing Camel to
-run in any OSGi container.
+When running Camel on platforms such as Spring Boot, Quarkus, or OSGi on Apache Karaf,
+then Camel uses platform specific resolvers to support classloading in these runtimes.
 
 == Configuration of a custom class resolver
 
 To instruct Camel to use your own custom class resolver, you set the
-resolver on the `CamelContext` using the appropriate setters.
-
-== Easy configuration of a custom class resolver in Spring XML
-
-We have provided easy configuration in Spring XML as you just need to
-declare a spring bean with your custom resolver and Camel will pick it
-up automatically.
-
-[source,xml]
-----
-<bean id="jbossresolver" class="com.mycompany.jboss.JBossPackageScanClassResolver"/>
+resolver on the `CamelContext` using the appropriate setters;
+or register a custom resolver in the xref:registry.adoc[Registry] then Camel
+will automatic detect this during startup.
 
-<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
-  <route>
-    <from uri="seda:start"/>
-    <to uri="mock:result"/>
-  </route>
-</camelContext>
-----
+=== SPI providers
 
-In the sample above the CamelContext will automatic detect the
-`jbossresolver` bean and use it instead of its default one.
-
-== Configuration of a custom factory finder resolver
-
-FactoryFinderResolver is used to get an instance of `FactoryFinder` that
-is used for lookup of resource files in the classpath in the
-`META-INF/services`. It is used internally by Camel to look in .jars for
-Camel components. For instance to look for the `file` component Camel
-will use the `FactoryFinder` to look the file named `file` in
-`META-INF/services/org/apache/camel/component`. The `CamelContext` have
-methods to inject a custom `FactoryFinderResolver`.
-
-== Easy configuration of a custom factory finder resolver in Spring XML
-
-We have provided easy configuration in Spring XML as you just need to
-declare a spring bean with your custom factory finder resolver and Camel
-will pick it up automatically.
-
-[source,xml]
-----
-<bean id="jbossFactoryFinderResolver" class="com.mycompany.jboss.JBossFactoryFinderResolver"/>
+Platform providers should look in the `org.apache.camel.spi` package for
+the pluggable resolvers, such as:
 
-<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
-  <route>
-    <from uri="seda:start"/>
-    <to uri="mock:result"/>
-  </route>
-</camelContext>
-----
+* `ClassResolver`
+* `FactoryFinderResolver`
+* `PackageScanClassResolver`
+* `PackageScanResourceResolver`
+* `ResourceResolver`
diff --git a/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc b/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc
index a39c1bc..b1bb55d 100644
--- a/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc
+++ b/docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc
@@ -1,24 +1,23 @@
 = POJO Consuming
 
-To consume a message you use the
-`org.apache.camel.Consume`
+To consume a message you use the `@Consume`
 annotation to mark a particular method of a bean as being a consumer
-method. The uri of the annotation defines the Camel
+method. The value of the annotation defines the Camel
 xref:endpoint.adoc[Endpoint] to consume from.
 
-e.g. lets invoke the `onCheese()` method with the String body of the
+For example lets invoke the `onCheese()` method with the String body of the
 inbound JMS message from xref:components::activemq-component.adoc[ActiveMQ] on the cheese
 queue; this will use the xref:type-converter.adoc[Type Converter] to
 convert the JMS ObjectMessage or BytesMessage to a String - or just use
 a TextMessage from JMS
 
-[source,syntaxhighlighter-pre]
+[source,java]
 ----
 public class Foo {
 
   @Consume("activemq:cheese")
   public void onCheese(String name) {
-    ...
+    // do something here
   }
 }
 ----
@@ -27,93 +26,23 @@ The xref:bean-binding.adoc[Bean Binding] is then used to convert the
 inbound xref:{eip-vc}:eips:message.adoc[Message] to the parameter list used to invoke
 the method .
 
-What this does is basically create a route that looks kinda like this
+This basically creates a route that looks kinda like this:
 
-[source,syntaxhighlighter-pre]
+[source,java]
 ----
 from(uri).bean(theBean, "methodName");
 ----
 
-**When using more than one CamelContext**
-
-When you use more than 1 xref:camelcontext.adoc[CamelContext] you might
-end up with each of them creating a xref:pojo-consuming.adoc[POJO
-Consuming]; therefore use the option `context` on *@Consume* that allows
-you to specify which xref:camelcontext.adoc[CamelContext] id/name you
-want it to apply for.
-
-[[POJOConsuming-UsingcontextoptiontoapplyonlyacertainCamelContext]]
-== Using context option to apply only a certain CamelContext
-
-See the warning above.
-
-You can use the `context` option to specify which
-xref:camelcontext.adoc[CamelContext] the consumer should only apply for.
-For example:
-
-[source,syntaxhighlighter-pre]
-----
-  @Consume(uri="activemq:cheese", context="camel-1")
-  public void onCheese(String name) {
-----
-
-The consumer above will only be created for the
-xref:camelcontext.adoc[CamelContext] that have the context id =
-`camel-1`. You set this id in the XML tag:
-
-[source,syntaxhighlighter-pre]
-----
-<camelContext id="camel-1" ...>
-----
-
-[[POJOConsuming-Usinganexplicitroute]]
-== Using an explicit route
-
-If you want to invoke a bean method from many different endpoints or
-within different complex routes in different circumstances you can just
-use the normal routing xref:dsl.adoc[DSL] or the
-xref:spring.adoc[Spring] XML configuration file.
-
-For example
-
-[source,syntaxhighlighter-pre]
-----
-from(uri).beanRef("myBean", "methodName");
-----
-
-which will then look up in the xref:registry.adoc[Registry] and find the
-bean and invoke the given bean name. (You can omit the method name and
-have Camel figure out the right method based on the method annotations
-and body type).
-
-[[POJOConsuming-UsetheBeanendpoint]]
-== Use the Bean endpoint
-
-You can always use the bean endpoint
-
-[source,syntaxhighlighter-pre]
-----
-from(uri).to("bean:myBean?method=methodName");
-----
-
-[[POJOConsuming-Usingapropertytodefinetheendpoint]]
 == Using a property to define the endpoint
 
-*Since Camel 2.11*
-
-The following annotations @Consume, @Produce, @EndpointInject, now
+The following annotations `@Consume`, `@Produce`, `@EndpointInject`, now
 offers a `property` attribute you can use to define the endpoint as a
 property on the bean. Then Camel will use the getter method to access
 the property.
 
-**This applies for them all**
-
-The explanation below applies for all the three annotations, eg
-@Consume, @Produce, and @EndpointInject
-
-For example
+For example:
 
-[source,syntaxhighlighter-pre]
+[source,java]
 ----
 public class MyService {
   private String serviceEndpoint;
@@ -123,64 +52,60 @@ public class MyService {
   }
 
   public String getServiceEndpoint() {
-     return serviceEndpoint
+     return serviceEndpoint;
   }
 
   @Consume(property = "serviceEndpoint")
   public void onService(String input) {
-     ...
+     // do something
   }
 }
 ----
 
 The bean `MyService` has a property named `serviceEndpoint` which has
 getter/setter for the property. Now we want to use the bean for
-xref:pojo-consuming.adoc[POJO Consuming], and hence why we use @Consume
-in the onService method. Notice how we use the
+xref:pojo-consuming.adoc[POJO Consuming], and hence why we use `@Consume`
+in the `onService` method. Notice how we use the
 `property = "serviceEndpoint` to configure the property that has the
 endpoint url.
 
-If you define the bean in Spring XML or Blueprint, then you can
-configure the property as follows:
+If you define the bean in Spring XML, then you can configure the property as follows:
 
-[source,syntaxhighlighter-pre]
+[source,xml]
 ----
 <bean id="myService" class="com.foo.MyService">
   <property name="serviceEndpoint" value="activemq:queue:foo"/>
 </bean>
 ----
 
-This allows you to configure the bean using any standard IoC style.
+This allows you to configure the bean without with any dependency injection style.
+
+=== Advanced use with property naming convention
 
 Camel offers a naming convention which allows you to not have to
-explicit name the property. +
-Camel uses this algorithm to find the getter method. The method must be
-a getXXX method.
-
-1. Use the property name if explicit given
-2. If no property name was configured, then use the method name +
-3. Try to get the property with name*Endpoint* (eg with Endpoint as
-postfix)
-4. Try to get the property with the name as is (eg no postfix or
-postfix)
-5. If the property name starts with *on* then omit that, and try step 3
-and 4 again.
-
-So in the example above, we could have defined the @Consume annotation
-as
-
-[source,syntaxhighlighter-pre]
+explicit name the property. Camel uses this algorithm to find the getter method.
+The method must be a `getXXX` method.
+
+. Use the property name if explicit given
+. If no property name was configured, then use the method name
+. Try to get the property with name**Endpoint** (eg with Endpoint as postfix)
+. Try to get the property with the name as is (eg no postfix or postfix)
+. If the property name starts with **on** then omit that, and try step 3 and 4 again.
+
+So in the example above, we could have defined the `@Consume` annotation as:
+
+[source,java]
 ----
   @Consume(property = "service")
   public void onService(String input) {
 ----
 
-Now the property is named 'service' which then would match step 3 from
-the algorithm, and have Camel invoke the getServiceEndpoint method.
+Now the property is named "service" which then would match step 3 from
+the algorithm, and have Camel invoke the `getServiceEndpoint` method.
 
 We could also have omitted the property attribute, to make it implicit
 
-[source,syntaxhighlighter-pre]
+[source,java]
 ----
   @Consume
   public void onService(String input) {
@@ -188,14 +113,5 @@ We could also have omitted the property attribute, to make it implicit
 
 Now Camel matches step 5, and loses the prefix *on* in the name, and
 looks for 'service' as the property. And because there is a
-getServiceEndpoint method, Camel will use that.
-
-[[POJOConsuming-Whichapproachtouse]]
-== Which approach to use?
-
-Using the @Consume annotations are simpler when you are creating a
-simple route with a single well defined input URI.
+`getServiceEndpoint` method, Camel will use this method.
 
-However if you require more complex routes or the same bean method needs
-to be invoked from many places then please use the routing
-xref:dsl.adoc[DSL] as shown above.