Added camel-guice 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/ae4ebd33 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/ae4ebd33 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/ae4ebd33 Branch: refs/heads/master Commit: ae4ebd3333ac42a4bd66e4306f7acaab8170dae1 Parents: 2c07a23 Author: Andrea Cosentino <anco...@gmail.com> Authored: Sat Apr 2 15:11:31 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Sat Apr 2 15:11:31 2016 +0200 ---------------------------------------------------------------------- .../src/main/docs/guava-eventbus.adoc | 4 + components/camel-guice/src/main/docs/guice.adoc | 161 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 3 files changed, 166 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/ae4ebd33/components/camel-guava-eventbus/src/main/docs/guava-eventbus.adoc ---------------------------------------------------------------------- diff --git a/components/camel-guava-eventbus/src/main/docs/guava-eventbus.adoc b/components/camel-guava-eventbus/src/main/docs/guava-eventbus.adoc index 11cc8ea..edda987 100644 --- a/components/camel-guava-eventbus/src/main/docs/guava-eventbus.adoc +++ b/components/camel-guava-eventbus/src/main/docs/guava-eventbus.adoc @@ -47,9 +47,12 @@ Options ^^^^^^^ + // component options: START The Guava EventBus component supports 2 options which are listed below. + + [width="100%",cols="2s,1m,8",options="header"] |======================================================================= | Name | Java Type | Description @@ -58,6 +61,7 @@ The Guava EventBus component supports 2 options which are listed below. |======================================================================= // component options: END + // endpoint options: START The Guava EventBus component supports 7 endpoint options which are listed below: http://git-wip-us.apache.org/repos/asf/camel/blob/ae4ebd33/components/camel-guice/src/main/docs/guice.adoc ---------------------------------------------------------------------- diff --git a/components/camel-guice/src/main/docs/guice.adoc b/components/camel-guice/src/main/docs/guice.adoc new file mode 100644 index 0000000..a1d9eae --- /dev/null +++ b/components/camel-guice/src/main/docs/guice.adoc @@ -0,0 +1,161 @@ +[[Guice-CamelGuice]] +Camel Guice +~~~~~~~~~~~ + +We have support for http://code.google.com/p/google-guice/[Google Guice] +as a dependency injection framework. + +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-guice</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[Guice-DependencyInjectingCamelwithGuice]] +Dependency Injecting Camel with Guice +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/GuiceCamelContext.html[GuiceCamelContext] +is designed to work nicely inside Guice. You then need to bind it using +some Guice Module. + +The camel-guice library comes with a number of reusable Guice Modules +you can use if you wish - or you can bind the GuiceCamelContext yourself +in your own module. + +* http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModule.html[CamelModule] +is the base module which binds the GuiceCamelContext but leaves it up +you to bind the RouteBuilder instances +* http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModuleWithRouteTypes.html[CamelModuleWithRouteTypes] +extends CamelModule so that in the constructor of the module you specify +the RouteBuilder classes or instances to use +* http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModuleWithMatchingRoutes.html[CamelModuleWithMatchingRoutes] +extends CamelModule so that all bound RouteBuilder instances will be +injected into the CamelContext or you can supply an optional Matcher to +find RouteBuilder instances matching some kind of predicate. + +So you can specify the exact link:routebuilder.html[RouteBuilder] +instances you want + +[source,java] +------------------------------------------------------------------------------------------------------------------------- +Injector injector = Guice.createInjector(new CamelModuleWithRouteTypes(MyRouteBuilder.class, AnotherRouteBuilder.class)); +// if required you can lookup the CamelContext +CamelContext camelContext = injector.getInstance(CamelContext.class); +------------------------------------------------------------------------------------------------------------------------- + +Or inject them all + +[source,java] +-------------------------------------------------------------------------- +Injector injector = Guice.createInjector(new CamelModuleWithRouteTypes()); +// if required you can lookup the CamelContext +CamelContext camelContext = injector.getInstance(CamelContext.class); +-------------------------------------------------------------------------- + +You can then use Guice in the usual way to inject the route instances or +any other dependent objects. + +[[Guice-BootstrappingwithJNDI]] +Bootstrapping with JNDI +^^^^^^^^^^^^^^^^^^^^^^^ + +A common pattern used in J2EE is to bootstrap your application or root +objects by looking them up in JNDI. This has long been the approach when +working with JMS for example - looking up the JMS ConnectionFactory in +JNDI for example. + +You can follow a similar pattern with Guice using the +http://code.google.com/p/guiceyfruit/wiki/GuiceyJndi[GuiceyFruit JNDI +Provider] which lets you bootstrap Guice from a *jndi.properties* file +which can include the Guice Modules to create along with environment +specific properties you can inject into your modules and objects. + +If the *jndi.properties* is conflict with other component, you can +specify the jndi properties file name in the Guice Main with option -j +or -jndiProperties with the properties file location to let Guice Main +to load right jndi properties file. + +[[Guice-ConfiguringComponent,EndpointorRouteBuilderinstances]] +Configuring Component, Endpoint or RouteBuilder instances +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use link:guice.html[Guice] to dependency inject whatever objects +you need to create, be it an link:endpoint.html[Endpoint], +link:component.html[Component], link:routebuilder.html[RouteBuilder] or +arbitrary link:bean-integration.html[bean used within a route]. + +The easiest way to do this is to create your own Guice Module class +which extends one of the above module classes and add a provider method +for each object you wish to create. A provider method is annotated with +*@Provides* as follows + +[source,java] +----------------------------------------------------------------------------------- +public class MyModule extends CamelModuleWithMatchingRoutes { + + @Provides + @JndiBind("jms") + JmsComponent jms(@Named("activemq.brokerURL") String brokerUrl) { + return JmsComponent.jmsComponent(new ActiveMQConnectionFactory(brokerUrl)); + } +} +----------------------------------------------------------------------------------- + +You can optionally annotate the method with *@JndiBind* to bind the +object to JNDI at some name if the object is a component, endpoint or +bean you wish to refer to by name in your routes. + +You can inject any environment specific properties (such as URLs, +machine names, usernames/passwords and so forth) from the +jndi.properties file easily using the *@Named* annotation as shown +above. This allows most of your configuration to be in Java code which +is typesafe and easily refactorable - then leaving some properties to be +environment specific (the jndi.properties file) which you can then +change based on development, testing, production etc. + +[[Guice-CreatingmultipleRouteBuilderinstancespertype]] +Creating multiple RouteBuilder instances per type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is sometimes useful to create multiple instances of a particular +link:routebuilder.html[RouteBuilder] with different configurations. + +To do this just create multiple provider methods for each configuration; +or create a single provider method that returns a collection of +RouteBuilder instances. + +For example + +[source,java] +---------------------------------------------------------------------------------------------------------- +import org.apache.camel.guice.CamelModuleWithMatchingRoutes; +import com.google.common.collect.Lists; + +public class MyModule extends CamelModuleWithMatchingRoutes { + + @Provides + @JndiBind("foo") + Collection<RouteBuilder> foo(@Named("fooUrl") String fooUrl) { + return Lists.newArrayList(new MyRouteBuilder(fooUrl), new MyRouteBuilder("activemq:CheeseQueue")); + } +} +---------------------------------------------------------------------------------------------------------- + +[[Guice-SeeAlso]] +See Also +^^^^^^^^ + +* there are a number of link:examples.html[Examples] you can look at to +see Guice and Camel being used such as link:guice-jms-example.html[Guice +JMS Example] +* link:guice-maven-plugin.html[Guice Maven Plugin] for running your +Guice based routes via Maven + http://git-wip-us.apache.org/repos/asf/camel/blob/ae4ebd33/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 14b03be..8c260ef 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -144,6 +144,7 @@ * [Groovy](groovy.adoc) * [Groovy DSL](groovy-dsl.adoc) * [Guava Eventbus](guava-eventbus.adoc) + * [Guice](guice.adoc) * [Ironmq](ironmq.adoc) * [JMS](jms.adoc) * [JMX](jmx.adoc)
