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 0ed82b6 Polish and cleanup documentation
0ed82b6 is described below
commit 0ed82b6d5206d4e73b25297c22d44d34c2ec189b
Author: Claus Ibsen <[email protected]>
AuthorDate: Wed Aug 11 16:58:50 2021 +0200
Polish and cleanup documentation
---
.../user-manual/modules/ROOT/pages/expression.adoc | 25 +-----
docs/user-manual/modules/ROOT/pages/predicate.adoc | 97 ++++++++++------------
docs/user-manual/modules/ROOT/pages/processor.adoc | 78 ++++++++++-------
3 files changed, 95 insertions(+), 105 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/expression.adoc
b/docs/user-manual/modules/ROOT/pages/expression.adoc
index e00eab8..ebcfeb6 100644
--- a/docs/user-manual/modules/ROOT/pages/expression.adoc
+++ b/docs/user-manual/modules/ROOT/pages/expression.adoc
@@ -1,13 +1,13 @@
[[Expression-Expressions]]
= Expressions
-Expressions and Predicates can then be used to
+Expressions and xref:predicate.adoc[Predicates] can then be used to
create the various
xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise
Integration Patterns] in the xref:dsl.adoc[DSL] like with the
xref:{eip-vc}:eips:recipientList-eip.adoc[Recipient List] EIP.
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 Languages.
+strategies using a variety of different
xref:latest@components:languages:index.adoc[Languages].
== Expression API
@@ -38,24 +38,3 @@ public interface Expression {
}
-------------------------------------------------------------------------------
-=== Predicate
-
-The API for a Camel Predicate is defined in the
-`org.apache.camel.Predicate` interface as shown:
-
-[source,java]
--------------------------------------------------------------------------------
-public interface Predicate {
-
- /**
- * Evaluates the predicate on the message exchange and returns true if this
- * exchange matches the predicate
- *
- * @param exchange the message exchange
- * @return true if the predicate matches
- */
- boolean matches(Exchange exchange);
-
-}
--------------------------------------------------------------------------------
-
diff --git a/docs/user-manual/modules/ROOT/pages/predicate.adoc
b/docs/user-manual/modules/ROOT/pages/predicate.adoc
index 6237f2f..1212c75 100644
--- a/docs/user-manual/modules/ROOT/pages/predicate.adoc
+++ b/docs/user-manual/modules/ROOT/pages/predicate.adoc
@@ -1,20 +1,42 @@
[[Predicate-Predicates]]
= Predicates
-Camel supports a pluggable interface called
+xref:expression.adoc[Expressions] and Predicates can then be used to
+create the various
xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise
+Integration Patterns] in the xref:dsl.adoc[DSL] like with the
xref:{eip-vc}:eips:content-based-router-eip.adoc[Content Based Router] EIP.
+
+To support dynamic rules Camel supports pluggable
https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Predicate.html[Predicate]
-which can be used to integrate a dynamic predicate into
-xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[Enterprise Integration
-Patterns] such as when using the xref:{eip-vc}:eips:filter-eip.adoc[Message
Filter]
-or xref:{eip-vc}:eips:content-based-router-eip.adoc[Content Based Router].
+strategies using a variety of different
xref:latest@components:languages:index.adoc[Languages].
+
+== Predicate API
-A Predicate is being evaluated to a boolean value so the result is
-either `true` or `false`. This makes xref:predicate.adoc[Predicate] so
+The API for a Camel Predicate is defined in the
+`org.apache.camel.Predicate` interface as shown:
+
+[source,java]
+-------------------------------------------------------------------------------
+public interface Predicate {
+
+ /**
+ * Evaluates the predicate on the message exchange and returns true if this
+ * exchange matches the predicate
+ *
+ * @param exchange the message exchange
+ * @return true if the predicate matches
+ */
+ boolean matches(Exchange exchange);
+
+}
+-------------------------------------------------------------------------------
+
+A `Predicate` is being evaluated to a boolean value so the result is
+either `true` or `false`. This makes predicates so
powerful as it is often used to control the routing of message in which
path they should be routed.
A simple example is to route an xref:exchange.adoc[Exchange] based on a
-header value:
+header value with the xref:{eip-vc}:eips:content-based-router-eip.adoc[Content
Based Router] EIP:
[source,java]
----
@@ -28,14 +50,14 @@ from("jms:queue:order")
----
In the route above the xref:predicate.adoc[Predicate] is the
-`header("type").isEqualTo("widget")` as its constructed as an
+`header("type").isEqualTo("widget")` as it is constructed as an
xref:expression.adoc[Expression] that is evaluated as a
-xref:predicate.adoc[Predicate]. To do this the various Builder classes
+xref:predicate.adoc[Predicate]. To do this the various _Builder classes_
helps us here to create a nice and fluent syntax. `isEqualTo` is a
builder method that returns a xref:predicate.adoc[Predicate] based on
the input.
-Sometimes the fluent builders can get long and a bit complex to read,
+Sometimes the fluent builders can get long, and a bit complex to read,
then you can just define your predicate outside the route and then just
refer to the predicate in the route:
@@ -57,7 +79,6 @@ from("jms:queue:order")
.end();
----
-[[Predicate-NegatingaPredicate]]
== Negating a Predicate
You can use the *not* method on the `PredicateBuilder` to negate a
@@ -68,7 +89,7 @@ read:
[source,java]
----
-import static org.apache.camel.builder.PredicateBuilder.not
+import static org.apache.camel.builder.PredicateBuilder.not;
----
And then we can use it to enclose an existing predicate and negate it as
@@ -83,14 +104,13 @@ from("direct:start")
.end();
----
-[[Predicate-CompoundPredicates]]
== Compound Predicates
You can also create compound predicates using boolean operators such as
`and, or, not` and many others.
-Currently this feature is only available in the Java-based DSLs, but not
-in the Spring nor Blueprint DSLs.
+Currently, this feature is only available in the Java-based DSLs, and not
+in other DSLs such as XML.
Using the
https://www.javadoc.io/doc/org.apache.camel/camel-support/current/org/apache/camel/support/builder/PredicateBuilder.html[`PredicateBuilder`]
@@ -103,10 +123,15 @@ based on logical operators and comparison operators:
* `startsWith`, `endsWith`
* `in` ("any of X predicates stands true")
-Additionally, with `PredicateBuilder` you can create Regular Expressions
+Additionally, with `PredicateBuilder` you can create regular expressions
and use them as predicates, applying them to the result of an
-expression, e.g. `PredicateBuilder.regex(header("foo"), "\d\{4}")`
-applies the regular expression to the header = foo.
+expression, e.g.
+
+[source,java]
+----
+PredicateBuilder.regex(header("foo"), "\d\{4}");
+----
+applies the regular expression to the foo header.
Combining different Expression Languages is also possible, e.g.:
@@ -145,37 +170,3 @@ from("direct:start").choice()
.end();
----
-[[Predicate-ExtensiblePredicates]]
-== Extensible Predicates
-
-Camel supports extensible Predicates using multiple
-xref:languages.adoc[Languages]; the following languages are supported
-out of the box
-
-* xref:components:languages:bean-language.adoc[Bean Language] for using Java
for expressions
-* xref:components:languages:constant-language.adoc[Constant]
-* xref:components:languages:header-language.adoc[Header]
-* xref:components:languages:jsonpath-language.adoc[JSonPath]
-* xref:components:languages:mvel-language.adoc[Mvel]
-* xref:components:languages:ognl-language.adoc[OGNL]
-* xref:components:languages:ref-language.adoc[Ref Language]
-* xref:components:languages:exchangeProperty-language.adoc[ExchangeProperty]
-** xref:components:languages:groovy-language.adoc[Groovy]
-* xref:components:languages:simple-language.adoc[Simple]
-** xref:components:languages:file-language.adoc[File Language]
-* xref:components:languages:spel-language.adoc[Spring Expression Language]
-* xref:components:languages:tokenize-language.adoc[Tokenizer]
-* xref:components:languages:xpath-language.adoc[XPath]
-* xref:components:languages:xquery-language.adoc[XQuery]
-
-Most of these languages is also supported used as
-xref:parameter-binding-annotations.adoc[Annotation Based
-Expression Language].
-
-You can easily write your own plugin predicate by implementing the
-https://github.com/apache/camel/blob/main/core/camel-api/src/main/java/org/apache/camel/Predicate.java[Predicate
-interface].
-
-There are also a number of helper builders available such as the
-https://github.com/apache/camel/blob/main/core/camel-core/src/main/java/org/apache/camel/builder/PredicateBuilder.java[PredicateBuilder
-class]
diff --git a/docs/user-manual/modules/ROOT/pages/processor.adoc
b/docs/user-manual/modules/ROOT/pages/processor.adoc
index 0c4fa57..184b787 100644
--- a/docs/user-manual/modules/ROOT/pages/processor.adoc
+++ b/docs/user-manual/modules/ROOT/pages/processor.adoc
@@ -3,23 +3,39 @@
The
https://www.javadoc.io/doc/org.apache.camel/camel-api/current/org/apache/camel/Processor.html[Processor]
-interface is used to implement consumers of message exchanges or to
-implement a xref:{eip-vc}:eips:message-translator.adoc[Message Translator].
+interface is used for implement consumers of message exchanges or to
+implement a xref:{eip-vc}:eips:message-translator.adoc[Message Translator],
+and other use-cases.
-[[Processor-Usingaprocessorinaroute]]
== Using a processor in a route
-Once you have written a class which implements processor like this...
+Once you have written a class which implements processor like this:
[source,java]
----
public class MyProcessor implements Processor {
+
public void process(Exchange exchange) throws Exception {
// do something...
}
+
}
----
+Then you can easily call this processor from a Java such as:
+
+[source,java]
+----
+from("activemq:myQueue").process(MyProcessor.class);
+----
+
+Notice that the processor is referred to by the class type `MyProcessor.class`
in the route.
+Camel will during startup automatic create one new instance of the processor
using xref:injector.adoc[Injector]
+to be used during routing messages.
+
+In XML DSL however the `<process`> tag requires, referring to an existing
processor instance
+which can be done:
+
You can then easily use this inside a route by declaring the bean in
Spring, say via the XML:
@@ -28,32 +44,50 @@ Spring, say via the XML:
<bean id="myProcessor" class="com.acme.MyProcessor"/>
----
-Then in Camel you can do:
+And then use the bean id in the Camel route:
+
+[source,xml]
+----
+<route>
+ <from uri="activemq:myQueue"/>
+ <process ref="myProcessor"/>
+</route>
+----
+
+And in Java DSL:
[source,java]
----
from("activemq:myQueue").process("myProcessor");
----
-In your route you can also use the `process` DSL syntax for invoking a
-processor.
+=== Referring to beans using #class syntax
+
+In XML DSL you can also refer to the processor by its class name using
`#class:` as prefix as shown:
+
+[source,xml]
+----
+<route>
+ <from uri="activemq:myQueue"/>
+ <process ref="#class:com.acme.MyProcessor"/>
+</route>
+----
+
+This also works in Java DSL:
[source,java]
----
-Processor myProcessor = new MyProcessor();
-...
-from("activemq:myQueue").process(myProcessor);
+from("activemq:myQueue").process("#class:com.acme.MyProcessor");
----
-If you need to lookup the processor in the xref:registry.adoc[Registry]
-then you can do:
+However in Java DSL you would often use the type safe way and provide the
class type directly as previously shown:
[source,java]
----
-from("activemq:myQueue").process("myProcessor");
+from("activemq:myQueue").process(MyProcessor.class);
----
-[[Processor-Whyuseprocesswhenyoucanusetoinstead]]
+
== Why use process when you can use to instead?
The process can be used in routes as an anonymous inner class such:
@@ -72,19 +106,5 @@ The process can be used in routes as an anonymous inner
class such:
This is usable for quickly whirling up some code. If the code in the
inner class gets a bit more complicated it is of course advised to
refactor it into a separate class. This approach is better if you do not want
to use this processor again.
-From reusability perspective, it is not recommended to follow this approach.
-
-[[Processor-TurningyourprocessorintoafullComponent]]
-== Turning your processor into a full Component
-
-There is a base class called
-https://www.javadoc.io/doc/org.apache.camel/camel-support/current/org/apache/camel/support/ProcessorEndpoint.html[ProcessorEndpoint]
-which supports the full xref:endpoint.adoc[Endpoint] semantics given a
-Processor instance.
-
-So you just need to create a xref:component.adoc[Component] class by
-deriving from
-https://www.javadoc.io/doc/org.apache.camel/camel-support/current/org/apache/camel/support/DefaultComponent.html[DefaultComponent]
-which returns instances of ProcessorEndpoint. For more details see
-xref:writing-components.adoc[Writing Components]
+From reusability perspective, it is not recommended to use this approach with
annonymois inner classes.
