svn commit: r1023524 - /camel/trunk/camel-core/src/main/java/org/apache/camel/Exchange.java

[ha...@apache.org]

Author: hadrian
Date: Sun Oct 17 16:40:37 2010
New Revision: 1023524

URL: http://svn.apache.org/viewvc?rev=1023524&view=rev
Log:
Updated javadoc for the Exchange api

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=1023524&r1=1023523&r2=1023524&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 Sun Oct 17 16:40:37 2010
@@ -23,46 +23,50 @@ import org.apache.camel.spi.Synchronizat
 import org.apache.camel.spi.UnitOfWork;
 
 /**
- * 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.
- * <br/>
- * See this <a href="http://camel.apache.org/using-getin-or-getout-methods-on-exchange.html">FAQ entry</a> for more details.
- * <p/><br/>
- * The {@link ExchangePattern Message Exchange Pattern} and the {@link #getIn()} and {@link #getOut()} methods
- * are <b>not</b> strictly mapped. For example if the MEP is {@link org.apache.camel.ExchangePattern#InOnly} then
- * you can still invoke the {@link #getOut()} method. The {@link ExchangePattern Message Exchange Pattern} is
- * essentially just a flag to indicate the message pattern. That means you can still set an OUT message using
- * the {@link #getOut()} method despite the pattern is {@link org.apache.camel.ExchangePattern#InOnly}.
- *
- * @version $Revision$
+ * An Exchange is the message container holding the information during the entire routing of
+ * a {@link  Message} received by a {@link Consumer}. 
+ * <p/>
+ * During processing down the {@link Processor} chain, the {@link Exchange} provides access to the 
+ * current (not the original) request and response {@link Message} messages. The {@link Exchange} 
+ * also holds meta-data during its entire lifetime stored as properties accessible using the 
+ * various {@link #getProperty(String)} methods. The {@link #setProperty(String, Object)} is 
+ * used to store a property. For example you can use this to store security, SLA related 
+ * data or any other information deemed useful throughout processing. If an {@link Exchange} 
+ * failed during routing the {@link Exception} that caused the failure is stored and accessible 
+ * via the {@link #getException()} method.
+ * <p/>
+ * An Exchange is created when a {@link Consumer} receives a request. A new {@link Message} is
+ * created, the request is set as the body of the {@link Message} and depending on the {@link Consumer}
+ * other {@link Endpoint} and protocol related information is added as headers on the {@link Message}.
+ * Then an Exchange is created and the newly created {@link Message} is set as the in on the Exchange.
+ * Therefore an Exchange starts its life in a {@link Consumer}. The Exchange is then sent down the
+ * {@link Route} for processing along a {@link Processor} chain. The {@link Processor} as the name
+ * suggests is what processes the {@link Message} in the Exchange and Camel, in addition to 
+ * providing out-of-the-box a large number of useful processors, it also allows you to create your own. 
+ * The rule Camel uses is to take the out {@link Message} produced by the previous {@link Processor} 
+ * and set it as the in for the next {@link Processor}. If the previous {@link Processor} did not
+ * produce an out, then the in of the previous {@link Processor} is sent as the next in. At the
+ * end of the processing chain, depending on the {@link ExchangePattern Message Exchange Pattern} (or MEP)
+ * the last out (or in of no out available) is sent by the {@link Consumer} back to the original caller.
+ * <p/>
+ * Camel, in addition to providing out-of-the-box a large number of useful processors, it also allows 
+ * you to implement and use your own. When the Exchange is passed to a {@link Processor}, it always 
+ * contains an in {@link Message} and no out {@link Message}. The {@link Processor} <b>may</b> produce 
+ * an out, depending on the nature of the {@link Processor}. The in {@link Message} can be accessed 
+ * using the {@link #getIn()} method. Since the out message is null when entering the {@link Processor}, 
+ * the {@link #getOut()} method is actually a convenient factory method that will lazily instantiate a 
+ * {@link org.apache.camel.impl.DefaultMessage} which you could populate. As an alternative you could 
+ * also instantiate your specialized  {@link Message} and set it on the exchange using the 
+ * {@link #setOut(org.apache.camel.Message)} method. Please note that a {@link Message} contains not only 
+ * the body but also headers and attachments. If you are creating a new {@link Message} the headers and 
+ * attachments of the in {@link Message} are not automatically copied to the out by Camel and you'll have 
+ * to set the headers and attachments you need yourself. If your {@link Processor} is not producing a 
+ * different {@link Message} but only needs to slightly  modify the in, you can simply update the in 
+ * {@link Message} returned by {@link #getIn()}. 
+ * <p/>
+ * See this <a href="http://camel.apache.org/using-getin-or-getout-methods-on-exchange.html">FAQ entry</a> 
+ * for more details.
+ * 
  */
 public interface Exchange {