Author: gertv
Date: Fri Jun 25 01:11:16 2010
New Revision: 957773
URL: http://svn.apache.org/viewvc?rev=957773&view=rev
Log:
Finishing Camel deployment options, adding tech selection guide and some NMR
info
Added:
servicemix/documentation/trunk/docs/manual/src/confluence/getting_started/
servicemix/documentation/trunk/docs/manual/src/confluence/getting_started/technology_selection.wiki
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/camel-nmr.wiki
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/event-listeners.wiki
Modified:
servicemix/documentation/trunk/docs/manual/src/confluence/camel/deployment.wiki
servicemix/documentation/trunk/docs/manual/src/docbkx/manual.xml
Modified:
servicemix/documentation/trunk/docs/manual/src/confluence/camel/deployment.wiki
URL:
http://svn.apache.org/viewvc/servicemix/documentation/trunk/docs/manual/src/confluence/camel/deployment.wiki?rev=957773&r1=957772&r2=957773&view=diff
==============================================================================
---
servicemix/documentation/trunk/docs/manual/src/confluence/camel/deployment.wiki
(original)
+++
servicemix/documentation/trunk/docs/manual/src/confluence/camel/deployment.wiki
Fri Jun 25 01:11:16 2010
@@ -1,8 +1,114 @@
-h1. Deploying Camel routes
-There are a few different ways to deploy Camel routes on ServiceMix 4:
+h1. Deployment options
+There are a few different ways to deploy Camel routes on ServiceMix
${servicemx.version}:
* deploy routes in a plain Spring XML file
* deploy a bundle containing
*# routes defined in a Spring XML file
*# routes defined in the Java or Scala DSL
-
\ No newline at end of file
+Camel routes can also be deployed as part of a JBI SA, allowing you use Camel
for routing between JBI endpoints - this option will be discussed later when we
are talking about using JBI inside ServiceMix 4.
+
+h2. Deploy as a plain Spring XML file
+ServiceMix ${servicemix.version} supports the deployment of plain Spring XML
files, automatically creating and starting the Spring ApplicationContext from
the XML file.
+
+In order to leverage this feature to create and start Camel routes, drop a
file with this syntax in the {{$SERVICEMIX_HOME/deploy}} folder:
+{code:lang=xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns:camel="http://camel.apache.org/schema/spring";
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+ http://camel.apache.org/schema/spring
+
http://camel.apache.org/schema/spring/camel-spring-${camel-version}.xsd";>
+
+ <camelContext xmlns="http://camel.apache.org/schema/spring";>
+ <!-- add Camel routes, interceptors,... here -->
+ </camelContext>
+
+</beans>
+{code}
+
+h3. An example
+Just create a new XML file in the deploy folder with the code below to start a
route to copy files from one directory to another.
+{code:lang=xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns:camel="http://camel.apache.org/schema/spring";
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+ http://camel.apache.org/schema/spring
+
http://camel.apache.org/schema/spring/camel-spring-${camel-version}.xsd";>
+
+ <camelContext xmlns="http://camel.apache.org/schema/spring";>
+ <route>
+ <from uri="file:input"/>
+ <log message="Copying ${file:name} to the output directory"/>
+ <to uri="file:output"/>
+ </route>
+ </camelContext>
+
+</beans>
+{code}
+
+h2. Deploy as an OSGi bundle
+The Spring XML file can also be deployed as part of a bundle by adding it to
the {{META-INF/spring}} folder. When the bundle is being started, the Spring
ApplicationContext is created and started as well. This kind of deployment
also allows using Java or Scala Routebuilders for defining the routes.
+
+h3. Using the XML file to define the routes
+The route can be defined directly in the XML file you add to
{{META-INF/spring}}, similar to the example shown before.
+
+h3. Using a Java or Scala RouteBuilder
+When using a Java (or Scala) RouteBuilder to define your Camel routes, the
Spring XML file refers to the packages containing the RouteBuilder classes:
+{code:lang=xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns:camel="http://camel.apache.org/schema/spring";
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+ http://camel.apache.org/schema/spring
+
http://camel.apache.org/schema/spring/camel-spring-${camel-version}.xsd";>
+
+ <camelContext xmlns="http://camel.apache.org/schema/spring";>
+ <package>org.apache.servicemix.manual.camel</package>
+ </camelContext>
+
+</beans>
+{code}
+
+The matching Java RouteBuilder class could look like this
+{code:lang=java}
+package org.apache.servicemix.manual.camel;
+
+import org.apache.camel.builder.RouteBuilder;
+
+public class MyRouteBuilder extends RouteBuilder {
+
+ public void configure() {
+ from("file:input")
+ .log("Copying ${file:name} to the output directory")
+ .to("file:output");
+ }
+
+}
+{code}
+
+A similar Scala RouteBuilder could look like
+{code:lang=scala}
+package org.apache.servicemix.manual.camel;
+
+import org.apache.camel.scala.dsl.builder.RouteBuilder;
+
+class MyRouteBuilder extends RouteBuilder {
+
+ "file:input" ==> {
+ log("Copying ${file:name} to the output directory")
+ to("file:output")
+ }
+
+}
+{code}
+
Added:
servicemix/documentation/trunk/docs/manual/src/confluence/getting_started/technology_selection.wiki
URL:
http://svn.apache.org/viewvc/servicemix/documentation/trunk/docs/manual/src/confluence/getting_started/technology_selection.wiki?rev=957773&view=auto
==============================================================================
---
servicemix/documentation/trunk/docs/manual/src/confluence/getting_started/technology_selection.wiki
(added)
+++
servicemix/documentation/trunk/docs/manual/src/confluence/getting_started/technology_selection.wiki
Fri Jun 25 01:11:16 2010
@@ -0,0 +1,34 @@
+h1. Technology selection guide
+ServiceMix 4 offers a set of different messaging and integration technologies:
+* ActiveMQ
+* Camel
+* CXF
+* JBI
+* NMR
+
+Depending on the solution you're building, you want to select one or more of
these technologies. Below are some guidelines to help you pick the right mix
for your problem.
+
+h2. When to use Camel?
+For any integration scenario, we recommend to start as simple as possible.
Camel allows you to build routes for integration scenario's quickly and
efficiently. You can deploy these routes directly on ServiceMix by deploying
the plain Spring XML route or by packaging the route in an OSGi bundle.
+
+As you need more (advanced) features, start combining Camel with ActiveMQ, CXF
and/or the NMR
+
+h2. When to use ActiveMQ?
+ActiveMQ is a JMS message broker, featuring support for clustering, pluggable
persistence mechanism, master-slave configuration for failover, ...
+
+ServiceMix 4 includes an instance of the ActiveMQ broker, which can be
combined with Camel to provide easy-to-use message persistence and reliable
messaging.
+
+After setting up multiple instances of ActiveMQ (or ServiceMix 4) on the
network, you can configure ActiveMQ clustering or master-slave mode to allow
for a more reliable and scalable set-up.
+
+h2. When to use CXF?
+CXF is an open-source services framework that you can use to suit your WS-*
standards integration needs. It allows you to use common programming APIs like
JAX-RS or JAX-WS for building your own services and to expose them to the
outside world.
+
+You can use CXF from within your Camel routes with the Camel CXF component.
+
+h2. When to use NMR?
+The NMR provides the basic ESB features for ServiceMix 4. You can use it to
connect multiple camel routes in a lightweight way. It can also be used as a
common transport on which you can add container-level auditing by registering
your own ExchangeListener implementation.
+
+h2. When to use JBI?
+If you want to build a full-blown SOA solution using BPEL, ServiceMix includes
a version of Apache ODE that integrates well with JBI messaging. Because we
still support JBI 1.0 on ServiceMix, you can also move your existing JBI
artifacts from ServiceMix 3 to the new container with no/minimal changes.
+
+
Added:
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/camel-nmr.wiki
URL:
http://svn.apache.org/viewvc/servicemix/documentation/trunk/docs/manual/src/confluence/nmr/camel-nmr.wiki?rev=957773&view=auto
==============================================================================
---
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/camel-nmr.wiki
(added)
+++
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/camel-nmr.wiki
Fri Jun 25 01:11:16 2010
@@ -0,0 +1,54 @@
+h1. Camel NMR Component
+
+The Camel NMR component is an adapter to the Normalized Message Router (NMR)
in ServiceMix, which is intended for use by Camel applications deployed
directly into the OSGi container.
+
+h2. Installing
+
+In order to be able to use this component, you first have to define it in
your Spring configuration file ({{META-INF/spring/*.xml}}) by adding the
following {{bean}}:
+
+{code}
+<beans xmlns:osgi="http://www.springframework.org/schema/osgi"; ... >
+ ...
+ <bean id="nmr" class="org.apache.servicemix.camel.nmr.ServiceMixComponent">
+ <property name="nmr">
+ <osgi:reference interface="org.apache.servicemix.nmr.api.NMR" />
+ </property>
+ </bean>
+ ...
+</beans>
+{code}
+
+h2. NMR consumer and producer endpoints
+
+The following code:
+
+{code}
+from("nmr:MyServiceEndpoint")
+{code}
+
+Automatically exposes a new endpoint to the bus with endpoint name
{{MyServiceEndpoint}} (see [#URI-format]).
+
+When an NMR endpoint appears at the end of a route, for example:
+
+{code}
+to("nmr:MyServiceEndpoint")
+{code}
+
+The messages sent by this producer endpoint are sent to the already deployed
JBI endpoint.
+
+h2. URI format
+
+{code}
+nmr:endpointName
+{code}
+
+h4. URI Options
+- *{{synchronous}}* (defaults to {{false}}) :: When this is set to {{true}}
on a consumer endpoint, an incoming, synchronous NMR Exchange will be handled
on the sender's thread instead of being handled on a new thread of the NMR
endpoint's thread pool |
+
+
+h3. Examples
+
+{code}
+from("nmr:MyServiceEndpoint")
+from("nmr:MyServiceEndpoint?synchronous=true").to("nmr:AnotherEndpoint")
+{code}
Added:
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/event-listeners.wiki
URL:
http://svn.apache.org/viewvc/servicemix/documentation/trunk/docs/manual/src/confluence/nmr/event-listeners.wiki?rev=957773&view=auto
==============================================================================
---
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/event-listeners.wiki
(added)
+++
servicemix/documentation/trunk/docs/manual/src/confluence/nmr/event-listeners.wiki
Fri Jun 25 01:11:16 2010
@@ -0,0 +1,89 @@
+h1. Event listeners
+
+The NMR has a rich event API that can be used to receive all sort of
notifications about what's happening in the NMR.
+Currently, two types of listeners are defined:
+- {{org.apache.servicemix.nmr.api.event.EndpointListener}}
+- {{org.apache.servicemix.nmr.api.event.ExchangeListener}}
+
+h2. Endpoint Listener
+
+h3. API
+The {{EndpointListener}} defined two methods:
+- {{endpointRegistered}} is called whenever a new endpoint is registered with
the NMR
+- {{endpointUnregistered}} is called whenever an existing endpoint is
unregistered
+
+{code:lang=java}
+public interface EndpointListener {
+ void endpointRegistered(InternalEndpoint endpoint);
+ void endpointUnregistered(InternalEndpoint endpoint);
+}
+{code}
+
+h3. Registering {{EndpointListener}}
+An {{EndpointListener}} can be registered directly with the NMR:
+{code:lang=java}
+nmr.getListenerRegistry().register(listener, null);
+{code}
+
+The recommended way of registering an {{EndpointListener}} is by adding it to
the OSGi Service Registry, e.g. using a Blueprint XML file:
+{code:lang=xml}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0";
+
xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0";>
+
+ <bean id="myListener" class="..."/>
+
+ <service ref="myListener">
+ <interfaces>
+ <value>org.apache.servicemix.nmr.api.event.EndpointListener</value>
+ <value>org.apache.servicemix.nmr.api.event.Listener</value>
+ </interfaces>
+ </service>
+
+</blueprint>
+{code}
+
+h3. Example
+An example of using an endpoint listener is shipped as part of the ServiceMix
distribution. It can be found in the {{examples/interceptors/endpoint}}
directory.
+
+h2. ExchangeListener
+
+h3. API
+The {{ExchangeListener}} defined two methods:
+- {{exchangeSent}} is called whenever an exchange is sent to the NMR for
delivery
+- {{exchangeDelivered}} is called whenever an exchange is being delivered to
an endpoint
+- {{exchangeFailed}} is called when a failure occurs while handling an exchange
+
+
+{code:lang=java}
+public interface ExchangeListener {
+ void exchangeSent(Exchange exchange);
+ void exchangeDelivered(Exchange exchange);
+ void exchangeFailed(Exchange exchange);
+}
+{code}
+
+h3. Registering {{ExchangeListener}}
+An {{ExchangeListener}} can be registered directly with the NMR:
+{code:lang=java}
+nmr.getListenerRegistry().register(listener, null);
+{code}
+
+The recommended way of registering an {{ExchangeListener}} is by adding it to
the OSGi Service Registry, e.g. using a Blueprint XML file:
+{code:lang=xml}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0";
+
xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0";>
+
+ <bean id="myListener" class="..."/>
+
+ <service ref="myListener">
+ <interfaces>
+ <value>org.apache.servicemix.nmr.api.event.ExchangeListener</value>
+ <value>org.apache.servicemix.nmr.api.event.Listener</value>
+ </interfaces>
+ </service>
+
+</blueprint>
+{code}
+
+h3. Example
+An example of using an exchange listener is shipped as part of the ServiceMix
distribution. It can be found in the {{examples/interceptors/exchange}}
directory.
\ No newline at end of file
Modified: servicemix/documentation/trunk/docs/manual/src/docbkx/manual.xml
URL:
http://svn.apache.org/viewvc/servicemix/documentation/trunk/docs/manual/src/docbkx/manual.xml?rev=957773&r1=957772&r2=957773&view=diff
==============================================================================
--- servicemix/documentation/trunk/docs/manual/src/docbkx/manual.xml (original)
+++ servicemix/documentation/trunk/docs/manual/src/docbkx/manual.xml Fri Jun 25
01:11:16 2010
@@ -101,6 +101,8 @@
<!-- Chapter on installation and build -->
<xi:include href="installation.xml"/>
+
+ <xi:include href="getting_started/technology_selection.wiki.xml"/>
</part>
<part>
@@ -119,6 +121,9 @@
<part>
<title>NMR</title>
+
+ <xi:include href="nmr/camel-nmr.wiki.xml"/>
+ <xi:include href="nmr/event-listeners.wiki.xml"/>
</part>
<part>
