Author: davsclaus
Date: Sat Sep 25 10:55:32 2010
New Revision: 1001191
URL: http://svn.apache.org/viewvc?rev=1001191&view=rev
Log:
CAMEL-3157: Updated javadoc for Exchange
Modified:
camel/trunk/camel-core/src/main/java/org/apache/camel/Exchange.java
Modified: camel/trunk/camel-core/src/main/java/org/apache/camel/Exchange.java
URL:
http://svn.apache.org/viewvc/camel/trunk/camel-core/src/main/java/org/apache/camel/Exchange.java?rev=1001191&r1=1001190&r2=1001191&view=diff
==============================================================================
--- camel/trunk/camel-core/src/main/java/org/apache/camel/Exchange.java
(original)
+++ camel/trunk/camel-core/src/main/java/org/apache/camel/Exchange.java Sat Sep
25 10:55:32 2010
@@ -23,10 +23,40 @@ import org.apache.camel.spi.Synchronizat
import org.apache.camel.spi.UnitOfWork;
/**
- * The base message exchange interface providing access to the request,
response
- * and fault {...@link Message} instances. Different providers such as JMS,
JBI,
- * CXF and HTTP can provide their own derived API to expose the underlying
- * transport semantics to avoid the leaky abstractions of generic APIs.
+ * Exchange is the message container holding the information during the entire
routing.
+ * <p/><br/>
+ * Most noticeable the {...@link Exchange} provides access to the request,
response and
+ * fault {...@link Message} messages.
+ * <p/><br/>
+ * It also provides information about what is known as the
+ * {...@link ExchangePattern Message Exchange Pattern} (or MEP for short). Its
a status
+ * which represents if the message is a <i>one-way</i> or <i>request-reply</i>
exchange pattern.
+ * A <i>one-way</i> pattern is defined as the {...@link
org.apache.camel.ExchangePattern#InOnly}
+ * adn the <i>request-reply</i> is the {...@link
org.apache.camel.ExchangePattern#InOut}.
+ * Those two patterns are the most commonly used. The other patterns is hardly
used at all.
+ * <p/><br/>
+ * The {...@link Exchange} also holds meta-data during the entire lifecycle of
the exchange which
+ * are stored as properties, accessible using the various {...@link
#getProperty(String)} method
+ * and the {...@link #setProperty(String, Object)} is used to store a
property. For example you
+ * can use this to store security related information. Also Camel itself
stores information
+ * as properties, like some of the <a
href="http://camel.apache.org/enterprise-integration-patterns.html";>
+ * Enterprise Integration Patterns</a> does.
+ * <p/><br/>
+ * If an {...@link Exchange} failed during routing the caused {...@link
Exception} is stored and accessible
+ * using the {...@link #getException()} method.
+ * <p/><br/>
+ * <b>Important:</b>
+ * As a Camel end user and you want to update the current {...@link Message}
on the {...@link Exchange} then
+ * you should pay attention. There are two methods two retrieve the message
named as {...@link #getIn()}
+ * and {...@link #getOut()}. This API has been there since Camel 1.0. You most
often should only use
+ * the {...@link #getIn()} method and change the current message by updating
it directly. By doing this
+ * you ensure all the information is kept for further processing. On the other
hand if you use the
+ * {...@link #getOut()} method to update the {...@link Message} then a
<b>new</b> message is created which
+ * means any headers, attachments or the likes from the {...@link #getIn()}
{...@link Message} is lost.
+ * The {...@link #getOut()} method is often only used in special cases or
internally by Camel or specific
+ * Camel components.
+ * <br/>
+ * See also this <a
href="http://camel.apache.org/using-getin-or-getout-methods-on-exchange.html";>FAQ
entry</a> for more details.
*
* @version $Revision$
*/
@@ -249,6 +279,8 @@ public interface Exchange {
* this method.
* <p/>
* <br/>If you want to test whether an OUT message have been set or not,
use the {...@link #hasOut()} method.
+ * <p/>
+ * See also the class java doc for this {...@link Exchange} for more
details.
*
* @return the response
* @see #getIn()
@@ -261,6 +293,8 @@ public interface Exchange {
* <br/><b>Important:</b> If you want to change the current message, then
use {...@link #getIn(Class)} instead as it will
* ensure headers etc. is kept and propagated when routing continues.
Bottom line end users should rarely use
* this method.
+ * <p/>
+ * See also the class java doc for this {...@link Exchange} for more
details.
*
* @param type the given type
* @return the message as the given type or <tt>null</tt> if not possible
to covert to given type
