You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicemix.apache.org by ge...@apache.org on 2010/06/25 03:11:17 UTC
svn commit: r957773 - in /servicemix/documentation/trunk/docs/manual/src:
confluence/camel/ confluence/getting_started/ confluence/nmr/ docbkx/
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>