PageRenderTime 30ms CodeModel.GetById 13ms RepoModel.GetById 1ms app.codeStats 0ms

/components/camel-guice/src/main/docs/guice.adoc

https://gitlab.com/matticala/apache-camel
AsciiDoc | 161 lines | 128 code | 33 blank | 0 comment | 0 complexity | 8adbd92da65ac67ec7fdd3cd173a9944 MD5 | raw file
  1. [[Guice-CamelGuice]]
  2. Camel Guice
  3. ~~~~~~~~~~~
  4. We have support for http://code.google.com/p/google-guice/[Google Guice]
  5. as a dependency injection framework.
  6. Maven users will need to add the following dependency to their `pom.xml`
  7. for this component:
  8. [source,xml]
  9. ------------------------------------------------------------
  10. <dependency>
  11. <groupId>org.apache.camel</groupId>
  12. <artifactId>camel-guice</artifactId>
  13. <version>x.x.x</version>
  14. <!-- use the same version as your Camel core version -->
  15. </dependency>
  16. ------------------------------------------------------------
  17. [[Guice-DependencyInjectingCamelwithGuice]]
  18. Dependency Injecting Camel with Guice
  19. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  20. The http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/GuiceCamelContext.html[GuiceCamelContext]
  21. is designed to work nicely inside Guice. You then need to bind it using
  22. some Guice Module.
  23. The camel-guice library comes with a number of reusable Guice Modules
  24. you can use if you wish - or you can bind the GuiceCamelContext yourself
  25. in your own module.
  26. * http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModule.html[CamelModule]
  27. is the base module which binds the GuiceCamelContext but leaves it up
  28. you to bind the RouteBuilder instances
  29. * http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModuleWithRouteTypes.html[CamelModuleWithRouteTypes]
  30. extends CamelModule so that in the constructor of the module you specify
  31. the RouteBuilder classes or instances to use
  32. * http://camel.apache.org/maven/current/camel-guice/apidocs/org/apache/camel/guice/CamelModuleWithMatchingRoutes.html[CamelModuleWithMatchingRoutes]
  33. extends CamelModule so that all bound RouteBuilder instances will be
  34. injected into the CamelContext or you can supply an optional Matcher to
  35. find RouteBuilder instances matching some kind of predicate.
  36. So you can specify the exact RouteBuilder
  37. instances you want
  38. [source,java]
  39. -------------------------------------------------------------------------------------------------------------------------
  40. Injector injector = Guice.createInjector(new CamelModuleWithRouteTypes(MyRouteBuilder.class, AnotherRouteBuilder.class));
  41. // if required you can lookup the CamelContext
  42. CamelContext camelContext = injector.getInstance(CamelContext.class);
  43. -------------------------------------------------------------------------------------------------------------------------
  44. Or inject them all
  45. [source,java]
  46. --------------------------------------------------------------------------
  47. Injector injector = Guice.createInjector(new CamelModuleWithRouteTypes());
  48. // if required you can lookup the CamelContext
  49. CamelContext camelContext = injector.getInstance(CamelContext.class);
  50. --------------------------------------------------------------------------
  51. You can then use Guice in the usual way to inject the route instances or
  52. any other dependent objects.
  53. [[Guice-BootstrappingwithJNDI]]
  54. Bootstrapping with JNDI
  55. ^^^^^^^^^^^^^^^^^^^^^^^
  56. A common pattern used in J2EE is to bootstrap your application or root
  57. objects by looking them up in JNDI. This has long been the approach when
  58. working with JMS for example - looking up the JMS ConnectionFactory in
  59. JNDI for example.
  60. You can follow a similar pattern with Guice using the
  61. http://code.google.com/p/guiceyfruit/wiki/GuiceyJndi[GuiceyFruit JNDI
  62. Provider] which lets you bootstrap Guice from a *jndi.properties* file
  63. which can include the Guice Modules to create along with environment
  64. specific properties you can inject into your modules and objects.
  65. If the *jndi.properties* is conflict with other component, you can
  66. specify the jndi properties file name in the Guice Main with option -j
  67. or -jndiProperties with the properties file location to let Guice Main
  68. to load right jndi properties file.
  69. [[Guice-ConfiguringComponent,EndpointorRouteBuilderinstances]]
  70. Configuring Component, Endpoint or RouteBuilder instances
  71. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  72. You can use Guice to dependency inject whatever objects
  73. you need to create, be it an Endpoint,
  74. Component, RouteBuilder or
  75. arbitrary bean used within a route.
  76. The easiest way to do this is to create your own Guice Module class
  77. which extends one of the above module classes and add a provider method
  78. for each object you wish to create. A provider method is annotated with
  79. *@Provides* as follows
  80. [source,java]
  81. -----------------------------------------------------------------------------------
  82. public class MyModule extends CamelModuleWithMatchingRoutes {
  83. @Provides
  84. @JndiBind("jms")
  85. JmsComponent jms(@Named("activemq.brokerURL") String brokerUrl) {
  86. return JmsComponent.jmsComponent(new ActiveMQConnectionFactory(brokerUrl));
  87. }
  88. }
  89. -----------------------------------------------------------------------------------
  90. You can optionally annotate the method with *@JndiBind* to bind the
  91. object to JNDI at some name if the object is a component, endpoint or
  92. bean you wish to refer to by name in your routes.
  93. You can inject any environment specific properties (such as URLs,
  94. machine names, usernames/passwords and so forth) from the
  95. jndi.properties file easily using the *@Named* annotation as shown
  96. above. This allows most of your configuration to be in Java code which
  97. is typesafe and easily refactorable - then leaving some properties to be
  98. environment specific (the jndi.properties file) which you can then
  99. change based on development, testing, production etc.
  100. [[Guice-CreatingmultipleRouteBuilderinstancespertype]]
  101. Creating multiple RouteBuilder instances per type
  102. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  103. It is sometimes useful to create multiple instances of a particular
  104. RouteBuilder with different configurations.
  105. To do this just create multiple provider methods for each configuration;
  106. or create a single provider method that returns a collection of
  107. RouteBuilder instances.
  108. For example
  109. [source,java]
  110. ----------------------------------------------------------------------------------------------------------
  111. import org.apache.camel.guice.CamelModuleWithMatchingRoutes;
  112. import com.google.common.collect.Lists;
  113. public class MyModule extends CamelModuleWithMatchingRoutes {
  114. @Provides
  115. @JndiBind("foo")
  116. Collection<RouteBuilder> foo(@Named("fooUrl") String fooUrl) {
  117. return Lists.newArrayList(new MyRouteBuilder(fooUrl), new MyRouteBuilder("activemq:CheeseQueue"));
  118. }
  119. }
  120. ----------------------------------------------------------------------------------------------------------
  121. [[Guice-SeeAlso]]
  122. See Also
  123. ^^^^^^^^
  124. * there are a number of Examples you can look at to
  125. see Guice and Camel being used such as link:guice-jms-example.html[Guice
  126. JMS Example]
  127. * Guice Maven Plugin for running your
  128. Guice based routes via Maven