[CONF] Apache Camel > Wire Tap

[confluence]

Wire Tap Page edited by Reuben Garrett Comment: basic proofreading Changes (31) h3. Wire Tap The [Wire Tap|http://www.enterpriseintegrationpatterns.com/WireTap.html] from the [EIP patterns|Enterprise Integration Patterns] allows you to route messages to a separate tap location while it is forwarded to the ultimate destination. [Wire Tap|http://www.enterpriseintegrationpatterns.com/WireTap.html] (from the [EIP patterns|Enterprise Integration Patterns]) allows you to route messages to a separate location while they are forwarded to the ultimate destination. !http://www.enterpriseintegrationpatterns.com/img/WireTap.gif! {info:title=Streams} If you [Wire Tap] a stream message body then you should consider enable enabling [Stream Caching] to ensure the message body can be re-read. read at each endpoint. See more details at [Stream Caching]. {info} ... {div:class=confluenceTableSmall} || Name || Default Value || Description || | {{uri}} | | The endpoint uri where to send the wire tapped message. You should use either {{uri}} or {{ref}}. | | {{ref}} | | Refers to the endpoint where to send the wire tapped message. You should use either {{uri}} or {{ref}}. | | {{executorServiceRef}} | | Refers to a custom [Thread Pool|Threading Model] to be used when processing the wire tapped messages. If not set then Camel uses a default thread pool. | | {{processorRef}} | | Refers to a custom [Processor] to be used for creating a new message (eg the send a new message mode). See below. | | {{copy}} | {{true}} | *Camel 2.3*: Should a copy of the [Exchange] to used when wire tapping the message. | | {{onPrepareRef}} | | *Camel 2.8:* Refers to a custom [Processor] to prepare the copy of the [Exchange] to be wire tapped. This allows you to do any custom logic, such as deep-cloning the message payload if that's needed etc. | | {{uri}} | | The URI of the endpoint to which the wire-tapped message will be sent. You should use either {{uri}} or {{ref}}. | | {{ref}} | | Reference identifier of the endpoint to which the wire-tapped message will be sent. You should use either {{uri}} or {{ref}}. | | {{executorServiceRef}} | | Reference identifier of a custom [Thread Pool|Threading Model] to use when processing the wire-tapped messages. If not set, Camel will use a default thread pool. | | {{processorRef}} | | Reference identifier of a custom [Processor] to use for creating a new message (e.g., the "send a new message" mode). See below. | | {{copy}} | {{true}} | *Camel 2.3*: Whether to copy the [Exchange] before wire-tapping the message. | | {{onPrepareRef}} | | *Camel 2.8:* Reference identifier of a custom [Processor] to prepare the copy of the [Exchange] to be wire-tapped. This allows you to do any custom logic, such as deep-cloning the message payload. | {div} ... h3. WireTap thread pool The [Wire Tap] uses a thread pool to process the tapped messages. The thread pool will by default use the default settings. You can read more details at [Threading Model]. The default settings will when the thread pool exhaust (the worker queue is filled up, and no idle threads), will use the current caller thread as well. This means the wire tap will not be asynchronous at that incident. To remedy this you can configure an explicit thread pool on the [Wire Tap] having either a different rejection policy, or a larger worker queue, or more worker threads etc. The [Wire Tap] uses a thread pool to process the tapped messages. This thread pool will by default use the settings detailed at [Threading Model]. In particular, when the pool is exhausted (with all threads utilized), further wiretaps will be executed synchronously by the calling thread. To remedy this, you can configure an explicit thread pool on the [Wire Tap] having either a different rejection policy, a larger worker queue, or more worker threads. h3. WireTap node *Available as of Camel 2.0* In Camel 2.0 we have introduced a new *wireTap* node for properly doing wire taps. Camel will copy the original [Exchange] and set its [Exchange Pattern] to *InOnly* as we want the tapped [Exchange] to be sent as a _fire and forget_ style. The tapped [Exchange] is then send in a separate thread so it can run in parallel with the original In Camel 2.0 we have introduced a new *wireTap* node to facilitate wiretaps. Camel will copy the original [Exchange] and set its [Exchange Pattern] to *InOnly*, as we want the tapped [Exchange] to be sent in a _fire and forget_ style. The tapped [Exchange] is then sent in a separate thread so it can run in parallel with the original. We have extended the *wireTap* to support two flavors when tapping an [Exchange]: - send a copy of the original [Exchange] (the traditional wire tap) - send a new [Exchange], allowing you to populate the [Exchange] it beforehand h4. Sending a copy (traditional wire tap) *Using the [Fluent Builders]* {snippet:id=e1|lang=java|url="" ... h4. Sending a new [Exchange] *Using the [Fluent Builders]* Camel supports either a processor or an [_expression_] to populate the new [Exchange]. Using a processor gives you full power over how the [Exchange] is populated as you can set properties, headers etc. The headers, et cetera. An [_expression_] can only be used to set the IN body. From *Camel 2.3* onwards the [_expression_] or [Processor] is pre populated with a copy of the original [Exchange] which allows you to access the original message when you prepare the new [Exchange] to be sent. You can use the {{copy}} option to indicate if you want this or not (default is enabled). If your turn {{copy=false}} then it works as in Camel 2.2 or older, where the [Exchange] always will be empty. From *Camel 2.3* onwards the [_expression_] or [Processor] is pre-populated with a copy of the original [Exchange], which allows you to access the original message when you prepare a new [Exchange] to be sent. You can use the {{copy}} option (enabled by default) to indicate whether you want this. If you set {{copy=false}}, then it works as in Camel 2.2 or older where the [Exchange] will be empty. Below is the processor variation shown. This example is from Camel 2.3, where we disable {{copy}} by passing in {{false}}. This will create a new empty [Exchange]. Below is the processor variation. This example is from Camel 2.3, where we disable {{copy}} by passing in {{false}} to create a new, empty [Exchange]. {snippet:id=e1|lang=java|url="" And the [_expression_] variation. This example is from Camel 2.3, where we disable {{copy}} by passing in {{false}}. This will create a new empty [Exchange]. Here is the [_expression_] variation. This example is from Camel 2.3, where we disable {{copy}} by passing in {{false}} to create a new, empty [Exchange]. {snippet:id=e2|lang=java|url="" *Using the [Spring XML Extensions]* The processor variation, notice we use a *processorRef* attribute to refer to a spring bean with this id: The processor variation, which uses a *processorRef* attribute to refer to a Spring bean by ID: {snippet:id=e2|lang=xml|url="" And Here is the [_expression_] variation, where the _expression_ is defined in the *body* tag: {snippet:id=e1|lang=xml|url="" And this variation accesses the body of the original message and creates a new [Exchange] which is based on the [_expression_]. This variation accesses the body of the original message and creates a new [Exchange] based on the [_expression_]. It will create a new Exchange and have the body contain {{"Bye ORIGINAL BODY MESSAGE HERE"}} {snippet:id=e1|lang=xml|url="" h3. Camel 1.x The following example shows how to route a request from an input *queue:a* endpoint to the wire tap location *queue:tap* before it is received by *queue:b* *Using the [Fluent Builders]* ... h4. Further Example For another example of this pattern in use you could look at pattern, refer to the [wire tap test case|http://svn.apache.org/repos/asf/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/WireTapTest.java]. h3. Sending a new [Exchange] and set headers in DSL *Available as of Camel 2.8* If you send a new messages using the [Wire Tap] then you could only set the message body using an [_expression_] from the DSL. If you also need to set new headers you would have to use a [Processor] for that. So in Camel 2.8 onwards we have improved this situation so you can now set headers as well in the DSL. If you send a new message using [Wire Tap], then you could only set the message body using an [_expression_] from the DSL. If you also need to set headers, you would have to use a [Processor]. In Camel 2.8 onwards, you can now set headers as well in the DSL. The following example sends a new message which has ... h4. XML DSL The XML DSL is slightly different than Java DSL as how you configure the message body and headers. In XML you use <body> and <setHeader> as shown: The XML DSL is slightly different than Java DSL in how you configure the message body and headers using <body> and <setHeader>: {snippet:id=e1|lang=xml|url="" ... Full Content Wire Tap Wire Tap (from the EIP patterns) allows you to route messages to a separate location while they are forwarded to the ultimate destination. Streams If you Wire Tap a stream message body then you should consider enabling Stream caching to ensure the message body can be read at each endpoint. See more details at Stream caching. Options Name Default Value Description uri   The URI of the endpoint to which the wire-tapped message will be sent. You should use either uri or ref. ref   Reference identifier of the endpoint to which the wire-tapped message will be sent. You should use either uri or ref. executorServiceRef   Reference identifier of a custom Thread Pool to use when processing the wire-tapped messages. If not set, Camel will use a default thread pool. processorRef   Reference identifier of a custom Processor to use for creating a new message (e.g., the "send a new message" mode). See below. copy true Camel 2.3: Whether to copy the Exchange before wire-tapping the message. onPrepareRef   Camel 2.8: Reference identifier of a custom Processor to prepare the copy of the Exchange to be wire-tapped. This allows you to do any custom logic, such as deep-cloning the message payload. WireTap thread pool The Wire Tap uses a thread pool to process the tapped messages. This thread pool will by default use the settings detailed at Threading Model. In particular, when the pool is exhausted (with all threads utilized), further wiretaps will be executed synchronously by the calling thread. To remedy this, you can configure an explicit thread pool on the Wire Tap having either a different rejection policy, a larger worker queue, or more worker threads. WireTap node Available as of Camel 2.0 In Camel 2.0 we have introduced a new wireTap node to facilitate wiretaps. Camel will copy the original Exchange and set its Exchange Pattern to InOnly, as we want the tapped Exchange to be sent in a fire and forget style. The tapped Exchange is then sent in a separate thread so it can run in parallel with the original. We have extended wireTap to support two flavors when tapping an Exchange: send a copy of the original Exchange (the traditional wiretap) send a new Exchange, allowing you to populate it beforehand Sending a copy (traditional wiretap) Using the Fluent Builders from("direct:start") .to("log:foo") .wireTap("direct:tap") .to("mock:result"); Using the Spring XML Extensions <route> <from uri="direct:start"/> <to uri="log:foo"/> <wireTap uri="direct:tap"/> <to uri="mock:result"/> </route> Sending a new Exchange Using the Fluent Builders Camel supports either a processor or an _expression_ to populate the new Exchange. Using a processor gives you full power over how the Exchange is populated as you can set properties, headers, et cetera. An _expression_ can only be used to set the IN body. From Camel 2.3 onwards the _expression_ or Processor is pre-populated with a copy of the original Exchange, which allows you to access the original message when you prepare a new Exchange to be sent. You can use the copy option (enabled by default) to indicate whether you want this. If you set copy=false, then it works as in Camel 2.2 or older where the Exchange will be empty. Below is the processor variation. This example is from Camel 2.3, where we disable copy by passing in false to create a new, empty Exchange. from("direct:start") .wireTap("direct:foo", false, new Processor() { public void process(Exchange exchange) throws Exception { exchange.getIn().setBody("Bye World"); exchange.getIn().setHeader("foo", "bar"); } }).to("mock:result"); from("direct:foo").to("mock:foo"); Here is the _expression_ variation. This example is from Camel 2.3, where we disable copy by passing in false to create a new, empty Exchange. from("direct:start") .wireTap("direct:foo", false, constant("Bye World")) .to("mock:result"); from("direct:foo").to("mock:foo"); Using the Spring XML Extensions The processor variation, which uses a processorRef attribute to refer to a Spring bean by ID: <route> <from uri="direct:start2"/> <wireTap uri="direct:foo" processorRef="myProcessor"/> <to uri="mock:result"/> </route> Here is the _expression_ variation, where the _expression_ is defined in the body tag: <route> <from uri="direct:start"/> <wireTap uri="direct:foo"> <body><constant>Bye World</constant></body> </wireTap> <to uri="mock:result"/> </route> This variation accesses the body of the original message and creates a new Exchange based on the _expression_. It will create a new Exchange and have the body contain "Bye ORIGINAL BODY MESSAGE HERE" <route> <from uri="direct:start"/> <wireTap uri="direct:foo"> <body><simple>Bye ${body}</simple></body> </wireTap> <to uri="mock:result"/> </route> Camel 1.x The following example shows how to route a request from an input queue:a endpoint to the wire tap location queue:tap before it is received by queue:b Using the Fluent Builders RouteBuilder builder = new RouteBuilder() { public void configure() { errorHandler(deadLetterChannel("mock:error")); from("seda:a") .multicast().to("seda:tap", "seda:b"); } }; Using the Spring XML Extensions <camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/spring"> <route> <from uri="seda:a"/> <multicast> <to uri="seda:tap"/> <to uri="seda:b"/> </multicast> </route> </camelContext> Further Example For another example of this pattern, refer to the wire tap test case. Sending a new Exchange and set headers in DSL Available as of Camel 2.8 If you send a new message using Wire Tap, then you could only set the message body using an _expression_ from the DSL. If you also need to set headers, you would have to use a Processor. In Camel 2.8 onwards, you can now set headers as well in the DSL. The following example sends a new message which has "Bye World" as message body a header with key "id" with the value 123 a header with key "date" which has current date as value Java DSL from("direct:start") // tap a new message and send it to direct:tap // the new message should be Bye World with 2 headers .wireTap("direct:tap") // create the new tap message body and headers .newExchangeBody(constant("Bye World")) .newExchangeHeader("id", constant(123)) .newExchangeHeader("date", simple("${date:now:yyyyMMdd}")) .end() // here we continue routing the original messages .to("mock:result"); // this is the tapped route from("direct:tap") .to("mock:tap"); XML DSL The XML DSL is slightly different than Java DSL in how you configure the message body and headers using <body> and <setHeader>: <route> <from uri="direct:start"/> <!-- tap a new message and send it to direct:tap --> <!-- the new message should be Bye World with 2 headers --> <wireTap uri="direct:tap"> <!-- create the new tap message body and headers --> <body><constant>Bye World</constant></body> <setHeader headerName="id"><constant>123</constant></setHeader> <setHeader headerName="date"><simple>${date:now:yyyyMMdd}</simple></setHeader> </wireTap> <!-- here we continue routing the original message --> <to uri="mock:result"/> </route> Using onPrepare to execute custom logic when preparing messages Available as of Camel 2.8 See details at Multicast 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. Change Notification Preferences View Online | View Changes | Add Comment