[camel] 01/04: CAMEL-14409: camel-core - ExtendedExchange for advanced API

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git

commit 811c720ce80f899de4a0226894e85afef9df28b8
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Thu Jan 16 14:36:13 2020 +0100

    CAMEL-14409: camel-core - ExtendedExchange for advanced API
---
 .../src/main/java/org/apache/camel/Exchange.java      |  7 +++++++
 .../modules/ROOT/pages/camel-3x-upgrade-guide.adoc    | 19 +++++++++++++++++--
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/core/camel-api/src/main/java/org/apache/camel/Exchange.java b/core/camel-api/src/main/java/org/apache/camel/Exchange.java
index 9b513d7..6a8fa26 100644
--- a/core/camel-api/src/main/java/org/apache/camel/Exchange.java
+++ b/core/camel-api/src/main/java/org/apache/camel/Exchange.java
@@ -559,6 +559,7 @@ public interface Exchange {
      *
      * @param fromEndpoint the endpoint which is originating this message exchange
      */
+    // TODO: Move to ExtendedExchange
     void setFromEndpoint(Endpoint fromEndpoint);
     
     /**
@@ -573,6 +574,7 @@ public interface Exchange {
      *
      * @param fromRouteId the from route id
      */
+    // TODO: Move to ExtendedExchange
     void setFromRouteId(String fromRouteId);
 
     /**
@@ -585,6 +587,7 @@ public interface Exchange {
      * Sets the unit of work that this exchange belongs to; which may map to
      * zero, one or more physical transactions
      */
+    // TODO: Move to ExtendedExchange
     void setUnitOfWork(UnitOfWork unitOfWork);
 
     /**
@@ -603,6 +606,7 @@ public interface Exchange {
      *
      * @param onCompletion  the callback to invoke on completion of this exchange
      */
+    // TODO: Move to ExtendedExchange
     void addOnCompletion(Synchronization onCompletion);
 
     /**
@@ -612,6 +616,7 @@ public interface Exchange {
      * @param onCompletion  the callback instance that is being checked for
      * @return <tt>true</tt>, if callback instance is already contained on this exchange, else <tt>false</tt>
      */
+    // TODO: Move to ExtendedExchange
     boolean containsOnCompletion(Synchronization onCompletion);
 
     /**
@@ -619,6 +624,7 @@ public interface Exchange {
      *
      * @param target the target exchange
      */
+    // TODO: Move to ExtendedExchange
     void handoverCompletions(Exchange target);
 
     /**
@@ -626,6 +632,7 @@ public interface Exchange {
      *
      * @return the on completions
      */
+    // TODO: Move to ExtendedExchange
     List<Synchronization> handoverCompletions();
 
     /**
diff --git a/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide.adoc b/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide.adoc
index 8384c4f..4ebef1c 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide.adoc
@@ -108,11 +108,26 @@ See the xref:message-history.adoc[Message History] documentation for how to enab
 
 The `Exchange` API has been modified slightly as part of an optimization effort.
 The returned value of `getCreated` is changed from `java.util.Date` to `long` which is the time millis.
-
 The `Exchange.CREATED_TIMESTAMP` is no longer stored as exchange property, but you should use the `getCreated` method on `Exchange`.
-
 The returned value of `isExternalRedelivered` is changed from `Boolean` to `boolean`.
 
+Some of the advanced and API for component developers on `Exchange` has been moved to an extended interface `ExtendedExchange`.
+The following methods has been moved:
+
+- setFromEndpoint
+- setFromRouteId
+- setUnitOfWork
+- addOnCompletion
+- containsOnCompletion
+- handoverCompletions
+
+You can use these methods by adapting to the extended exchange as shown below:
+
+[source,java]
+----
+exchange.adapt(ExtendedExchange.class).addOnCompletion(...);
+----
+
 ==== Cookies
 
 Cookies from `camel-http-common` has been moved into a new `camel-http-base` JAR.