[camel] branch master updated: Add proper endChoice() and end() blocks (#5311)

[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


The following commit(s) were added to refs/heads/master by this push:
     new e5491c5  Add proper endChoice() and end() blocks (#5311)
e5491c5 is described below

commit e5491c577140ffdaf48e3cabeacc9b52f0ddf2b3
Author: swapy <sp...@gmail.com>
AuthorDate: Sat Apr 10 17:10:19 2021 +0530

    Add proper endChoice() and end() blocks (#5311)
    
    * Add proper endChoice() and end() blocks
    
    Need to add proper endChoice() and end() blocks to show correct way to work with choices(as a best practice).
    
    * Updated documentation to explain endChoice and end.
    
    Have added additional example with information to explain usage of endChoice and end.
    
    * Updated choice EIP documentation.
    
    Had to do minor restructuring of data to keep old document as is.
    Reverted to original example.
---
 .../main/docs/modules/eips/pages/choice-eip.adoc   | 46 +++++++++++++++++++---
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc b/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc
index 9000a01..a431005 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/choice-eip.adoc
@@ -46,14 +46,9 @@ RouteBuilder builder = new RouteBuilder() {
                     .to("direct:d");
     }
 };
+
 ----
 
-[TIP]
-====
-See xref:latest@manual:faq:why-can-i-not-use-when-or-otherwise-in-a-java-camel-route.adoc[Why
-can I not use when or otherwise in a Java Camel route] if you have
-problems with the Java DSL, accepting using `when` or `otherwise`.
-====
 
 And the same example using XML:
 
@@ -78,3 +73,42 @@ And the same example using XML:
     </route>
 </camelContext>
 ----
+
+== Usage of endChoice and end
+Usage of `endChoice` is not mandatory. However, It should be used whenever you want to return back control to `choice()` dsl so that you can add subsequent `when` and `otherwise` to the choice dsl.
+If you want to end entire `choice()` block use `end()`.
+
+=== Example
+
+[source,java]
+----
+
+    @Override
+    protected RouteBuilder createRouteBuilder() throws Exception {
+        return new RouteBuilder() {
+            @Override
+            public void configure() throws Exception {
+                from("direct:start")
+                    .choice()
+                        .when(body().contains("Camel"))
+                        .multicast()
+                            .to("mock:foo")
+                            .to("mock:bar")
+                        .endChoice() //we need to use endChoice to tell Java DSL to return scope back to the choice DSL.
+                        .otherwise() 
+                            .to("mock:result");
+            }
+        };
+    }
+    
+----
+
+Another example is explained in the TIP below.
+
+[TIP]
+====
+See xref:latest@manual:faq:why-can-i-not-use-when-or-otherwise-in-a-java-camel-route.adoc[Why
+can I not use when or otherwise in a Java Camel route] if you have
+problems with the Java DSL, accepting using `when` or `otherwise`.
+====
+