SMX4-617: Add troubleshooting section and more information about features
git-svn-id: https://svn.apache.org/repos/asf/servicemix/documentation/trunk@1072374 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/main/webapp/users-guide/camel/camel-guide.pdf.conf b/src/main/webapp/users-guide/camel/camel-guide.pdf.conf
index 0f3354d..92dcfc7 100644
--- a/src/main/webapp/users-guide/camel/camel-guide.pdf.conf
+++ b/src/main/webapp/users-guide/camel/camel-guide.pdf.conf
@@ -8,4 +8,13 @@
{include:users-guide/camel/deployment/index.conf}
{include:users-guide/camel/deployment/plain-spring.conf}
{include:users-guide/camel/deployment/plain-blueprint.conf}
-{include:users-guide/camel/deployment/osgi-bundle.conf}
+{include:users-guide/camel/deployment/osgi-bundle-spring.conf}
+{include:users-guide/camel/deployment/osgi-bundle-blueprint.conf}
+
+h1. Installing components
+{include:users-guide/camel/installing-components.conf}
+
+h1. Troubleshooting
+{include:users-guide/camel/troubleshooting.conf}
+
+
diff --git a/src/main/webapp/users-guide/camel/deployment/index.conf b/src/main/webapp/users-guide/camel/deployment/index.conf
index 946170a..11d2e5b 100644
--- a/src/main/webapp/users-guide/camel/deployment/index.conf
+++ b/src/main/webapp/users-guide/camel/deployment/index.conf
@@ -6,3 +6,20 @@
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.
+h3. Benefits and drawbacks
+
+h4. Plain XML or OSGi bundles
+Choose a plain XML file:
+* if you want to get routes deployed as quickly as possible \\ all you need for developing routes is a simple text editor, no compilation, building, ... required at all
+* if you prefer the XML syntax over the Java of Scala DSL
+
+Choose an OSGi bundle:
+* if you want to package helper classes together with your route definitions
+* if you prefer developing routes in the Java or Scala DSL \\ you can package the RouteBuilder implementations inside the bundle
+
+h4. Blueprint or Spring
+Choose Blueprint:
+* if you want the best possible integration with the OSGi Framework and Service Registy \\ the Blueprint specification has been developed specifically for the OSGi Framework by the OSGi Alliance
+
+Choose Spring:
+* if you already invested in Spring for creating and running Camel routes
\ No newline at end of file
diff --git a/src/main/webapp/users-guide/camel/deployment/osgi-bundle-blueprint.conf b/src/main/webapp/users-guide/camel/deployment/osgi-bundle-blueprint.conf
new file mode 100644
index 0000000..3b9c24f
--- /dev/null
+++ b/src/main/webapp/users-guide/camel/deployment/osgi-bundle-blueprint.conf
@@ -0,0 +1,33 @@
+h2. Deploy as an OSGi bundle
+
+Using an OSGi bundle to deploy your Camel routes allows you to use the Java or Scala DSL for defining your routes.
+
+In this case, we will use a Blueprint XML file to start your Camel routs. To do so, the Blueprint XML files have to be included in the bundle inside the {{OSGI-INF/blueprint}} directory.
+{pygmentize:lang=text}
++ <bundle classes, incl. your RouteBuilder>
+|- META-INF
+| |- MANIFEST.MF
+\- OSGI-INF
+ \- blueprint
+ \- camel-context.xml
+{pygmentize}
+
+As soon as the bundle becomes Active, the Blueprint extender will create the Blueprint container starting your Routes.
+
+h3. Example: Referring to Java or Scala RouteBuilder classes
+If your RouteBuilder classes have been defined in the {{org.apache.servicemix.manual.camel}} package, the file would look like this:
+{pygmentize:lang=xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<blueprint
+ xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://www.osgi.org/xmlns/blueprint/v1.0.0
+ http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">
+
+ <camelContext xmlns="http://camel.apache.org/schema/blueprint">
+ <package>org.apache.servicemix.manual.camel</package>
+ </camelContext>
+
+</blueprint>
+{pygmentize}
\ No newline at end of file
diff --git a/src/main/webapp/users-guide/camel/deployment/osgi-bundle-spring.conf b/src/main/webapp/users-guide/camel/deployment/osgi-bundle-spring.conf
new file mode 100644
index 0000000..5ebb651
--- /dev/null
+++ b/src/main/webapp/users-guide/camel/deployment/osgi-bundle-spring.conf
@@ -0,0 +1,34 @@
+h2. Deploy as an OSGi bundle with Spring
+
+Using an OSGi bundle to deploy your Camel routes allows you to use the Java or Scala DSL for defining your routes.
+
+In this case, you're using Spring to start your Camel routes, so you include your Spring XML file (e.g. {{camel-context.xml}}) in the {{META-INF/spring}} folder inside your bundle.
+{pygmentize:lang=text}
++ <bundle classes, incl. your RouteBuilder>
+\- META-INF
+ |- MANIFEST.MF
+ \- spring
+ \- camel-context.xml
+{pygmentize}
+
+After the bundle has been activated, the Spring DM extender will find, create and start your Spring ApplicationContexts.
+
+h3. Example: Referring to Java or Scala RouteBuilder classes
+If your RouteBuilder classes have been defined in the {{org.apache.servicemix.manual.camel}} package, the file would look like this:
+{pygmentize: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>
+{pygmentize}
\ No newline at end of file
diff --git a/src/main/webapp/users-guide/camel/deployment/osgi-bundle.conf b/src/main/webapp/users-guide/camel/deployment/osgi-bundle.conf
deleted file mode 100644
index a8c73c0..0000000
--- a/src/main/webapp/users-guide/camel/deployment/osgi-bundle.conf
+++ /dev/null
@@ -1,60 +0,0 @@
-h2. Deploy as an OSGi bundle
-
-Using an OSGi bundle to deploy your Camel routes allows you to use the Java or Scala DSL for defining your routes. The routes are still being started by a Spring or Blueprint XML file, which is included inside the OSGi bundle.
-
-h3. Using Spring
-When using Spring to start your Camel routes, you include your Spring XML file (e.g. {{camel-context.xml}}) in the {{META-INF/spring}} folder inside your bundle. After the bundle has been activated, the Spring DM extender will find, create and start your Spring ApplicationContexts.
-{noformat}
-+ <bundle classes, incl. your RouteBuilder>
-\- META-INF
- |- MANIFEST.MF
- \- spring
- \- camel-context.xml
-{noformat}
-
-Example: If your RouteBuilder classes have been defined in the {{org.apache.servicemix.manual.camel}} package, the file would look like this:
-{pygmentize: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>
-{pygmentize}
-
-h3. Using Blueprint
-When using Blueprint to start your Camel routes, the Blueprint XML files have to be included in the bundle inside the {{OSGI-INF/blueprint}} directory.
-{noformat}
-+ <bundle classes, incl. your RouteBuilder>
-|- META-INF
-| |- MANIFEST.MF
-\- OSGI-INF
- \- blueprint
- \- camel-context.xml
-{noformat}
-
-Example: If your RouteBuilder classes have been defined in the {{org.apache.servicemix.manual.camel}} package, the file would look like this:
-{pygmentize:lang=xml}
-<?xml version="1.0" encoding="UTF-8"?>
-<blueprint
- xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://www.osgi.org/xmlns/blueprint/v1.0.0
- http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">
-
- <camelContext xmlns="http://camel.apache.org/schema/blueprint">
- <package>org.apache.servicemix.manual.camel</package>
- </camelContext>
-
-</blueprint>
-{pygmentize}
\ No newline at end of file
diff --git a/src/main/webapp/users-guide/camel/index.conf b/src/main/webapp/users-guide/camel/index.conf
index 40d7c11..982fc65 100644
--- a/src/main/webapp/users-guide/camel/index.conf
+++ b/src/main/webapp/users-guide/camel/index.conf
@@ -13,8 +13,10 @@
h2. More information about Camel
-More information about Camel itself, can be found on http://camel.apache.org.
+More information about Camel itself, can be found on [http://camel.apache.org].
-There's also a great book available about Camel:
+There's also a great book available about Camel
* Ibsen, Claus, and Anstey, Jonathan. (December 2010). _Camel in Action_. Greenwich, CT: Manning. ISBN: 9781935182368.
+!http://www.manning.com/ibsen/ibsen_cover150.jpg!
+
diff --git a/src/main/webapp/users-guide/camel/installing-components.conf b/src/main/webapp/users-guide/camel/installing-components.conf
new file mode 100644
index 0000000..d91079f
--- /dev/null
+++ b/src/main/webapp/users-guide/camel/installing-components.conf
@@ -0,0 +1,32 @@
+Camel comes with over 80 components, so you can imagine that we don't install all of them by default. This section shows you how to find available components and how to install them at runtime.
+
+h3. List available components
+Camel components are available as installable features. You can look at the full list of available features using the {{features:list}} command, using {{grep}} to limit things down to features related to camel:
+
+{pygmentize:lang=text}
+karaf@root> features:list | grep camel
+[installed ] [${camel.version} ] camel repo-0
+[installed ] [${camel.version} ] camel-core repo-0
+[installed ] [${camel.version} ] camel-spring repo-0
+[installed ] [${camel.version} ] camel-blueprint repo-0
+[uninstalled] [${camel.version} ] camel-test repo-0
+[uninstalled] [${camel.version} ] camel-cxf repo-0
+[uninstalled] [${camel.version} ] camel-cache repo-0
+[uninstalled] [${camel.version} ] camel-castor repo-0
+...
+{pygmentize}
+
+The items marked with *{{installed}}* in the first column have already been installed and are available for use in your Camel routes.
+
+h3. Install and uninstalling components
+You can use {{features:install}} to install any component on the list.
+
+An example: to install the {{camel-cache}} component
+{pygmentize:lang=text}
+karaf@root> features:install camel-cache
+{pygmentize}
+
+Similarly, you can also uninstall components that you're no longer using with {{features:uninstall}}
+{pygmentize:lang=text}
+karaf@root> features:uninstall camel-cache
+{pygementize}
diff --git a/src/main/webapp/users-guide/camel/toc.ssp b/src/main/webapp/users-guide/camel/toc.ssp
index cc5c6dd..58e1757 100644
--- a/src/main/webapp/users-guide/camel/toc.ssp
+++ b/src/main/webapp/users-guide/camel/toc.ssp
@@ -6,9 +6,16 @@
<ul>
<li id="plain-blueprint"><a href="${uri("/users-guide/camel/deployment/plain-blueprint.html")}">Plain Blueprint XML</a></li>
<li id="plain-spring"><a href="${uri("/users-guide/camel/deployment/plain-spring.html")}">Plain Spring XML</a></li>
- <li id="osgi-bundle"><a href="${uri("/users-guide/camel/deployment/osgi-bundle.html")}">OSGi Bundle</a></li>
+ <li id="osgi-bundle-spring"><a href="${uri("/users-guide/camel/deployment/osgi-bundle-spring.html")}">OSGi Bundle using Spring</a></li>
+ <li id="osgi-bundle-blueprint"><a href="${uri("/users-guide/camel/deployment/osgi-bundle-blueprint.html")}">OSGi Bundle using Blueprint</a></li>
</ul>
</li>
+ <li id="installing-components">
+ <a href="${uri("/users-guide/camel/installing-components.html")}">Installing components</a>
+ </li>
+ <li id="troubleshooting">
+ <a href="${uri("/users-guide/camel/troubleshooting.html")}">Troubleshooting</a>
+ </li>
</ul>
</li>
</ul>
\ No newline at end of file
diff --git a/src/main/webapp/users-guide/camel/troubleshooting.conf b/src/main/webapp/users-guide/camel/troubleshooting.conf
new file mode 100644
index 0000000..ffe3aff
--- /dev/null
+++ b/src/main/webapp/users-guide/camel/troubleshooting.conf
@@ -0,0 +1,10 @@
+In this section, you'll find solutions for some frequently asked questions when using Camel on ServicMix.
+
+h3. No component with id 'xyz' could be found
+This usually means that your route is trying to use a component that hasn't been installed yet.
+
+Solution:
+# install the additional component
+# restart the bundle using the {{osg:restart <bundle id>}} command - you can find the bundle id for your route in the output of the {{osgi:list}} command
+
+Refer to [Installing additional components|/users-guide/camel/installing-components] for more information about installing additional components.
