CAMEL-16861: Update docs

Author: davsclaus

docs/user-manual/modules/ROOT/pages/expression.adoc

@@ -10,7 +10,8 @@ To support dynamic rules Camel supports pluggable
 https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Expression.html[Expression]
 strategies using a variety of different xref:components:languages:index.adoc[Languages].
 
-== Expression API
+NOTE: The xref:components:languages:simple-language.adoc[Simple] is often used as predicates and expressions
+with the Camel EIPs.
 
 If you are outside the DSL and want to create your own
 expressions you can either implement the
@@ -19,7 +20,7 @@ interface], reuse one of the other builders or try the
 https://www.javadoc.io/doc/org.apache.camel/camel-support/current/org/apache/camel/support/builder/ExpressionBuilder.html[ExpressionBuilder
 class].
 
-=== Expression
+== Expression API
 
 The API for a Camel Expression is defined in the
 `org.apache.camel.Expression` interface as shown:
@@ -38,3 +39,5 @@ public interface Expression {
 }
 ----
 
+A `Expression` is being evaluated to an Object value. This makes expressions so
+powerful as this can be used for functions, data mapping, templating, and for low-code users.

docs/user-manual/modules/ROOT/pages/parameter-binding-annotations.adoc

@@ -2,46 +2,26 @@
 
 The bean parameter binding annotations from Camel are as follows:
 
-[width="100%",cols="34%,33%,33%",options="header",]
-|=======================================================================
-|Annotation |Meaning |Parameter
-|`org.apache.camel.Body`
-|To bind to an inbound message body | 
-
-|`org.apache.camel.Header`
-|To bind to a message header |String name of the header
-
-|`org.apache.camel.Headers`
-|To bind to the Map of the message headers |
-
-|`org.apache.camel.Variable`
-|To bind to a named variable |String name of the
-variable
-
-|`org.apache.camel.Variables`
-|To bind to the variables map |
-
-|`org.apache.camel.ExchangeProperty`
-|To bind to a named property on the exchange |String name of the
-property
-
-|`org.apache.camel.ExchangeProperties`
-|To bind to the exchange property map on the exchange |
-
-|`org.apache.camel.ExchangeException`
-|To bind to an Exception set on the exchange |
-
-|=======================================================================
+[width="100%",cols="1m,2",options="header",]
+|===
+|Annotation                                                        | Meaning
+|`org.apache.camel.Body` | To bind to an inbound message body
+|`org.apache.camel.Header` | To bind to a message header by the given name
+|`org.apache.camel.Headers` | To bind to the Map of the message headers
+|`org.apache.camel.Variable` | To bind to a named variable the given name
+|`org.apache.camel.Variables` | To bind to the variables map
+|`org.apache.camel.ExchangeProperty` | To bind to a named property on the exchange the given name
+|`org.apache.camel.ExchangeProperties` | To bind to the exchange property map on the exchange
+|`org.apache.camel.ExchangeException` | To bind to an Exception set on the exchange
+|===
 
 These annotations can be used with the xref:components::bean-component.adoc[Bean]
 component or when invoking beans in the xref:dsl.adoc[DSL]
 
 Annotations can be used to define an xref:expression.adoc[Expression] or
 to extract various headers, properties or payloads from a
-xref:components:eips:message.adoc[Message] when invoking a bean method (see
-xref:bean-integration.adoc[Bean Integration] for more detail of how to
-invoke bean methods) together with being useful to help disambiguate
-which method to invoke.
+xref:components:eips:message.adoc[Message] when invoking a bean method. See
+xref:bean-integration.adoc[Bean Integration] for more in depth details on invoking beans.
 
 If no annotations are used then Camel assumes that a single parameter is
 the body of the message. Camel will then use the
@@ -78,11 +58,11 @@ TIP: You don't necessarily need to use the `@Consume` annotation if you don't
 want to as you could also make use of the Camel xref:dsl.adoc[DSL] to
 route to the bean's method as well.
 
-=== Using the DSL to invoke the bean method
+=== Calling bean from Camel routes
 
 Here is another example which does not use xref:pojo-consuming.adoc[POJO
 Consuming] annotations but instead uses the xref:dsl.adoc[DSL] to route
