CAMEL-16861: Cleanup docs

Author: davsclaus

components/camel-seda/src/main/docs/seda-component.adoc

@@ -34,8 +34,8 @@ If you need persistence, reliability or distributed SEDA, try using xref:jms-com
 ====
 *Synchronous*
 
-The xref:direct-component.adoc[Direct] component provides synchronous invocation
-of any consumers when a producer sends a message exchange.
+The xref:direct-component.adoc[Direct] component provides synchronous invocation (uses no threading; it directly invokes the
+consumer when sending) of any consumers when a producer sends a message exchange.
 ====
 
 == URI format

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

@@ -126,6 +126,58 @@ in the xref:registry.adoc[Registry] that the file endpoint should use.
 file://inbox?idempontentRepository=#type:org.apache.camel.spi.IdempotentRepository
 ----
 
+=== Configuring endpoint URIs in XML escaping & sign
+
+If you try and use one of the Camel xref:ROOT:uris.adoc[URIs] in an
+XML DSL using the URI query parameter notation, such as:
+
+[source,xml]
+----
+<route>
+  <from uri="direct:start?paramA=1&paramB=2"/>
+  <to uri="mock:result"/>
+</route>
+----
+
+you might get errors such as...
+
+----
+Caused by: org.xml.sax.SAXParseException: The reference to entity "paramB" must end with the ';' delimiter.
+  at com.sun.org.apache.xerces.internal.util.ErrorHandlerWrapper.createSAXParseException(ErrorHandlerWrapper.java:236)
+  at
+----
+
+This is because in XML you need to escape some special XML characters
+like these:
+
+[width="100%",cols="50%,50%",options="header",]
+|==================================================
+|Special Character |How to escape it in XML
+a|`&`
+
+a|`+&amp;+`
+
+a|`<`
+
+a|`+&lt;+`
+
+a|`>`
+
+a|`+&gt;+`
+
+|==================================================
+
+So if you write the following XML it should work...
+
+[source,xml]
+----
+<route>
+  <from uri="direct:start?paramA=1&amp;paramB=2"/>
+  <to uri="mock:result"/>
+</route>
+----
+
+
 === Configuring parameter values using raw values, such as passwords
 
 When configuring endpoint options using URI syntax, then the values is
@@ -322,6 +374,56 @@ The default maximum cache size is 1000.
 
 You need to configure this before xref:ROOT:camelcontext.adoc[CamelContext] is started.
 
+== Configuring time duration using hours, minutes syntax
+
+Some of the Camel xref:ROOT:component.adoc[components] offers options to
+specify a time period, which must be entered in millisecond as unit.
+
+This may be unfriendly to read as a human when the value is large such
+as `2700000` millis (45 minutes).
+
+In Camel you can configure this in a more readable syntax as explained:
+
+[width="100%",cols="50%,50%",options="header",]
+|============
+|Syntax |Unit
+|h |hour
+|m |minute
+|s |second
+|============
+
+So for example the xref:components::timer-component.adoc[Timer] endpoint can be configured as
+follows:
+
+[source,java]
+----
+from("timer:foo?period=45m").to("log:foo");
+----
+
+You can mix and match the units so you can do this as well:
+
+[source,java]
+----
+from("timer:foo?period=1h15m").to("log:foo");
+from("timer:bar?period=2h30s").to("log:bar");
+from("timer:bar?period=3h45m58s").to("log:bar");
+----
+
+However, you can also use long syntax:
+
+[width="100%",cols="50%,50%",options="header",]
+|=========================
+|Syntax |Unit
+|hour _or_ hours |hour
+|minute _or_ minutes |minute
+|second _or_ seconds |second
+|=========================
+
+[source,java]
+----
+from("timer:foo?period=45minutes").to("log:foo");
+----
+
 
 == Java Endpoint API
 

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

@@ -137,6 +137,50 @@ camel.main.tracing-logging-format = %-4.4s [%-30.30s] [%-50.50s]
 ----
 ====
 
+=== Configuring maximum length of message body
+
+When you run Camel with logging, it will log the messages and its
+content from time to time.
+
+As some messages can contain very big payloads Camel will by default
+clip the log message and only show the first 1000 chars.
+
+You will see this in the log as:
+
+[source,log]
+----
+DEBUG ProducerCache                  - >>>> Endpoint[direct:start] Exchange[Message: 01234567890123456789... [Body clipped after 20 chars, total length is 1000]]
+----
+
+
+[tabs]
+====
+
+Java::
++
+In Java you can set the maximum length as a global option.
++
+[source,java]
+----
+context.getGlobalOptions().put(Exchange.LOG_DEBUG_BODY_MAX_CHARS, "500");
+----
+
+Application Properties::
++
+You can also set the limit in `application.properties`.
++
+[source,properties]
+-----
+camel.main.globalOptions[CamelLogDebugBodyMaxChars] = 500
+-----
+====
+
+NOTE: You can customize the limit when Camel clips the body in the log.
+You can use a limit of 0 to disable limit, so the entire body is
+shown. Setting a negative value, such as -1, means
+the message body is not logged at all.
+
+
 == See Also
 
 - xref:backlog-tracer.adoc[Backlog Tracer]

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

@@ -13,12 +13,7 @@
 ** xref:ROOT:languages.adoc[What languages are supported?]
 ** xref:what-platforms-are-supported.adoc[What platforms are supported?]
 ** xref:why-the-name-camel.adoc[Why the name Camel?]
-** xref:how-do-i-specify-which-method-to-use-when-using-beans-in-routes.adoc[How do I specify which method to use when using beans in routes?]
 ** xref:how-does-camel-look-up-beans-and-endpoints.adoc[How does Camel look up beans and endpoints?]
-** xref:how-do-i-reuse-the-contexttestsupport-class-in-my-unit-tests.adoc[How do I reuse the ContextTestSupport class in my unit tests?]
-** xref:how-do-i-set-the-max-chars-when-debug-logging-messages-in-camel.adoc[How do I set the max chars when debug logging messages in Camel?]
-** xref:how-do-i-use-uris-with-parameters-in-xml.adoc[How do I use URIs with parameters in XML?]
-** xref:how-do-i-write-a-custom-processor-which-sends-multiple-messages.adoc[How do I write a custom Processor which sends multiple messages?]
 ** xref:how-should-i-invoke-my-pojos-or-spring-services.adoc[How should I invoke my POJOs or Spring Services?]
 ** 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?]
@@ -38,9 +33,6 @@
 ** xref:why-is-the-exception-null-when-i-use-onexception.adoc[Why is the exception null when I use onException?]
 ** xref:why-use-multiple-camelcontext.adoc[Why use multiple CamelContext?]
 ** xref:how-do-i-use-log4j.adoc[How do I use log4j?]
-** xref:how-do-i-set-the-mep-when-interacting-with-jbi.adoc[How do I set the MEP when interacting with JBI?]
-** xref:how-do-the-direct-event-seda-and-vm-endpoints-compare.adoc[How do the direct, event, seda and vm endpoints compare?]
-** xref:how-do-the-timer-and-quartz-endpoints-compare.adoc[How do the Timer and Quartz endpoints compare?]
 ** xref:why-does-my-jms-route-only-consume-one-message-at-once.adoc[Why does my JMS route only consume one message at once?]
 ** xref:exception-orgapachecamelnosuchendpointexception.adoc[Exception - org.apache.camel.NoSuchEndpointException]
 ** xref:exception-orgxmlsaxsaxparseexception.adoc[Exception - org.xml.sax.SAXParseException]