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 68db2e5 CAMEL-16861: Cleanup and update EIP docs 68db2e5 is described below commit 68db2e58039825ac51b14934a6f60e01a9e1391b Author: Claus Ibsen <claus.ib...@gmail.com> AuthorDate: Mon Oct 11 12:10:45 2021 +0200 CAMEL-16861: Cleanup and update EIP docs --- .../src/main/java/org/apache/camel/Processor.java | 1 + .../eips/images/eip/message_flow_in_route.png | Bin 0 -> 13415 bytes .../main/docs/modules/eips/pages/process-eip.adoc | 119 +++++++++++++-------- 3 files changed, 76 insertions(+), 44 deletions(-) diff --git a/core/camel-api/src/main/java/org/apache/camel/Processor.java b/core/camel-api/src/main/java/org/apache/camel/Processor.java index 8cbc1d8..11ddc12 100644 --- a/core/camel-api/src/main/java/org/apache/camel/Processor.java +++ b/core/camel-api/src/main/java/org/apache/camel/Processor.java @@ -26,6 +26,7 @@ package org.apache.camel; * thread-safe way, as the Camel routes can potentially be executed by concurrent threads, and therefore multiple * threads can call the same {@link Processor} instance. */ +@FunctionalInterface public interface Processor { /** diff --git a/core/camel-core-engine/src/main/docs/modules/eips/images/eip/message_flow_in_route.png b/core/camel-core-engine/src/main/docs/modules/eips/images/eip/message_flow_in_route.png new file mode 100644 index 0000000..07b4637 Binary files /dev/null and b/core/camel-core-engine/src/main/docs/modules/eips/images/eip/message_flow_in_route.png differ diff --git a/core/camel-core-engine/src/main/docs/modules/eips/pages/process-eip.adoc b/core/camel-core-engine/src/main/docs/modules/eips/pages/process-eip.adoc index 5cf894b..7b0aa0a 100644 --- a/core/camel-core-engine/src/main/docs/modules/eips/pages/process-eip.adoc +++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/process-eip.adoc @@ -5,19 +5,52 @@ :since: :supportlevel: Stable -The http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Processor.html[Processor] interface is used to implement consumers of message exchanges or to implement a xref:message-translator.adoc[Message Translator] +The http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Processor.html[Processor] +is used for processing message xref:latest@manual:ROOT:exchange.adoc[Exchanges]. -== Options +The processor is a core Camel concept that represents a node capable of using, creating, +or modifying an incoming exchange. During routing, exchanges flow from one processor +to another; as such, you can think of a route as a graph having specialized processors +as the nodes, and lines that connect the output of one processor to the input of another. +Processors could be implementations of EIPs, producers for specific components, or +your own custom creation. The figure below shows the flow between processors. -// eip options: START -include::partial$eip-options.adoc[] -// eip options: END +image::eip/message_flow_in_route.png[image] -== Samples +A route first starts with a consumer (think `from` in the DSL) that populates the initial +exchange. At each processor step, the out message from the previous step is the in +message of the next. In many cases, processors don’t set an out message, so in this case +the in message is reused. At the end of a route, the xref:latest@manual:ROOT:exchange-pattern.adoc[Messageg Exchange Pattern] (MEP) +of the exchange determines whether a reply needs to be sent back to the caller of the route. If the MEP is `InOnly`, +no reply will be sent back. If it’s `InOut`, Camel will take the out message from the last +step and return it. + +== Processor API + +The `Processor` interface is a central API in Camel. +Its API is purposely designed to be both simple and flexible in the form of a single functional method: + +[source,java] +---- +@FunctionalInterface +public interface Processor { + + /** + * Processes the message exchange + * + * @param exchange the message exchange + * @throws Exception if an internal processing error has occurred. + */ + void process(Exchange exchange) throws Exception; +} +---- + +The `Processor` is used heavily internally in Camel, such as the base for all implementations of +the xref:enterprise-integration-patterns.adoc[EIP patterns]. === 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] ---- @@ -28,43 +61,54 @@ public class MyProcessor implements Processor { } ---- -You can then easily use this inside a route by declaring the bean in -Spring, say via the XML (or registering it in JNDI if that is your -xref:latest@manual:ROOT:registry.adoc[Registry]) +Then in Camel you can call this processor: -[source,xml] --------------------------------------------------------- -<bean id="myProcessor" class="com.acme.MyProcessor"/> --------------------------------------------------------- +[source,java] +---- +from("activemq:myQueue") + .process(new MyProcessor()); +---- -Then in Camel you can do +You can also call a processor by its bean id, if the processor +has been enlisted in the xref:latest@manual:ROOT:registry.adoc[Registry], such as with the id `myProcessor`: [source,java] ---- -from("activemq:myQueue").to("myProcessor"); +from("activemq:myQueue") + .process("myProcessor"); ---- -=== Using the process DSL +And in XML you can refer to the fully qualified class name via `#class:` syntax: -In your route you can also use the `process` DSL syntax for invoking a -processor. - -[source,java] +[source,xml] ---- -Processor myProcessor = new MyProcessor(); -... -from("activemq:myQueue").process(myProcessor); +<route> + <from uri="activemq:myQueue"/> + <process ref="#class:com.foo.MyProcessor"/> +</route> ---- -If you need to lookup the processor in the xref:latest@manual:ROOT:registry.adoc[Registry] -then you should use the *processRef* DSL: +Or if you use Spring XML you can create the processor via `<bean>`: -[source,java] +[source,xml] ---- -from("activemq:myQueue").processRef("myProcessor"); +<beans> + + <bean id="myProcessor" class="com.foo.MyProcessor"/> + + <camelContext> + <routes> + <route> + <from uri="activemq:myQueue"/> + <process ref="myProcessor"/> + </route> + </routes> + </camelContext> + +</beans> ---- -== Why use process when you can use to instead? +=== Why use process when you can use to instead? The process can be used in routes as an anonymous inner class such: @@ -72,9 +116,9 @@ The process can be used in routes as an anonymous inner class such: ---- from("activemq:myQueue").process(new Processor() { public void process(Exchange exchange) throws Exception { - String payload = exchange.getIn().getBody(String.class); + String payload = exchange.getMessage().getBody(String.class); // do something with the payload and/or exchange here - exchange.getIn().setBody("Changed body"); + exchange.getMessage().setBody("Changed body"); } }).to("activemq:myOtherQueue"); ---- @@ -82,16 +126,3 @@ 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. - -== Turning your processor into a full Component - -There is a base class called -http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/impl/ProcessorEndpoint.html[ProcessorEndpoint] -which supports the full xref:latest@manual:ROOT:endpoint.adoc[Endpoint] semantics given a -Processor instance. - -So you just need to create a https://github.com/apache/camel/tree/main/components[Component] class by -deriving from -http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/impl/DefaultComponent.html[DefaultComponent] -which returns instances of ProcessorEndpoint. For more details see -xref:latest@manual:ROOT:writing-components.adoc[Writing Components]