-messages to the bean method
+messages to the bean method.
 
 [source,java]
 ----
@@ -97,23 +77,79 @@ public class MyBean {
 
 The routing DSL then looks like this
 
+[tabs]
+====
+
+Java::
++
 [source,java]
 ----
 from("activemq:someQueue").
   to("bean:myBean");
 ----
 
+XML::
++
+[source,xml]
+----
+<route>
+    <from uri="activemq:someQueue"/>
+    <to uri="bean:myBean"/>
+</route>
+----
+
+YAML::
++
+[source,yaml]
+----
+- route:
+    from:
+      uri: activemq:someQueue
+      steps:
+        - to:
+            uri: bean:myBean
+----
+====
+
 Here *myBean* would be looked up in the xref:registry.adoc[Registry]
 then the body of the message would be used to try figure out what method to call.
 
 If you want to be explicit you can use:
 
+[tabs]
+====
+
+Java::
++
 [source,java]
 ----
 from("activemq:someQueue").
-  to("bean:myBean?methodName=doSomething");
+  to("bean:myBean?method=doSomething");
+----
+
+XML::
++
+[source,xml]
+----
+<route>
+    <from uri="activemq:someQueue"/>
+    <to uri="bean:myBean?method=doSomething"/>
+</route>
 ----
 
+YAML::
++
+[source,yaml]
+----
+- route:
+    from:
+      uri: activemq:someQueue
+      steps:
+        - to:
+            uri: bean:myBean?method=doSomething
+----
+====
+
 And here we have a nifty example for you to show some great power in
 Camel. You can mix and match the annotations with the normal parameters,
 so we can have this example with annotations and the Exchange also:
@@ -136,28 +172,16 @@ Camel to bind expressions to method parameters when using
 xref:bean-integration.adoc[Bean Integration]. For example, you can use
 any of these annotations:
 
-[width="100%",cols="50%,50%",options="header",]
-|=======================================================================
+[width="100%",cols="1m,2",options="header",]
+|===
 |Annotation |Description
-|`@Bean`
-|Inject a xref:components:languages:bean-language.adoc[Bean] expression
-
-|`@Constant`
-|Inject a xref:components:languages:constant-language.adoc[Constant] expression
-
-|`@Groovy`
-|Inject a  xref:components:languages:groovy-language.adoc[Groovy] expression
-
-|`@Header`
-|Inject a xref:components:languages:header-language.adoc[Header] expression
-
-|`@Simple`
-|Inject an xref:components:languages:simple-language.adoc[Simple] expression
-
-|`@XPath`
-|Inject an xref:components:languages:xpath-language.adoc[XPath] expression
-
-|=======================================================================
+|`@Bean`|Inject a xref:components:languages:bean-language.adoc[Bean] expression
+|`@Constant`|Inject a xref:components:languages:constant-language.adoc[Constant] expression
+|`@Groovy`|Inject a  xref:components:languages:groovy-language.adoc[Groovy] expression
+|`@Header`|Inject a xref:components:languages:header-language.adoc[Header] expression
+|`@Simple`|Inject an xref:components:languages:simple-language.adoc[Simple] expression
+|`@XPath`|Inject an xref:components:languages:xpath-language.adoc[XPath] expression
+|===
 
 The table above only list some of the commonly used languages. You can find
 a list of all supported xref:components:languages:index.adoc[Languages]
@@ -182,7 +206,7 @@ public class Foo {
 
 ==== Advanced example using @Bean
 
-And an example of using the the `@Bean` binding annotation,
+And an example of using the `@Bean` binding annotation,
 where you can call a xref:components::bean-component.adoc[POJO] to supply
 the parameter value:
 
@@ -210,8 +234,7 @@ public class MyIdGenerator {
     public String generate(@Header(name = "user") String user, @Body String payload) throws Exception {
        User user = userManager.lookupUser(user);
        String userId = user.getPrimaryId();
-       String id = userId + generateHashCodeForPayload(payload);
-       return id;
+       return userId + generateHashCodeForPayload(payload);
    }
 }
 ----
@@ -250,7 +273,7 @@ For example in Spring XML:
 In this example we have an Exchange that has a User object stored in the
 in header. This User object has methods to get some user information. We
 want to use xref:components:languages:groovy-language.adoc[Groovy] to inject an expression that
-extracts and concats the fullname of the user into the fullName parameter.
+extracts and concat the names of the user into the fullName parameter.
 
 [source,java]
 ----

docs/user-manual/modules/ROOT/pages/pojo-consuming.adoc

@@ -5,18 +5,12 @@ annotation to mark a particular method of a bean as being a consumer
 method. The value of the annotation defines the Camel
 xref:endpoint.adoc[Endpoint] to consume from.
 
-IMPORTANT: The `@Consume` POJO annotations are not part of any Camel routes, and you cannot use errorHandler or onException with that.
-
-[NOTE]
-====
-The following steps use the ActiveMQ component which is not yet supported on Camel 4.
-====
+IMPORTANT: The `@Consume` POJO annotations are not part of any Camel routes, and you cannot use xref:error-handler.adoc[errorHandler] or xref:exception-clause.adoc[onException] with this.
 
 For example lets invoke the `onCheese()` method with the String body of the
 inbound JMS message from 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
+convert the JMS payload to `String` as declared in the method signature.
 
 [source,java]
 ----
@@ -31,19 +25,19 @@ public class Foo {
 
 The xref:bean-binding.adoc[Bean Binding] is then used to convert the
 inbound xref:components:eips:message.adoc[Message] to the parameter list used to invoke
-the method .
+the method.
 
-This basically creates a route that looks kinda like this:
+This basically creates a route that looks kinda like this (based on the example above):
 
 [source,java]
 ----
-from(uri).bean(theBean, "methodName");
+from("activemq:cheese").bean(Foo.class, "onCheese");
 ----
 
 == Using a property to define the endpoint
 
-The following annotations `@Consume`, `@Produce`, `@EndpointInject`, now
-offers a `property` attribute you can use to define the endpoint as a
+The following annotations `@Consume`, `@Produce`, `@EndpointInject`, provides
+a `property` attribute you can use to define the endpoint uri as a
 property on the bean. Then Camel will use the getter method to access
 the property.
 
@@ -52,22 +46,25 @@ For example:
 [source,java]
 ----
 public class MyService {
+
   private String serviceEndpoint;
   
   public void setServiceEndpoint(String uri) {
      this.serviceEndpoint = uri;
   }
 
-  public String getServiceEndpoint() {
+  public String getServiceEndpoint() { // <2>
      return serviceEndpoint;
   }
 
-  @Consume(property = "serviceEndpoint")
+  @Consume(property = "serviceEndpoint") // <1>
   public void onService(String input) {
      // do something
   }
 }
 ----
+<1> the getter for the property
+<2> refers to the name of the property
 
 The bean `MyService` has a property named `serviceEndpoint` which has
 getter/setter for the property. Now we want to use the bean for
@@ -76,15 +73,33 @@ 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, then you can configure the property as follows:
 
+[tabs]
+====
+
+Spring XML::
++
+If you define the bean in Spring XML, then you can configure the property as follows:
++
 [source,xml]
 ----
 <bean id="myService" class="com.foo.MyService">
   <property name="serviceEndpoint" value="activemq:queue:foo"/>
 </bean>
 ----
 
+YAML::
++
+[source,yaml]
+----
+- beans:
+    - name: foo
+      type: com.foo.MyService
+      properties:
+        serviceEndpoint: activemq:queue:foo
+----
+====
+
 This allows you to configure the bean without with any dependency injection style.
 
 === Advanced use with property naming convention
@@ -95,8 +110,8 @@ 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)
+. Try to get the property with name**Endpoint** (e.g. with Endpoint as postfix)
+. Try to get the property with the name as is (e.g. 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:
@@ -110,7 +125,7 @@ So in the example above, we could have defined the `@Consume` annotation as:
 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
+We could also have omitted the property attribute, to make it implicit:
 
 [source,java]
 ----
@@ -122,3 +137,6 @@ 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 this method.
 
+== See Also
+
+- xref:pojo-producing.adoc[]