Repository: camel Updated Branches: refs/heads/master cc7dd1059 -> a3fffb9f8
CAMEL-11786: Migrate docs to more correct ascii doc format Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/a3fffb9f Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/a3fffb9f Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/a3fffb9f Branch: refs/heads/master Commit: a3fffb9f87fb9df1c7a2205be30c42870e2fe1e7 Parents: cc7dd10 Author: Claus Ibsen <davscl...@apache.org> Authored: Wed Sep 20 11:06:17 2017 +0200 Committer: Claus Ibsen <davscl...@apache.org> Committed: Wed Sep 20 11:06:22 2017 +0200 ---------------------------------------------------------------------- camel-core/src/main/docs/eips/log-eip.adoc | 124 +++++++++++++---------- camel-core/src/main/docs/eips/loop-eip.adoc | 81 ++++++++------- 2 files changed, 113 insertions(+), 92 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/a3fffb9f/camel-core/src/main/docs/eips/log-eip.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/eips/log-eip.adoc b/camel-core/src/main/docs/eips/log-eip.adoc index 18cc0e9..153229f 100644 --- a/camel-core/src/main/docs/eips/log-eip.adoc +++ b/camel-core/src/main/docs/eips/log-eip.adoc @@ -8,6 +8,8 @@ Camel provides many ways to log the fact that you are processing a message. Here * You can also use a link:processor.html[Processor] or link:bean.html[Bean] and log from Java code. * You can use the log DSL. +=== Options + // eip options: START The Log EIP supports 5 options which are listed below: @@ -24,77 +26,82 @@ The Log EIP supports 5 options which are listed below: // eip options: END -== Using log DSL +==== Difference between log in the DSL and Log component +The log DSL is much lighter and meant for logging human logs such as Starting to do ... etc. It can only log a message based on the Simple language. On the other hand Log component is a full fledged component which involves using endpoints and etc. The Log component is meant for logging the Message itself and you have many URI options to control what you would like to be logged. + +=== Samples In *Camel 2.2* you can use the log DSL which allows you to use link:simple.html[Simple] language to construct a dynamic message which gets logged. For example you can do [source,java] --------------------------------------------------------- -from("direct:start").log("Processing ${id}").to("bean:foo"); --------------------------------------------------------- +---- +from("direct:start") + .log("Processing ${id}") + .to("bean:foo"); +---- Which will construct a String message at runtime using the Simple language. The log message will by logged at INFO level using the route id as the log name. By default a route is named route-1, route-2 etc. But you can use the routeId("myCoolRoute") to set a route name of choice. -INFO:Difference between log in the DSL and [Log] component -The log DSL is much lighter and meant for logging human logs such as Starting to do ... etc. It can only log a message based on the Simple language. On the other hand Log component is a full fledged component which involves using endpoints and etc. The Log component is meant for logging the Message itself and you have many URI options to control what you would like to be logged. - -INFO:Using Logger instance from the the Registry -As of *Camel 2.12.4/2.13.1*, if no logger name or logger instance is passed to log DSL, there is a Registry lookup performed to find single instance of org.slf4j.Logger. If such an instance is found, it is used instead of creating a new logger instance. If more instances are found, the behavior defaults to creating a new instance of logger. - -INFO:Logging message body with streamed messages +TIP: *Logging message body with streamed messages:* If the message body is stream based, then logging the message body, may cause the message body to be empty afterwards. See this FAQ. For streamed messages you can use Stream caching to allow logging the message body and be able to read the message body afterwards again. The log DSL have overloaded methods to set the logging level and/or name as well. [source,java] --------------------------------------------------------- -from("direct:start").log(LoggingLevel.DEBUG, "Processing ${id}").to("bean:foo"); --------------------------------------------------------- +---- +from("direct:start") + .log(LoggingLevel.DEBUG, "Processing ${id}") + .to("bean:foo"); +---- and to set a logger name [source,java] --------------------------------------------------------- -from("direct:start").log(LoggingLevel.DEBUG, "com.mycompany.MyCoolRoute", "Processing ${id}").to("bean:foo"); --------------------------------------------------------- +---- +from("direct:start") + .log(LoggingLevel.DEBUG, "com.mycompany.MyCoolRoute", "Processing ${id}") + .to("bean:foo"); +---- Since *Camel 2.12.4/2.13.1* the logger instance may be used as well: [source,java] --------------------------------------------------------- -from("direct:start").log(LoggingLeven.DEBUG, org.slf4j.LoggerFactory.getLogger("com.mycompany.mylogger"), "Processing ${id}").to("bean:foo"); --------------------------------------------------------- +---- +from("direct:start") + .log(LoggingLeven.DEBUG, org.slf4j.LoggerFactory.getLogger("com.mycompany.mylogger"), "Processing ${id}") + .to("bean:foo"); +---- For example you can use this to log the file name being processed if you consume files. [source,java] --------------------------------------------------------- -from("file://target/files").log(LoggingLevel.DEBUG, "Processing file ${file:name}").to("bean:foo"); --------------------------------------------------------- - -=== Using log DSL from Spring +---- +from("file://target/files") + .log(LoggingLevel.DEBUG, "Processing file ${file:name}") + .to("bean:foo"); +---- In Spring DSL it is also easy to use log DSL as shown below: [source,xml] --------------------------------------------------------- +---- <route id="foo"> <from uri="direct:foo"/> <log message="Got ${body}"/> <to uri="mock:foo"/> </route> --------------------------------------------------------- +---- The log tag has attributes to set the message, loggingLevel and logName. For example: [source,xml] --------------------------------------------------------- +---- <route id="baz"> <from uri="direct:baz"/> <log message="Me Got ${body}" loggingLevel="FATAL" logName="com.mycompany.MyCoolRoute"/> <to uri="mock:baz"/> </route> --------------------------------------------------------- +---- Since Camel *2.12.4/2.13.1* it is possible to reference logger instance. For example: [source,xml] --------------------------------------------------------- +---- <bean id="myLogger" class="org.slf4j.LoggerFactory" factory-method="getLogger" xmlns="http://www.springframework.org/schema/beans";> <constructor-arg value="com.mycompany.mylogger" /> </bean> @@ -104,7 +111,14 @@ Since Camel *2.12.4/2.13.1* it is possible to reference logger instance. For exa <log message="Me Got ${body}" loggingLevel="INFO" loggerRef="myLogger"/> <to uri="mock:baz"/> </route> --------------------------------------------------------- +---- + +==== Using Logger instance from the the Registry + +As of *Camel 2.12.4/2.13.1*, if no logger name or logger instance is passed to log DSL, + there is a Registry lookup performed to find single instance of org.slf4j.Logger. + If such an instance is found, it is used instead of creating a new logger instance. + If more instances are found, the behavior defaults to creating a new instance of logger. === Configuring log name globally *Available as of Camel 2.17* @@ -113,32 +127,33 @@ By default the log name is the route id. If you want to use a different log name With Camel 2.17 onwards you can configure a global log name that is used instead of the route id, eg [source,java] --------------------------------------------------------- -CamelContext context = ... -context.getProperties().put(Exchange.LOG_EIP_NAME, "com.foo.myapp"); --------------------------------------------------------- +---- +camelContext.getProperties().put(Exchange.LOG_EIP_NAME, "com.foo.myapp"); +---- And in XML [source,xml] --------------------------------------------------------- +---- <camelContext ...> <properties> <property key="CamelLogEipName" value="com.foo.myapp"/> </properties> --------------------------------------------------------- +</camelContext> +---- === Using slf4j Marker *Available as of Camel 2.9* You can specify a marker name in the DSL [source,xml] --------------------------------------------------------- +---- <route id="baz"> <from uri="direct:baz"/> - <log message="Me Got ${body}" loggingLevel="FATAL" logName="com.mycompany.MyCoolRoute" marker="myMarker"/> + <log loggingLevel="FATAL" logName="com.mycompany.MyCoolRoute" marker="myMarker" + message="Me Got ${body}"/> <to uri="mock:baz"/> </route> --------------------------------------------------------- +---- === Using log DSL in OSGi *Improvement as of Camel 2.12.4/2.13.1* @@ -155,36 +170,35 @@ Note that this option also affects link:log.html[Log] component. To enable mask in Java DSL at CamelContext level: [source,java] --------------------------------------------------------- -CamelContext context = ... -context.setLogMask(true); --------------------------------------------------------- +---- +camelContext.setLogMask(true); +---- And in XML: [source,java] --------------------------------------------------------- +---- <camelContext logMask="true"> ... --------------------------------------------------------- - +</camelContext> +---- You can also turn it on|off at route level. To enable mask in Java DSL at route level: [source,java] --------------------------------------------------------- -from("direct:start").logMask().log("Processing ${id}").to("bean:foo"); --------------------------------------------------------- +---- +from("direct:start").logMask() + .log("Processing ${id}") + .to("bean:foo"); +---- And in XML: [source,java] --------------------------------------------------------- +---- <route logMask="true"> ... --------------------------------------------------------- +</route> +---- `org.apache.camel.processor.DefaultMaskingFormatter` is used for the masking by default. If you want to use a custom masking formatter, put it into registry with the name `CamelCustomLogMask`. Note that the masking formatter must implement `org.apache.camel.spi.MaskingFormatter`. - -=== Using This Pattern -If you would like to use this EIP Pattern then please read the link:getting-started.html[Getting Started], you may also find the link:architecture.html[Architecture] useful particularly the description of link:endpoint.html[Endpoint] and link:uris.html[URIs]. Then you could try out some of the link:examples.html[Examples] first before trying this pattern out. http://git-wip-us.apache.org/repos/asf/camel/blob/a3fffb9f/camel-core/src/main/docs/eips/loop-eip.adoc ---------------------------------------------------------------------- diff --git a/camel-core/src/main/docs/eips/loop-eip.adoc b/camel-core/src/main/docs/eips/loop-eip.adoc index 9c604f0..6a80cd2 100644 --- a/camel-core/src/main/docs/eips/loop-eip.adoc +++ b/camel-core/src/main/docs/eips/loop-eip.adoc @@ -1,4 +1,5 @@ == Loop EIP + The Loop allows for processing a message a number of times, possibly in a different way for each iteration. Useful mostly during testing. [NOTE] @@ -23,40 +24,48 @@ The Loop EIP supports 2 options which are listed below: === Exchange properties + For each iteration two properties are set on the Exchange. Processors can rely on these properties to process the Message in different ways. + [width="100%",cols="3,6",options="header"] -|======================================================================= +|=== | Property | Description | CamelLoopSize | Total number of loops. This is not available if running the loop in while loop mode. | CamelLoopIndex | Index of the current iteration (0 based) -|======================================================================= +|=== -=== Examples +=== Samples The following example shows how to take a request from the *direct:x* endpoint, then send the message repetitively to *mock:result*. The number of times the message is sent is either passed as an argument to `loop()`, or determined at runtime by evaluating an expression. The expression *must* evaluate to an int, otherwise a `RuntimeCamelException` is thrown. -#=== Using the Fluent Builders Pass loop count as an argument [source,java] ---------------------- -from("direct:a").loop(8).to("mock:result"); ---------------------- +---- +from("direct:a") + .loop(8) + .to("mock:result"); +---- Use expression to determine loop count [source,java] ---------------------- -from("direct:b").loop(header("loop")).to("mock:result"); ---------------------- +---- +from("direct:b") + .loop(header("loop")) + .to("mock:result"); +---- Use expression to determine loop count [source,java] ---------------------- -from("direct:c").loop().xpath("/hello/@times").to("mock:result"); ---------------------- +---- +from("direct:c") + .loop(xpath("/hello/@times")) + .to("mock:result"); +---- + +And examples in XML: -#=== Using the Spring XML Extensions Pass loop count as an argument [source,xml] ---------------------- +---- <route> <from uri="direct:a"/> <loop> @@ -64,11 +73,11 @@ Pass loop count as an argument <to uri="mock:result"/> </loop> </route> ---------------------- +---- Use expression to determine loop count [source,xml] ---------------------- +---- <route> <from uri="direct:b"/> <loop> @@ -76,45 +85,44 @@ Use expression to determine loop count <to uri="mock:result"/> </loop> </route> ---------------------- - -For further examples of this pattern in use you could look at one of the junit test case. +---- -#=== Using copy mode +=== Using copy mode *Available as of Camel 2.8* + + Now suppose we send a message to "direct:start" endpoint containing the letter A. + The output of processing this route will be that, each "mock:loop" endpoint will receive "AB" as message. [source,java] ---------------------- +---- from("direct:start") // instruct loop to use copy mode, which mean it will use a copy of the input exchange // for each loop iteration, instead of keep using the same exchange all over .loop(3).copy() .transform(body().append("B")) .to("mock:loop") - .end() + .end() // end loop .to("mock:result"); ---------------------- +---- However if we do *not* enable copy mode then "mock:loop" will receive "AB", "ABB", "ABBB", etc. messages. [source,java] ---------------------- +---- from("direct:start") // by default loop will keep using the same exchange so on the 2nd and 3rd iteration its // the same exchange that was previous used that are being looped all over .loop(3) .transform(body().append("B")) .to("mock:loop") - .end() + .end() // end loop .to("mock:result"); ---------------------- +---- The equivalent example in XML DSL in copy mode is as follows: [source,xml] ---------------------- +---- <route> <from uri="direct:start"/> <!-- enable copy mode for loop eip --> @@ -127,26 +135,27 @@ The equivalent example in XML DSL in copy mode is as follows: </loop> <to uri="mock:result"/> </route> ---------------------- +---- -#=== Using while mode +=== Using while mode *Available as of Camel 2.17* + + The loop can act like a while loop that loops until the expression evaluates to false or null. + For example the route below loops while the length of the message body is 5 or less characters. Notice that the DSL uses *loopDoWhile*. [source,java] ---------------------- +---- from("direct:start") .loopDoWhile(simple("${body.length} <= 5")) .to("mock:loop") .transform(body().append("A")) - .end() + .end() // end loop .to("mock:result"); ---------------------- +---- And the same example in XML: [source,xml] ---------------------- +---- <route> <from uri="direct:start"/> <loop doWhile="true"> @@ -158,9 +167,7 @@ And the same example in XML: </loop> <to uri="mock:result"/> </route> ---------------------- +---- Notice in XML that the while loop is turned on using the *doWhile* attribute. -=== Using This Pattern -If you would like to use this EIP Pattern then please read the Getting Started, you may also find the Architecture useful particularly the description of Endpoint and URIs. Then you could try out some of the Examples first before trying this pattern out.
