Author: buildbot
Date: Thu Nov 27 13:19:37 2014
New Revision: 930766
Log:
Production update by buildbot for camel
Modified:
websites/production/camel/content/cache/main.pageCache
websites/production/camel/content/camel-and-scr.html
Modified: websites/production/camel/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/camel/content/camel-and-scr.html
==============================================================================
--- websites/production/camel/content/camel-and-scr.html (original)
+++ websites/production/camel/content/camel-and-scr.html Thu Nov 27 13:19:37
2014
@@ -85,14 +85,14 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><h2
id="CamelandSCR-WorkingwithCamelandSCR">Working with Camel and SCR</h2><p><span
style="font-size: 14.0px;line-height: 1.4285715;">SCR stands for Service
Component Runtime and is an implementation of OSGi Declarative Services
specification. SCR enables any plain old Java object to expose and use OSGi
services with no boilerplate code.</span></p><p>OSGi framework knows your
object by looking at SCR descriptor files in its bundle which are typically
generated from Java annotations by a plugin such as <code><a shape="rect"
class="external-link"
href="https://felix.apache.org/documentation/subprojects/apache-felix-maven-scr-plugin.html";>org.apache.felix:maven-scr-plugin</a></code>.</p><p>Running
Camel in an SCR bundle is a great alternative for Spring DM and Blueprint
based solutions having significantly fewer lines of code between you and the
OSGi framework. Using SCR your bundle can remain completely in Java world;
there is no need to edit XML
or properties files. This offers you full control over everything and means
your IDE of choice knows exactly what is going on in your project.</p><h3
id="CamelandSCR-CamelSCRsupport">Camel SCR support</h3><p><strong>Available as
of Camel 2.15.0</strong></p><p><span style="line-height:
1.4285715;"><code>org.apache.camel/camel-scr</code> bundle provides a base
class, <code>AbstractCamelRunner</code>, which manages a Camel context for you
and a helper class, <code>ScrHelper</code>, for using your SCR properties in
unit tests. Camel-scr feature for Apache Karaf </span><span
style="line-height: 1.4285715;">defines all features and bundles required for
running Camel in SCR
bundles.</span></p><p><code>AbstractCamelRunner</code> class ties
CamelContext's lifecycle to Service Component's lifecycle and handles
configuration with help of Camel's PropertiesComponent. All you have to do to
make a Service Component out of your java class is to extend it from
<code>AbstractCamelRunner</c
ode> and add the following <code><a shape="rect" class="external-link"
href="https://felix.apache.org/documentation/subprojects/apache-felix-maven-scr-plugin/scr-annotations.html";>org.apache.felix.scr.annotations</a></code>
on class level:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Add
required annotations</b></div><div class="codeContent panelContent pdl">
+<div class="wiki-content maincontent"><h2
id="CamelandSCR-WorkingwithCamelandSCR">Working with Camel and SCR</h2><p><span
style="font-size: 14.0px;line-height: 1.4285715;">SCR stands for Service
Component Runtime and is an implementation of OSGi Declarative Services
specification. SCR enables any plain old Java object to expose and use OSGi
services with no boilerplate code.</span></p><p>OSGi framework knows your
object by looking at SCR descriptor files in its bundle which are typically
generated from Java annotations by a plugin such as <code><a shape="rect"
class="external-link"
href="https://felix.apache.org/documentation/subprojects/apache-felix-maven-scr-plugin.html";>org.apache.felix:maven-scr-plugin</a></code>.</p><p>Running
Camel in an SCR bundle is a great alternative for Spring DM and Blueprint
based solutions having significantly fewer lines of code between you and the
OSGi framework. Using SCR your bundle can remain completely in Java world;
there is no need to edit XML
or properties files. This offers you full control over everything and means
your IDE of choice knows exactly what is going on in your project.</p><h3
id="CamelandSCR-CamelSCRsupport">Camel SCR support</h3><p><strong>Available as
of Camel 2.15.0</strong></p><p><span style="line-height:
1.4285715;"><code>org.apache.camel/camel-scr</code> bundle provides a base
class, <code>AbstractCamelRunner</code>, which manages a Camel context for you
and a helper class, <code>ScrHelper</code>, for using your SCR properties in
unit tests. Camel-scr feature for Apache Karaf </span><span
style="line-height: 1.4285715;">defines all features and bundles required for
running Camel in SCR
bundles.</span></p><p><code>AbstractCamelRunner</code> class ties
CamelContext's lifecycle to Service Component's lifecycle and handles
configuration with help of Camel's PropertiesComponent. All you have to do to
make a Service Component out of your java class is to extend it from
<code>AbstractCamelRunner</c
ode> and add the following <code><a shape="rect" class="external-link"
href="https://felix.apache.org/documentation/subprojects/apache-felix-maven-scr-plugin/scr-annotations.html";>org.apache.felix.scr.annotations</a></code>
on class level:</p><p> </p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Add required annotations</b></div><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[@Component
@References({
@Reference(name = "camelComponent",referenceInterface =
ComponentResolver.class,
cardinality = ReferenceCardinality.MANDATORY_MULTIPLE, policy =
ReferencePolicy.DYNAMIC,
policyOption = ReferencePolicyOption.GREEDY, bind =
"gotCamelComponent", unbind = "lostCamelComponent")
})]]></script>
-</div></div><p>Then implement <code>getRouteBuilders()</code> method which
returns the Camel routes you want to run:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Load routes</b></div><div
class="codeContent panelContent pdl">
+</div></div><p> </p><p>Then implement <code>getRouteBuilders()</code>
method which returns the Camel routes you want to run:</p><p> </p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Load routes</b></div><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ @Override
protected List<RoutesBuilder> getRouteBuilders() {
List<RoutesBuilder> routesBuilders = new ArrayList<>();
@@ -100,14 +100,14 @@
routesBuilders.add(new AnotherRouteBuilderHere(registry));
return routesBuilders;
}]]></script>
-</div></div><p>And finally provide the default configuration with:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Define configuration with
annotations</b></div><div class="codeContent panelContent pdl">
+</div></div><p> </p><p>And finally provide the default configuration
with:</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Define configuration with annotations</b></div><div class="codeContent
panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[@Properties({
@Property(name = "camelContextId", value = "my-test"),
@Property(name = "active", value = "true"),
@Property(name = "...", value = "..."),
...
})]]></script>
-</div></div><p>That's all. And if you used <code>camel-archetype-scr</code> to
generate a project all this is already taken care of.</p><p>Below is an example
of a complete Service Component class, generated by
<code>camel-archetype-scr:</code></p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CamelScrExample.java</b></div><div
class="codeContent panelContent pdl">
+</div></div><p> </p><p>That's all. And if you used
<code>camel-archetype-scr</code> to generate a project all this is already
taken care of.</p><p>Below is an example of a complete Service Component class,
generated by <code>camel-archetype-scr:</code></p><p> </p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CamelScrExample.java</b></div><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[// This file was generated from
org.apache.camel.archetypes/camel-archetype-scr/2.15-SNAPSHOT
package example;
@@ -151,7 +151,7 @@ public class CamelScrExample extends Abs
return routesBuilders;
}
}]]></script>
-</div></div><p><code style="font-size: 14.0px;line-height:
1.4285715;">CamelContextId</code><span style="font-size: 14.0px;line-height:
1.4285715;"> and </span><code style="font-size: 14.0px;line-height:
1.4285715;">active</code><span style="font-size: 14.0px;line-height:
1.4285715;"> properties control the CamelContext's name (defaults to
"camel-runner-default") and whether it will be started or not (defaults to
"false"), respectively. In addition to these you can add and use as many
properties as you like. Camel's PropertiesComponent handles recursive
properties and prefixing with fallback without
problem.</span></p><p><code>AbstractCamelRunner</code> will make these
properties available to your RouteBuilders with help of Camel's
PropertiesComponent and it will also inject these values into your Service
Component's and RouteBuilder's fields when their names match. The fields can be
declared with any visibility level, and many types are supported (String, int,
boolea
n, URL, ...).</p><h4
id="CamelandSCR-AbstractCamelRunner'slifecycleinSCR">AbstractCamelRunner's
lifecycle in SCR</h4><ol><li>When component's configuration policy and
mandatory references are satisfied SCR calls <code>activate()</code>. This
creates and sets up a CamelContext through the following call chain:
<code>activate()</code> → <code>prepare()</code> → <code>createCamelContext()</code>
→ <code>setupPropertiesComponent()</code>
→ <code>configure()</code>
→ <code>setupCamelContext()</code>. Finally, the context is
scheduled to start after a delay defined in
<code>AbstractCamelRunner.START_DELAY</code> with
<code>runWithDelay()</code>.</li><li><span style="line-height: 1.4285715;">When
Camel components (<code>ComponentResolver</code> services, to be exact) are
registered in OSGi, SCR calls </span><code>gotCamelComponent</code><span
style="line-height: 1.4285715;"><code>()</code> which reschedules/delays the Ca
melContext start further by the same
</span><code>AbstractCamelRunner.START_DELAY</code><span style="line-height:
1.4285715;">. This in effect makes CamelContext wait until all Camel components
are loaded or there is a sufficient gap between them. The same logic will tell
a failed-to-start CamelContext to try again whenever we add more Camel
components.</span></li><li><span style="line-height: 1.4285715;">When Camel
components are unregistered SCR calls
</span><code>lostCamelComponent</code><span style="line-height:
1.4285715;"><code>()</code>. This call does nothing.</span></li><li><span
style="line-height: 1.4285715;">When one of the requirements that caused the
call to </span><code>activate</code><span style="line-height:
1.4285715;"><code>()</code> is lost SCR will call
</span><code>deactivate</code><span style="line-height:
1.4285715;"><code>()</code>. This will shutdown the
CamelContext.</span></li></ol><p>In (non-OSGi) unit tests you should use
<code>prepare()</code> →&
#160;<code>run()</code> → <code>stop()</code> instead of
<code>activate()</code> → <code>deactivate()</code> for more
fine-grained control. Also, this allows us to avoid possible SCR specific
operations in tests.</p><h3 id="CamelandSCR-Usingcamel-archetype-scr">Using
camel-archetype-scr</h3><p>The easiest way to create an Camel SCR bundle
project is to use <code>camel-archetype-scr</code> and Maven.</p><p>You
can generate a project with the following steps:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Generating a project</b></div><div
class="codeContent panelContent pdl">
+</div></div><p> </p><p><code style="font-size: 14.0px;line-height:
1.4285715;">CamelContextId</code><span style="font-size: 14.0px;line-height:
1.4285715;"> and </span><code style="font-size: 14.0px;line-height:
1.4285715;">active</code><span style="font-size: 14.0px;line-height:
1.4285715;"> properties control the CamelContext's name (defaults to
"camel-runner-default") and whether it will be started or not (defaults to
"false"), respectively. In addition to these you can add and use as many
properties as you like. Camel's PropertiesComponent handles recursive
properties and prefixing with fallback without
problem.</span></p><p><code>AbstractCamelRunner</code> will make these
properties available to your RouteBuilders with help of Camel's
PropertiesComponent and it will also inject these values into your Service
Component's and RouteBuilder's fields when their names match. The fields can be
declared with any visibility level, and many types are supported (String
, int, boolean, URL, ...).</p><h4
id="CamelandSCR-AbstractCamelRunner'slifecycleinSCR">AbstractCamelRunner's
lifecycle in SCR</h4><ol><li>When component's configuration policy and
mandatory references are satisfied SCR calls <code>activate()</code>. This
creates and sets up a CamelContext through the following call chain:
<code>activate()</code> → <code>prepare()</code> → <code>createCamelContext()</code>
→ <code>setupPropertiesComponent()</code>
→ <code>configure()</code>
→ <code>setupCamelContext()</code>. Finally, the context is
scheduled to start after a delay defined in
<code>AbstractCamelRunner.START_DELAY</code> with
<code>runWithDelay()</code>.</li><li><span style="line-height: 1.4285715;">When
Camel components (<code>ComponentResolver</code> services, to be exact) are
registered in OSGi, SCR calls </span><code>gotCamelComponent</code><span
style="line-height: 1.4285715;"><code>()</code> which reschedules/
delays the CamelContext start further by the same
</span><code>AbstractCamelRunner.START_DELAY</code><span style="line-height:
1.4285715;">. This in effect makes CamelContext wait until all Camel components
are loaded or there is a sufficient gap between them. The same logic will tell
a failed-to-start CamelContext to try again whenever we add more Camel
components.</span></li><li><span style="line-height: 1.4285715;">When Camel
components are unregistered SCR calls
</span><code>lostCamelComponent</code><span style="line-height:
1.4285715;"><code>()</code>. This call does nothing.</span></li><li><span
style="line-height: 1.4285715;">When one of the requirements that caused the
call to </span><code>activate</code><span style="line-height:
1.4285715;"><code>()</code> is lost SCR will call
</span><code>deactivate</code><span style="line-height:
1.4285715;"><code>()</code>. This will shutdown the
CamelContext.</span></li></ol><p>In (non-OSGi) unit tests you should use
<code>prepare()</c
ode> → <code>run()</code> → <code>stop()</code> instead
of <code>activate()</code> → <code>deactivate()</code> for more
fine-grained control. Also, this allows us to avoid possible SCR specific
operations in tests.</p><h3 id="CamelandSCR-Usingcamel-archetype-scr">Using
camel-archetype-scr</h3><p>The easiest way to create an Camel SCR bundle
project is to use <code>camel-archetype-scr</code> and Maven.</p><p>You
can generate a project with the following steps:</p><p> </p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Generating a
project</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: text; gutter: false"
type="syntaxhighlighter"><![CDATA[$ mvn archetype:generate
-Dfilter=org.apache.camel.archetypes:camel-archetype-scr
Â
Choose archetype:
@@ -176,7 +176,7 @@ archetypeGroupId: org.apache.camel.arche
archetypeVersion: 2.15-SNAPSHOT
className: CamelScrExample
Y: :]]></script>
-</div></div><p>All done! See ReadMe.txt in the generated project folder for
the next steps:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ReadMe.txt</b></div><div class="codeContent panelContent pdl">
+</div></div><p> </p><p>All done! See ReadMe.txt in the generated project
folder for the next steps:</p><p> </p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>ReadMe.txt</b></div><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: text; gutter: false"
type="syntaxhighlighter"><![CDATA[Camel SCR bundle project
========================
@@ -208,7 +208,7 @@ To deploy this project in Apache Karaf (
For more help see the Apache Camel documentation
http://camel.apache.org/]]></script>
-</div></div><h3 id="CamelandSCR-UnittestingCamelroutes">Unit testing Camel
routes</h3><p>Service Component is a POJO and has no special requirements for
(non-OSGi) unit testing. There are however some techniques that are specific to
Camel SCR or just make testing easier.</p><p><span style="line-height:
1.4285715;">Below is an example unit test, generated by </span><code
style="line-height: 1.4285715;">camel-archetype-scr</code><span
style="line-height: 1.4285715;">:</span></p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CamelScrExampleTest.java</b></div><div
class="codeContent panelContent pdl">
+</div></div><h3 id="CamelandSCR-UnittestingCamelroutes">Unit testing Camel
routes</h3><p>Service Component is a POJO and has no special requirements for
(non-OSGi) unit testing. There are however some techniques that are specific to
Camel SCR or just make testing easier.</p><p><span style="line-height:
1.4285715;">Below is an example unit test, generated by </span><code
style="line-height: 1.4285715;">camel-archetype-scr</code><span
style="line-height: 1.4285715;">:</span></p><p><span style="line-height:
1.4285715;"><br clear="none"></span></p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>CamelScrExampleTest.java</b></div><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[// This file was generated from
org.apache.camel.archetypes/camel-archetype-scr/2.15-SNAPSHOT
package example;
@@ -295,15 +295,15 @@ public class CamelScrExampleTest {
resultEndpoint.assertIsSatisfied();
}
}]]></script>
-</div></div><p>Now, let's take a look at the interesting bits one by
one.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Using
property prefixing</b></div><div class="codeContent panelContent pdl">
+</div></div><p> </p><p>Now, let's take a look at the interesting bits one
by one.</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Using property prefixing</b></div><div class="codeContent panelContent
pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ // Set property prefix for unit
testing
System.setProperty(CamelScrExample.PROPERTY_PREFIX,
"unit");]]></script>
-</div></div><p>This allows you to override parts of the configuration by
prefixing properties with "unit.". For example, <code>unit.from</code>
overrides <code>from</code> for the unit test.</p><p>Prefixes, as a whole, can
be used to cover the differences between the runtime environments where your
routes might run. Moving the unchanged bundle through development, testing and
production environments is a typical use case.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Getting test configuration from
annotations</b></div><div class="codeContent panelContent pdl">
+</div></div><p>This allows you to override parts of the configuration by
prefixing properties with "unit.". For example, <code>unit.from</code>
overrides <code>from</code> for the unit test.</p><p>Prefixes, as a whole, can
be used to cover the differences between the runtime environments where your
routes might run. Moving the unchanged bundle through development, testing and
production environments is a typical use case.</p><p> </p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Getting test configuration from
annotations</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ integration.prepare(null,
ScrHelper.getScrProperties(integration.getClass().getName()));]]></script>
-</div></div><p>Here we configure the Service Component in test with the same
properties that would be used in OSGi environment.</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Mocking components for test</b></div><div
class="codeContent panelContent pdl">
+</div></div><p>Here we configure the Service Component in test with the same
properties that would be used in OSGi environment.</p><p> </p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Mocking components for
test</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ // Fake a component for test
context.addComponent("amq", new MockComponent());]]></script>
-</div></div><p>Components that are not available in test can be mocked like
this to allow the route to start.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Adjusting routes for test</b></div><div
class="codeContent panelContent pdl">
+</div></div><p>Components that are not available in test can be mocked like
this to allow the route to start.</p><p> </p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Adjusting routes for test</b></div><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ // Adjust routes
List<RouteDefinition> routes = context.getRouteDefinitions();
@@ -316,10 +316,10 @@ public class CamelScrExampleTest {
mockEndpoints("log:*");
}
});]]></script>
-</div></div><p>Camel's AdviceWith feature allows routes to be modified for
test.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Starting the routes</b></div><div class="codeContent panelContent pdl">
+</div></div><p>Camel's AdviceWith feature allows routes to be modified for
test.</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Starting the routes</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ // Start the integration
integration.run();]]></script>
-</div></div><p>Here we start the Service Component and along with it the
routes.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Sending
a test message</b></div><div class="codeContent panelContent pdl">
+</div></div><p>Here we start the Service Component and along with it the
routes.</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Sending a test message</b></div><div class="codeContent panelContent
pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ // Send the test message
context.createProducerTemplate().sendBody("direct:start",
"hello");]]></script>
</div></div><p>Here we send a message to a route in test.</p></div>
