Repository: camel Updated Branches: refs/heads/master 1d41d1a1f -> ea96c3e6b
Added camel-context 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/ea96c3e6 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/ea96c3e6 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/ea96c3e6 Branch: refs/heads/master Commit: ea96c3e6bc4bd3b6db83bfb370ebe843ba3a3e0b Parents: 1d41d1a Author: Andrea Cosentino <[email protected]> Authored: Thu Jun 30 13:35:11 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Thu Jun 30 13:35:11 2016 +0200 ---------------------------------------------------------------------- .../camel-context/src/main/docs/context.adoc | 174 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 175 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/ea96c3e6/components/camel-context/src/main/docs/context.adoc ---------------------------------------------------------------------- diff --git a/components/camel-context/src/main/docs/context.adoc b/components/camel-context/src/main/docs/context.adoc new file mode 100644 index 0000000..92f1a06 --- /dev/null +++ b/components/camel-context/src/main/docs/context.adoc @@ -0,0 +1,174 @@ +[[Context-ContextComponent]] +Context Component +~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.7* + +The *context* component allows you to create new Camel Components from a +CamelContext with a number of routes which is then treated as a black +box, allowing you to refer to the local endpoints within the component +from other CamelContexts. + +It is similar to the link:routebox.html[Routebox] component in idea, +though the Context component tries to be really simple for end users; +just a simple convention over configuration approach to refer to local +endpoints inside the CamelContext Component. + +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-context</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[Context-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +-------------------------------------------------- +context:camelContextId:localEndpointName[?options] +-------------------------------------------------- + +Or you can omit the "context:" prefix. + +[source,java] +------------------------------------------ +camelContextId:localEndpointName[?options] +------------------------------------------ + + + +// component options: START +The Camel Context component has no options. +// component options: END + + + +// endpoint options: START +The Camel Context component supports 6 endpoint options which are listed below: + +{% raw %} +[width="100%",cols="2s,1,1m,1m,5",options="header"] +|======================================================================= +| Name | Group | Default | Java Type | Description +| contextId | common | | String | *Required* Is the ID you used to register the CamelContext into the Registry. +| localEndpointUrl | common | | String | *Required* Can be a valid Camel URI evaluated within the black box CamelContext. Or it can be a logical name which is mapped to any local endpoints. For example if you locally have endpoints like direct:invoices and seda:purchaseOrders inside a CamelContext of id supplyChain then you can just use the URIs supplyChain:invoices or supplyChain:purchaseOrders to omit the physical endpoint kind and use pure logical URIs. +| 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. +| 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. +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange +| 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 + + +You can append query options to the URI in the following format, +`?option=value&option=value&...` + +[[Context-Example]] +Example +^^^^^^^ + +In this example we'll create a black box context, then we'll use it from +another CamelContext. + +[[Context-Definingthecontextcomponent]] +Defining the context component +++++++++++++++++++++++++++++++ + +First you need to create a CamelContext, add some routes in it, start it +and then register the CamelContext into the link:registry.html[Registry] +(JNDI, Spring, Guice or OSGi etc). + +This can be done in the usual Camel way from this +http://svn.apache.org/viewvc/camel/trunk/components/camel-context/src/test/java/org/apache/camel/component/context/JavaDslBlackBoxTest.java?revision=1069442&view=markup[test +case] (see the createRegistry() method); this example shows Java and +JNDI being used... + +[source,java] +------------------------------------------------------------------------------------ +// lets create our black box as a camel context and a set of routes +DefaultCamelContext blackBox = new DefaultCamelContext(registry); +blackBox.setName("blackBox"); +blackBox.addRoutes(new RouteBuilder() { + @Override + public void configure() throws Exception { + // receive purchase orders, lets process it in some way then send an invoice + // to our invoice endpoint + from("direct:purchaseOrder"). + setHeader("received").constant("true"). + to("direct:invoice"); + } +}); +blackBox.start(); + +registry.bind("accounts", blackBox); +------------------------------------------------------------------------------------ + +Notice in the above route we are using pure local endpoints (*direct* +and *seda*). Also note we expose this CamelContext using the *accounts* +ID. We can do the same thing in Spring via + +[source,xml] +-------------------------------------------------------------------------- +<camelContext id="accounts" xmlns="http://camel.apache.org/schema/spring";> + <route> + <from uri="direct:purchaseOrder"/> + ... + <to uri="direct:invoice"/> + </route> +</camelContext> +-------------------------------------------------------------------------- + +[[Context-Usingthecontextcomponent]] +Using the context component ++++++++++++++++++++++++++++ + +Then in another CamelContext we can then refer to this "accounts black +box" by just sending to *accounts:purchaseOrder* and consuming from +*accounts:invoice*. + +If you prefer to be more verbose and explicit you could use +*context:accounts:purchaseOrder* or even +*context:accounts:direct://purchaseOrder* if you prefer. But using +logical endpoint URIs is preferred as it hides the implementation detail +and provides a simple logical naming scheme. + +For example if we wish to then expose this accounts black box on some +middleware (outside of the black box) we can do things like... + +[source,xml] +-------------------------------------------------------------------------------- +<camelContext xmlns="http://camel.apache.org/schema/spring";> + <route> + <!-- consume from an ActiveMQ into the black box --> + <from uri="activemq:Accounts.PurchaseOrders"/> + <to uri="accounts:purchaseOrders"/> + </route> + <route> + <!-- lets send invoices from the black box to a different ActiveMQ Queue --> + <from uri="accounts:invoice"/> + <to uri="activemq:UK.Accounts.Invoices"/> + </route> +</camelContext> +-------------------------------------------------------------------------------- + +[[Context-Namingendpoints]] +Naming endpoints +++++++++++++++++ + +A context component instance can have many public input and output +endpoints that can be accessed from outside it's CamelContext. When +there are many it is recommended that you use logical names for them to +hide the middleware as shown above. + +However when there is only one input, output or error/dead letter +endpoint in a component we recommend using the common posix shell names +*in*, *out* and *err* http://git-wip-us.apache.org/repos/asf/camel/blob/ea96c3e6/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 931a18d..ec75f76 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -139,6 +139,7 @@ * [Cmis](cmis.adoc) * [CoAP](coap.adoc) * [Cometd](cometd.adoc) + * [Context](context.adoc) * [Couchdb](couchdb.adoc) * [Crypto](crypto.adoc) * [Crypto Digital Signatures](crypto-digital-signatures.adoc)
