[CONF] Apache Camel > Using getIn or getOut methods on Exchange

[confluence]

Using getIn or getOut methods on Exchange Page edited by Claus Ibsen Changes (10) h2. Using getIn or getOut methods on Exchange The Camel API is influenced by the [JBI specification|http://en.wikipedia.org/wiki/Java_Business_Integration] which defines a concept called Message Exchange Patterns (MEP for short). The MEP defines the messaging style used such as one-way ([InOnly|Event Message]) or request-reply ([InOut|Request Reply]). The Camel API is influenced by APIs such as [JBI specification|http://en.wikipedia.org/wiki/Java_Business_Integration], [CXF|http://cxf.apache.org/] which defines a concept called Message Exchange Patterns (MEP for short). The MEP defines the messaging style used such as one-way ([InOnly|Event Message]) or request-reply ([InOut|Request Reply]), which means you have IN and optionally OUT messages. This closely maps to other APIs such as WS, WSDL, REST, JBI and the likes. The [Exchange] API provides two methods to get a message, either {{getIn}} or {{getOut}}. Obviously the {{getIn}} gets the IN message, and the {{getOut}} gets the OUT message. {info:title=Important for Camel end users} As a Camel end user you should *always* prefer to use the {{getIn}} method, and frankly just forget about the {{getOut}} method. {info} The {{getOut}} method is only needed in special use cases and by certain Camel component such as the [JBI] or [NMR] components. Now suppose you want to use a Camel [Processor] to adjust a message. This can be done as follows: {code:java} public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the message to say Hello exchange.getOut().setBody("Hello " + body); } {code} If you use the {{getOut}} method, then data from the in message would be lost. For example several Camel end users who got started with Camel, couldn't understand why their message headers was lost during route in Camel. The problem was they used {{getOut}} method in a Camel [Processor]. They should as said use the {{getIn}} method. This seems intuitive and is what you would expect is the _right_ approach to change a message from a [Processor]. However there is an big issue - the {{getOut}} method will create a new [Message], which means any other information from the IN message will not be propagated; which means you will lose that data. To remedy this we'll have to copy the data which is done as follows: {code:java} public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the message to say Hello exchange.getOut().setBody("Hello " + body); // copy headers from IN to OUT to propagate them exchange.getOut().setHeaders(exchange.getIn().getHeaders(); } {code} If you decide to use the {{getOut}} method and want to keep headers, attachments and the likes, then you must manually copy those information from the in to the out message. Well that is not all, a [Message] can also contain attachments so to be sure you need to propagate those as well: {code:java} public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the message to say Hello exchange.getOut().setBody("Hello " + body); // copy headers from IN to OUT to propagate them exchange.getOut().setHeaders(exchange.getIn().getHeaders(); // copy attachements from IN to OUT to propagate them exchange.getOut().setAttachments(exchange.getIn().getAttachments()); } {code} Now we ensure that all additional data is propagated on the new OUT message. But its a shame we need 2 code lines to ensure data is propagated. What you can do instead is to change the IN message instead, as shown below: {code:java} public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the existing message to say Hello exchange.getIn().setBody("Hello " + body); } {code} {tip:title=Consider using getIn} As shown above you most often need to alter the existing IN message, than creating a totally new OUT message. And therefore it's often easier just to adjust the IN message directly. {tip} h3. About Message Exchange Pattern and getOut If the [Exchange] is using {{InOnly}} as the MEP, then you may think that the [Exchange] has no OUT message. But you can still invoke the {{getOut}} method on [Exchange]; Camel will not barf. So the example code above is possible for any kind of MEP. The MEP is _just_ a flag on the [Exchange] which the Consumer and Producer adhere to. You can change the MEP on the [Exchange] using the {{setPattern}} method. And likewise there is DSL to change it as well. Full Content Using getIn or getOut methods on Exchange The Camel API is influenced by APIs such as JBI specification, CXF which defines a concept called Message Exchange Patterns (MEP for short). The MEP defines the messaging style used such as one-way (InOnly) or request-reply (InOut), which means you have IN and optionally OUT messages. This closely maps to other APIs such as WS, WSDL, REST, JBI and the likes. The Exchange API provides two methods to get a message, either getIn or getOut. Obviously the getIn gets the IN message, and the getOut gets the OUT message. Now suppose you want to use a Camel Processor to adjust a message. This can be done as follows: public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the message to say Hello exchange.getOut().setBody("Hello " + body); } This seems intuitive and is what you would expect is the right approach to change a message from a Processor. However there is an big issue - the getOut method will create a new Message, which means any other information from the IN message will not be propagated; which means you will lose that data. To remedy this we'll have to copy the data which is done as follows: public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the message to say Hello exchange.getOut().setBody("Hello " + body); // copy headers from IN to OUT to propagate them exchange.getOut().setHeaders(exchange.getIn().getHeaders(); } Well that is not all, a Message can also contain attachments so to be sure you need to propagate those as well: public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the message to say Hello exchange.getOut().setBody("Hello " + body); // copy headers from IN to OUT to propagate them exchange.getOut().setHeaders(exchange.getIn().getHeaders(); // copy attachements from IN to OUT to propagate them exchange.getOut().setAttachments(exchange.getIn().getAttachments()); } Now we ensure that all additional data is propagated on the new OUT message. But its a shame we need 2 code lines to ensure data is propagated. What you can do instead is to change the IN message instead, as shown below: public void process(Exchange exchange) throws Exception { String body = exchange.getIn().getBody(String.class); // change the existing message to say Hello exchange.getIn().setBody("Hello " + body); } Consider using getIn As shown above you most often need to alter the existing IN message, than creating a totally new OUT message. And therefore it's often easier just to adjust the IN message directly. About Message Exchange Pattern and getOut If the Exchange is using InOnly as the MEP, then you may think that the Exchange has no OUT message. But you can still invoke the getOut method on Exchange; Camel will not barf. So the example code above is possible for any kind of MEP. The MEP is just a flag on the Exchange which the Consumer and Producer adhere to. You can change the MEP on the Exchange using the setPattern method. And likewise there is DSL to change it as well. Change Notification Preferences View Online | View Changes | Add Comment