faq update (#21804)

* CAMEL-16861: Cleanup docs

Author: davsclaus

components/camel-cxf/camel-cxf-soap/src/main/docs/cxf-component.adoc

@@ -1134,4 +1134,90 @@ ServletRequest request = (ServletRequest) cxfMessage.get("HTTP.REQUEST");
 String remoteAddress = request.getRemoteAddr();
 ----
 
+== How to switch the CXF consumer between HTTP and HTTPS without touching the Spring configuration?
+
+You can find general information how to secure your Camel CXF Consumer with HTTPS in the
+http://cxf.apache.org/docs/client-http-transport-including-ssl-support.html[Apache CXF Client HTTP transport documentation].
+
+A simple Camel CXF Consumer configuration which use the `\http:conduit`
+configuration to enable SSL and an external properties file for all
+environment specific configurations could look like in Spring XML:
+
+.Spring XML
+[source,xml]
+----
+<beans xmlns="http://www.springframework.org/schema/beans"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:ctx="http://www.springframework.org/schema/context"
+  xmlns:camel="http://camel.apache.org/schema/spring"
+  xmlns:camel-cxf="http://camel.apache.org/schema/cxf"
+  xmlns:http="http://cxf.apache.org/transports/http/configuration"
+  xmlns:sec="http://cxf.apache.org/configuration/security"
+  xsi:schemaLocation="
+    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+    http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
+    http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
+    http://camel.apache.org/schema/osgi http://camel.apache.org/schema/osgi/camel-osgi.xsd
+    http://camel.apache.org/schema/cxf http://camel.apache.org/schema/cxf/camel-cxf.xsd
+    http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd
+    http://cxf.apache.org/configuration/security http://cxf.apache.org/schemas/configuration/security.xsd
+    ">
+
+  <import resource="classpath:META-INF/cxf/cxf.xml" />
+  <import resource="classpath:META-INF/cxf/cxf-extension-soap.xml" />
+  <import resource="classpath:META-INF/cxf/cxf-extension-http-jetty.xml" />
+
+  <ctx:property-placeholder location="classpath:orderEntry.cfg" />
+
+  <camel-cxf:cxfEndpoint id="orderEntryEndpoint"
+    address="${endpointUri}"
+    serviceClass="com.company.product.OrderEntryService"
+    endpointName="ssp:OrderEntry"
+    serviceName="ssp:OrderEntryService"
+    wsdlURL="META-INF/orderEntry/orderEntry.wsdl"
+    xmlns:ssp="http://www.company.com/product/orderEntry/service/1" />
+
+  <http:conduit name="{http://www.company.com/product/orderEntry/service/1}OrderEntry.http-conduit">
+    <http:tlsClientParameters disableCNCheck="true">
+      <sec:trustManagers>
+        <sec:keyStore type="JKS" password="${trustStore.password}" file="${trustStore.file}"/>
+      </sec:trustManagers>
+      <sec:cipherSuitesFilter>
+        <sec:include>.*_EXPORT_.*</sec:include>
+        <sec:include>.*_EXPORT1024_.*</sec:include>
+        <sec:include>.*_WITH_DES_.*</sec:include>
+        <sec:include>.*_WITH_NULL_.*</sec:include>
+        <sec:exclude>.*_DH_anon_.*</sec:exclude>
+      </sec:cipherSuitesFilter>
+    </http:tlsClientParameters>
+  </http:conduit>
+
+  <camel:camelContext trace="true">
+    <camel:routeBuilder ref="orderEntryRoute" />
+  </camel:camelContext>
+
+  <bean id="orderEntryRoute" class="com.company.product.OrderEntryRoute" />
+</beans>
+----
+
+The environment specific configurations are externalized into a properties file:
+
+*orderEntry.cfg*
+[source,java]
+----
+endpointUri=https://localhost:8181/OrderEntry
+trustStore.password=password
+trustStore.file=etc/myApp.ts
+----
+
+With this configuration, you Camel CXF consumer connects with HTTPS to the web service provider.
+
+If you need to change the protocol to HTTP, maybe for tracing/debugging
+reasons, change the `endpointUri` property in your properties file to
+e.g. `\http://localhost:8080/OrderEntry`.
+
+Apache CXF detects that you _only_ use HTTP and instantiates a
+`HttpURLConnectionFactoryImpl` instead of a `HttpsURLConnectionFactory`.
+
+
 include::spring-boot:partial$starter.adoc[]

core/camel-core-engine/src/main/docs/modules/eips/pages/removeHeaders-eip.adoc

@@ -109,6 +109,20 @@ YAML::
 ----
 ====
 
+== Leaking Camel headers when sending to an endpoint
+
+When I send a message to a Camel endpoint such as the
+xref:components::mail-component.adoc[Mail] component, then the mail include some message
+headers I do not want. How can I avoid this?
+
+This is a gotcha more people encounter. However, it's very easy to solve.
+To remove all headers (see above) use a `*` expression:
+
+Most components will automatically remove all Camel specific headers (the header key starts with `Camel`) using
+the `DefaultHeaderFilterStrategy` which automatic removes these headers. However if you use a component that does
+not do this, such as a custom component, or a Camel component which has not been improved to do that, then you can
+remove all these Camel specific headers using `Camel*` with the `removeHeaders` EIP as shown previously on this page.
+
 == See Also
 
 Camel provides the following EIPs for removing headers or exchange properties:

docs/user-manual/modules/ROOT/pages/component.adoc

@@ -139,6 +139,21 @@ Component-DSL is a builder API that allows using type-safe construction of Camel
 
 This is an advanced topic and described in more detail in the xref:writing-components.adoc[Writing Components Guide].
 
+=== Using HeaderFilterStrategy with components
+
+Some components supports configuring a custom header filter strategy.
+
+This allows you to implement the
+`org.apache.camel.spi.HeaderFilterStrategy` interface, where one can
+filter unwanted headers from the communication while not removing them from the
+`Exchange`.
+
+Camel core offers a default filter strategy implementation, the
+`DefaultHeaderFilterStrategy`, to which one can provide a regular expression
+pattern or a set of header names to be filtered out.
+
+
+
 == See Also
 
 - List of all Camel xref:components::index.adoc[Components]

docs/user-manual/modules/ROOT/pages/endpoint.adoc

@@ -177,6 +177,27 @@ So if you write the following XML it should work...
 </route>
 ----
 
+If you do not escape the & sign, then you can `org.xml.sax.SAXParseException` or other kind of XML parsing errors.
+
+In the URIs used for specifying Camel endpoints, the `&` is used to
+separate the parameters. However, `&` also is a reserved character in XML.
+
+Because of this, you have to replace all `&` in your URIs by `+&amp;+` when
+using the XML DSL to configure Camel routes.
+
+An example: this snippet of code in Java DSL:
+
+[source,java]
+----
+from("timer://myTimer?fixedRate=true&delay=0&period=2000")
+----
+
+... matches this example in the XML syntax where `&` has been replaced with `+&amp;+`
+
+[source,xml]
+----
+<from uri="timer://myTimer?fixedRate=true&amp;delay=0&amp;period=2000"/>
+----
 
 === Configuring parameter values using raw values, such as passwords
 

docs/user-manual/modules/ROOT/pages/exception-clause.adoc

@@ -725,6 +725,51 @@ And the same example in YAML DSL
             uri: mock:result
 ----
 
+== Why is the exception null when I use onException ?
+
+If you use `onException` to handle exceptions, and want to get the caused
+`Exception` from a `Processor` in Java code, such as shown below:
+
+[source,java]
+----
+.onException(Exception.class)
+    .handled(true)
+    .process(new Processor() {
+        @Override
+        public void process(Exchange exchange) throws Exception {
+            Exception cause = exchange.getException();
+            // why cause exception is null ???
+        }
+    })
+.end()
+----
+
+Then beware the caused exception is no longer available from `exchange.getException()`, because
+the message is processed by the `onException` block.
+
+Instead, you can access the caused exception from exchange property on the
+exchange with the key `Exchange.EXCEPTION_CAUGHT`, as follows:
+
+[source,java]
+----
+Exception cause = exchange.getProperty(Exchange.EXCEPTION_CAUGHT, Exception.class);
+----
+
+The correct code to use in the example is there:
+
+[source,java]
+----
+.onException(Exception.class).handled(true)
+    .process(new Processor() {
+        @Override
+        public void process(Exchange exchange) throws Exception {
+            Exception cause = exchange.getProperty(Exchange.EXCEPTION_CAUGHT, Exception.class);
+            // we now have the caused exception
+        }
+    })
+.end()
+----
+
 == Handling and Sending a Fixed Response Back to the Client
 
 In the route above we handled the exception but routed it to a different

docs/user-manual/modules/faq/nav.adoc

@@ -4,19 +4,10 @@
 ** xref:how-can-i-get-the-source-code.adoc[How can I get the source code?]
 ** xref:how-do-i-become-a-committer.adoc[How do I become a committer?]
 ** xref:how-do-i-edit-the-website.adoc[How do I edit the website?]
-** xref:running-camel-standalone.adoc[Running Camel standalone]
 ** xref:what-is-camel.adoc[What is Camel?]
 ** xref:ROOT:languages.adoc[What languages are supported?]
 ** xref:why-the-name-camel.adoc[Why the name Camel?]
-** xref:how-to-avoid-sending-some-or-all-message-headers.adoc[How to avoid sending some or all message headers?]
 ** xref:how-to-remove-the-http-protocol-headers-in-the-camel-message.adoc[How to remove the http protocol headers in the camel message?]
-** xref:how-to-switch-the-cxf-consumer-between-http-and-https-without-touching-the-spring-configuration.adoc[How to switch the CXF consumer between HTTP and HTTPS without touching the Spring configuration?]
 ** xref:how-to-use-a-dynamic-uri-in-to.adoc[How to use a dynamic URI in to()?]
 ** xref:using-getin-or-getout-methods-on-exchange.adoc[Using getIn or getOut methods on Exchange]
-** xref:why-can-i-not-use-when-or-otherwise-in-a-java-camel-route.adoc[Why can I not use when or otherwise in a Java Camel route?]
-** xref:why-does-my-file-consumer-not-pick-up-the-file-and-how-do-i-let-the-file-consumer-use-the-camel-error-handler.adoc[Why does my file consumer not pick up the file, and how do I let the file consumer use the Camel error handler?]
-** xref:why-does-useoriginalmessage-with-error-handler-not-work-as-expected.adoc[Why does useOriginalMessage with error handler not work as expected?]
 ** xref:why-is-my-message-body-empty.adoc[Why is my message body empty?]
-** xref:why-is-the-exception-null-when-i-use-onexception.adoc[Why is the exception null when I use onException?]
-** xref:exception-orgapachecamelnosuchendpointexception.adoc[Exception - org.apache.camel.NoSuchEndpointException]
-** xref:exception-orgxmlsaxsaxparseexception.adoc[Exception - org.xml.sax.SAXParseException]