You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/05/19 08:46:46 UTC
[4/4] camel git commit: Added camel-routebox docs to Gitbook
Added camel-routebox docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/7cfced8b
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/7cfced8b
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/7cfced8b
Branch: refs/heads/master
Commit: 7cfced8b5beb380c4da05d491a287357f0e17e16
Parents: c29aafb
Author: Andrea Cosentino <an...@gmail.com>
Authored: Thu May 19 10:45:37 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Thu May 19 10:45:37 2016 +0200
----------------------------------------------------------------------
.../camel-routebox/src/main/docs/routebox.adoc | 281 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 282 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/7cfced8b/components/camel-routebox/src/main/docs/routebox.adoc
----------------------------------------------------------------------
diff --git a/components/camel-routebox/src/main/docs/routebox.adoc b/components/camel-routebox/src/main/docs/routebox.adoc
new file mode 100644
index 0000000..503d53b
--- /dev/null
+++ b/components/camel-routebox/src/main/docs/routebox.adoc
@@ -0,0 +1,281 @@
+[[Routebox-RouteboxComponent]]
+Routebox Component
+~~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.6*
+
+*Routebox subject for change*
+
+The Routebox component will be revisited in upcoming releases to see if
+it can be further simplified, be more intuitive and user friendly. The
+related link:context.html[Context] component may be regardes as the
+simpler component. This component may be @deprecated in favor of
+link:context.html[Context].
+
+The *routebox* component enables the creation of specialized endpoints
+that offer encapsulation and a strategy based indirection service to a
+collection of camel routes hosted in an automatically created or user
+injected camel context.
+
+Routebox endpoints are camel endpoints that may be invoked directly on
+camel routes. The routebox endpoint performs the following key functions
+
+* encapsulation - acts as a blackbox, hosting a collection of camel
+routes stored in an inner camel context. The inner context is fully
+under the control of the routebox component and is *JVM bound*.
+* strategy based indirection - direct payloads sent to the routebox
+endpoint along a camel route to specific inner routes based on a user
+defined internal routing strategy or a dispatch map.
+* exchange propagation - forward exchanges modified by the routebox
+endpoint to the next segment of the camel route.
+
+The routebox component supports both consumer and producer endpoints.
+
+Producer endpoints are of two flavors
+
+* Producers that send or dispatch incoming requests to a external
+routebox consumer endpoint
+* Producers that directly invoke routes in an internal embedded camel
+context thereby not sending requests to an external consumer.
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component:
+
+[source,xml]
+------------------------------------------------------------
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-routebox</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+[[Routebox-TheneedforaCamelRouteboxendpoint]]
+The need for a Camel Routebox endpoint
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The routebox component is designed to ease integration in complex
+environments needing
+
+* a large collection of routes and
+* involving a wide set of endpoint technologies needing integration in
+different ways
+
+In such environments, it is often necessary to craft an integration
+solution by creating a sense of layering among camel routes effectively
+organizing them into
+
+* Coarse grained or higher level routes - aggregated collection of inner
+or lower level routes exposed as Routebox endpoints that represent an
+integration focus area. For example
+
+[width="100%",cols="50%,50%",options="header",]
+|=======================================================================
+|Focus Area |Coarse grained Route Examples
+
+|Department Focus |HR routes, Sales routes etc
+
+|Supply chain & B2B Focus |Shipping routes, Fulfillment routes, 3rd party services etc
+
+|Technology Focus |Database routes, JMS routes, Scheduled batch routes etc
+|=======================================================================
+
+* Fine grained routes - routes that execute a singular and specific
+business and/or integration pattern.
+
+Requests sent to Routebox endpoints on coarse grained routes can then
+delegate requests to inner fine grained routes to achieve a specific
+integration objective, collect the final inner result, and continue to
+progress to the next step along the coarse-grained route.
+
+[[Routebox-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,java]
+-------------------------------
+routebox:routeboxname[?options]
+-------------------------------
+
+You can append query options to the URI in the following format,
+`?option=value&option=value&...`
+
+[[Routebox-Options]]
+Options
+^^^^^^^
+
+
+// component options: START
+The RouteBox component has no options.
+// component options: END
+
+
+
+// endpoint options: START
+The RouteBox component supports 18 endpoint options which are listed below:
+
+{% raw %}
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| routeboxName | common | | String | *Required* Logical name for the routebox (eg like a queue name)
+| dispatchMap | common | | Map | A string representing a key in the Camel Registry matching an object value of the type HashMap. The HashMap key should contain strings that can be matched against the value set for the exchange header ROUTE_DISPATCH_KEY. The HashMap value should contain inner route consumer URI's to which requests should be directed.
+| dispatchStrategy | common | | RouteboxDispatchStrategy | To use a custom RouteboxDispatchStrategy which allows to use custom dispatching instead of the default.
+| forkContext | common | true | boolean | Whether to fork and create a new inner CamelContext instead of reusing the same CamelContext.
+| innerProtocol | common | direct | String | The Protocol used internally by the Routebox component. Can be Direct or SEDA. The Routebox component currently offers protocols that are JVM bound.
+| queueSize | common | | int | Create a fixed size queue to receive requests.
+| bridgeErrorHandler | consumer | false | boolean | Allows for bridging the consumer to the Camel routing Error Handler which mean any exceptions occurred while the consumer is trying to pickup incoming messages or the likes will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions that will be logged at WARN/ERROR level and ignored.
+| pollInterval | consumer | 1000 | long | The timeout used when polling from seda. When a timeout occurs the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.
+| threads | consumer | 20 | int | Number of threads to be used by the routebox to receive requests.
+| exceptionHandler | consumer (advanced) | | ExceptionHandler | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions that will be logged at WARN/ERROR level and ignored.
+| connectionTimeout | producer | 20000 | long | Timeout in millis used by the producer when sending a message.
+| sendToConsumer | producer | true | boolean | Dictates whether a Producer endpoint sends a request to an external routebox consumer. If the setting is false the Producer creates an embedded inner context and processes requests internally.
+| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange
+| innerContext | advanced | | CamelContext | A string representing a key in the Camel Registry matching an object value of the type org.apache.camel.CamelContext. If a CamelContext is not provided by the user a CamelContext is automatically created for deployment of inner routes.
+| innerProducerTemplate | advanced | | ProducerTemplate | The ProducerTemplate to use by the internal embeded CamelContext
+| innerRegistry | advanced | | Registry | To use a custom registry for the internal embedded CamelContext.
+| routeBuilders | advanced | | String | A string representing a key in the Camel Registry matching an object value of the type List. If the user does not supply an innerContext pre-primed with inner routes the routeBuilders option must be provided as a non-empty list of RouteBuilders containing inner routes
+| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
+|=======================================================================
+{% endraw %}
+// endpoint options: END
+
+
+[[Routebox-SendingReceivingMessagestofromtheroutebox]]
+Sending/Receiving Messages to/from the routebox
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before sending requests it is necessary to properly configure the
+routebox by loading the required URI parameters into the Registry as
+shown below. In the case of Spring, if the necessary beans are declared
+correctly, the registry is automatically populated by Camel.
+
+[[Routebox-Step1:LoadinginnerroutedetailsintotheRegistry]]
+Step 1: Loading inner route details into the Registry
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+[source,java]
+------------------------------------------------------------------------------------------------------------
+@Override
+protected JndiRegistry createRegistry() throws Exception {
+ JndiRegistry registry = new JndiRegistry(createJndiContext());
+
+ // Wire the routeDefinitions & dispatchStrategy to the outer camelContext where the routebox is declared
+ List<RouteBuilder> routes = new ArrayList<RouteBuilder>();
+ routes.add(new SimpleRouteBuilder());
+ registry.bind("registry", createInnerRegistry());
+ registry.bind("routes", routes);
+
+ // Wire a dispatch map to registry
+ HashMap<String, String> map = new HashMap<String, String>();
+ map.put("addToCatalog", "seda:addToCatalog");
+ map.put("findBook", "seda:findBook");
+ registry.bind("map", map);
+
+ // Alternatively wiring a dispatch strategy to the registry
+ registry.bind("strategy", new SimpleRouteDispatchStrategy());
+
+ return registry;
+}
+
+private JndiRegistry createInnerRegistry() throws Exception {
+ JndiRegistry innerRegistry = new JndiRegistry(createJndiContext());
+ BookCatalog catalogBean = new BookCatalog();
+ innerRegistry.bind("library", catalogBean);
+
+ return innerRegistry;
+}
+...
+CamelContext context = new DefaultCamelContext(createRegistry());
+------------------------------------------------------------------------------------------------------------
+
+[[Routebox-Step2:OptionalyusingaDispatchStrategyinsteadofaDispatchMap]]
+Step 2: Optionaly using a Dispatch Strategy instead of a Dispatch Map
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Using a dispatch Strategy involves implementing the interface
+_org.apache.camel.component.routebox.strategy.RouteboxDispatchStrategy_
+as shown in the example below.
+
+[source,java]
+-------------------------------------------------------------------------------------------------------------------------------------------------
+public class SimpleRouteDispatchStrategy implements RouteboxDispatchStrategy {
+
+ /* (non-Javadoc)
+ * @see org.apache.camel.component.routebox.strategy.RouteboxDispatchStrategy#selectDestinationUri(java.util.List, org.apache.camel.Exchange)
+ */
+ public URI selectDestinationUri(List<URI> activeDestinations,
+ Exchange exchange) {
+ URI dispatchDestination = null;
+
+ String operation = exchange.getIn().getHeader("ROUTE_DISPATCH_KEY", String.class);
+ for (URI destination : activeDestinations) {
+ if (destination.toASCIIString().equalsIgnoreCase("seda:" + operation)) {
+ dispatchDestination = destination;
+ break;
+ }
+ }
+
+ return dispatchDestination;
+ }
+}
+-------------------------------------------------------------------------------------------------------------------------------------------------
+
+[[Routebox-Step2:Launchingarouteboxconsumer]]
+Step 2: Launching a routebox consumer
++++++++++++++++++++++++++++++++++++++
+
+When creating a route consumer, note that the # entries in the
+routeboxUri are matched to the created inner registry, routebuilder list
+and dispatchStrategy/dispatchMap in the CamelContext Registry. Note that
+all routebuilders and associated routes are launched in the routebox
+created inner context
+
+[source,java]
+----------------------------------------------------------------------------------------------------------------------
+private String routeboxUri = "routebox:multipleRoutes?innerRegistry=#registry&routeBuilders=#routes&dispatchMap=#map";
+
+public void testRouteboxRequests() throws Exception {
+ CamelContext context = createCamelContext();
+ template = new DefaultProducerTemplate(context);
+ template.start();
+
+ context.addRoutes(new RouteBuilder() {
+ public void configure() {
+ from(routeboxUri)
+ .to("log:Routes operation performed?showAll=true");
+ }
+ });
+ context.start();
+
+ // Now use the ProducerTemplate to send the request to the routebox
+ template.requestBodyAndHeader(routeboxUri, book, "ROUTE_DISPATCH_KEY", "addToCatalog");
+}
+----------------------------------------------------------------------------------------------------------------------
+
+[[Routebox-Step3:Usingarouteboxproducer]]
+Step 3: Using a routebox producer
++++++++++++++++++++++++++++++++++
+
+When sending requests to the routebox, it is not necessary for producers
+do not need to know the inner route endpoint URI and they can simply
+invoke the Routebox URI endpoint with a dispatch strategy or dispatchMap
+as shown below
+
+It is necessary to set a special exchange Header called
+*ROUTE_DISPATCH_KEY* (optional for Dispatch Strategy) with a key that
+matches a key in the dispatch map so that the request can be sent to the
+correct inner route
+
+[source,java]
+-----------------------------------------------------------------------------------------------------------
+from("direct:sendToStrategyBasedRoutebox")
+ .to("routebox:multipleRoutes?innerRegistry=#registry&routeBuilders=#routes&dispatchStrategy=#strategy")
+ .to("log:Routes operation performed?showAll=true");
+
+from ("direct:sendToMapBasedRoutebox")
+ .setHeader("ROUTE_DISPATCH_KEY", constant("addToCatalog"))
+ .to("routebox:multipleRoutes?innerRegistry=#registry&routeBuilders=#routes&dispatchMap=#map")
+ .to("log:Routes operation performed?showAll=true");
+-----------------------------------------------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/7cfced8b/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 56c4b6b..61c7c58 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -224,6 +224,7 @@
* [RabbitMQ](rabbitmq.adoc)
* [Restlet](restlet.adoc)
* [RMI](rmi.adoc)
+ * [Routebox](routebox.adoc)
* [Scp](scp.adoc)
* [SJMS](sjms.adoc)
* [SJMS Batch](sjms-batch.adoc)