You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2016/08/16 08:04:11 UTC
[47/51] [partial] camel git commit: CAMEL-9541: Use -component as
suffix for component docs.
http://git-wip-us.apache.org/repos/asf/camel/blob/9c0b7baf/camel-core/src/main/docs/log-component.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/log-component.adoc b/camel-core/src/main/docs/log-component.adoc
new file mode 100644
index 0000000..0e9f414
--- /dev/null
+++ b/camel-core/src/main/docs/log-component.adoc
@@ -0,0 +1,302 @@
+[[Log-LogComponent]]
+Log Component
+~~~~~~~~~~~~~
+
+The *log:* component logs message exchanges to the underlying logging
+mechanism.
+
+Camel uses http://www.slf4j.org/[sfl4j] which allows you to configure
+logging via, among others:
+
+* http://logging.apache.org/log4j/[Log4j]
+* http://logback.qos.ch/[Logback]
+*
+http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html[JDK
+Util Logging logging]
+
+[[Log-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,java]
+-----------------------------
+log:loggingCategory[?options]
+-----------------------------
+
+Where *loggingCategory* is the name of the logging category to use. You
+can append query options to the URI in the following format,
+`?option=value&option=value&...`
+
+INFO:*Using Logger instance from the the Registry*
+As of *Camel 2.12.4/2.13.1*, if there's single instance
+of�`org.slf4j.Logger` found in the Registry, the *loggingCategory* is no
+longer used to create logger instance. The registered instance is used
+instead. Also it is possible to reference particular�`Logger` instance
+using�`?logger=#myLogger` URI parameter. Eventually, if there's no
+registered and URI�`logger` parameter, the logger instance is created
+using *loggingCategory*.
+
+For example, a log endpoint typically specifies the logging level using
+the `level` option, as follows:
+
+[source,java]
+----------------------------------------
+log:org.apache.camel.example?level=DEBUG
+----------------------------------------
+
+The default logger logs every exchange (_regular logging_). But Camel
+also ships with the `Throughput` logger, which is used whenever the
+`groupSize` option is specified.
+
+TIP:*Also a log in the DSL*
+There is also a `log` directly in the DSL, but it has a different
+purpose. Its meant for lightweight and human logs. See more details at
+link:logeip.html[LogEIP].
+
+[[Log-Options]]
+Options
+^^^^^^^
+
+
+// component options: START
+The Log component supports 1 options which are listed below.
+
+
+
+{% raw %}
+[width="100%",cols="2s,1m,8",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| exchangeFormatter | ExchangeFormatter | Sets a custom ExchangeFormatter to convert the Exchange to a String suitable for logging. If not specified we default to DefaultExchangeFormatter.
+|=======================================================================
+{% endraw %}
+// component options: END
+
+
+
+// endpoint options: START
+The Log component supports 27 endpoint options which are listed below:
+
+{% raw %}
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| loggerName | producer | | String | *Required* The logger name to use
+| groupActiveOnly | producer | true | Boolean | If true will hide stats when no new messages have been received for a time interval if false show stats regardless of message traffic.
+| groupDelay | producer | | Long | Set the initial delay for stats (in millis)
+| groupInterval | producer | | Long | If specified will group message stats by this time interval (in millis)
+| groupSize | producer | | Integer | An integer that specifies a group size for throughput logging.
+| level | producer | INFO | String | Logging level to use. The default value is INFO.
+| marker | producer | | String | An optional Marker name to use.
+| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange.
+| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
+| maxChars | formatting | 10000 | int | Limits the number of characters logged per line.
+| multiline | formatting | false | boolean | If enabled then each information is outputted on a newline.
+| showAll | formatting | false | boolean | Quick option for turning all options on. (multiline maxChars has to be manually set if to be used)
+| showBody | formatting | true | boolean | Show the message body.
+| showBodyType | formatting | true | boolean | Show the body Java type.
+| showCaughtException | formatting | false | boolean | f the exchange has a caught exception show the exception message (no stack trace). A caught exception is stored as a property on the exchange (using the key link org.apache.camel.ExchangeEXCEPTION_CAUGHT and for instance a doCatch can catch exceptions.
+| showException | formatting | false | boolean | If the exchange has an exception show the exception message (no stacktrace)
+| showExchangeId | formatting | false | boolean | Show the unique exchange ID.
+| showExchangePattern | formatting | true | boolean | Shows the Message Exchange Pattern (or MEP for short).
+| showFiles | formatting | false | boolean | If enabled Camel will output files
+| showFuture | formatting | false | boolean | If enabled Camel will on Future objects wait for it to complete to obtain the payload to be logged.
+| showHeaders | formatting | false | boolean | Show the message headers.
+| showOut | formatting | false | boolean | If the exchange has an out message show the out message.
+| showProperties | formatting | false | boolean | Show the exchange properties.
+| showStackTrace | formatting | false | boolean | Show the stack trace if an exchange has an exception. Only effective if one of showAll showException or showCaughtException are enabled.
+| showStreams | formatting | false | boolean | Whether Camel should show stream bodies or not (eg such as java.io.InputStream). Beware if you enable this option then you may not be able later to access the message body as the stream have already been read by this logger. To remedy this you will have to use Stream Caching.
+| skipBodyLineSeparator | formatting | true | boolean | Whether to skip line separators when logging the message body. This allows to log the message body in one line setting this option to false will preserve any line separators from the body which then will log the body as is.
+| style | formatting | Default | OutputStyle | Sets the outputs style to use.
+|=======================================================================
+{% endraw %}
+// endpoint options: END
+
+
+[[Log-Regularloggersample]]
+Regular logger sample
+^^^^^^^^^^^^^^^^^^^^^
+
+In the route below we log the incoming orders at `DEBUG` level before
+the order is processed:
+
+[source,java]
+------------------------------------------------------------------------------------------
+from("activemq:orders").to("log:com.mycompany.order?level=DEBUG").to("bean:processOrder");
+------------------------------------------------------------------------------------------
+
+Or using Spring XML to define the route:
+
+[source,xml]
+---------------------------------------------------
+ <route>
+ <from uri="activemq:orders"/>
+ <to uri="log:com.mycompany.order?level=DEBUG"/>
+ <to uri="bean:processOrder"/>
+ </route>
+---------------------------------------------------
+
+[[Log-Regularloggerwithformattersample]]
+Regular logger with formatter sample
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the route below we log the incoming orders at `INFO` level before the
+order is processed.
+
+[source,java]
+--------------------------------------------------------------------------------------
+from("activemq:orders").
+ to("log:com.mycompany.order?showAll=true&multiline=true").to("bean:processOrder");
+--------------------------------------------------------------------------------------
+
+[[Log-ThroughputloggerwithgroupSizesample]]
+Throughput logger with groupSize sample
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the route below we log the throughput of the incoming orders at
+`DEBUG` level grouped by 10 messages.
+
+[source,java]
+-----------------------------------------------------------------------------------
+from("activemq:orders").
+ to("log:com.mycompany.order?level=DEBUG&groupSize=10").to("bean:processOrder");
+-----------------------------------------------------------------------------------
+
+[[Log-ThroughputloggerwithgroupIntervalsample]]
+Throughput logger with groupInterval sample
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This route will result in message stats logged every 10s, with an
+initial 60s delay and stats should be displayed even if there isn't any
+message traffic.
+
+[source,java]
+-----------------------------------------------------------------------------------------------------------------------------
+from("activemq:orders").
+to("log:com.mycompany.order?level=DEBUG&groupInterval=10000&groupDelay=60000&groupActiveOnly=false").to("bean:processOrder");
+-----------------------------------------------------------------------------------------------------------------------------
+
+The following will be logged:
+
+[source,java]
+------------------------------------------------------------------------------------------------------------------------------------
+"Received: 1000 new messages, with total 2000 so far. Last group took: 10000 millis which is: 100 messages per second. average: 100"
+------------------------------------------------------------------------------------------------------------------------------------
+
+[[Log-Fullcustomizationoftheloggingoutput]]
+Full customization of the logging output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.11*
+
+With the options outlined in the link:log.html[#Formatting] section, you
+can control much of the output of the logger. However, log lines will
+always follow this structure:
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------
+Exchange[Id:ID-machine-local-50656-1234567901234-1-2, ExchangePattern:InOut,
+Properties:{CamelToEndpoint=log://org.apache.camel.component.log.TEST?showAll=true,
+CamelCreatedTimestamp=Thu Mar 28 00:00:00 WET 2013},
+Headers:{breadcrumbId=ID-machine-local-50656-1234567901234-1-1}, BodyType:String, Body:Hello World, Out: null]
+--------------------------------------------------------------------------------------------------------------
+
+This format is unsuitable in some cases, perhaps because you need to...
+
+* ... filter the headers and properties that are printed, to strike a
+balance between insight and verbosity.
+* ... adjust the log message to whatever you deem most readable.
+* ... tailor log messages for digestion by log mining systems, e.g.
+Splunk.
+* ... print specific body types differently.
+* ... etc.
+
+Whenever you require absolute customization, you can create a class that
+implements the
+http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/spi/ExchangeFormatter.html[`ExchangeFormatter`]
+interface. Within the `format(Exchange)` method you have access to the
+full Exchange, so you can select and extract the precise information you
+need, format it in a custom manner and return it. The return value will
+become the final log message.
+
+You can have the Log component pick up your custom `ExchangeFormatter`
+in either of two ways:
+
+*Explicitly instantiating the LogComponent in your Registry:*
+
+[source,java]
+---------------------------------------------------------------------
+<bean name="log" class="org.apache.camel.component.log.LogComponent">
+ <property name="exchangeFormatter" ref="myCustomFormatter" />
+</bean>
+---------------------------------------------------------------------
+
+*Convention over configuration:*
+
+Simply by registering a bean with the name `logFormatter`; the Log
+Component is intelligent enough to pick it up automatically.
+
+[source,java]
+----------------------------------------------------------------------
+<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" />
+----------------------------------------------------------------------
+
+NOTE: the `ExchangeFormatter` gets applied to *all Log endpoints within
+that Camel Context*. If you need different ExchangeFormatters for
+different endpoints, just instantiate the LogComponent as many times as
+needed, and use the relevant bean name as the endpoint prefix.
+
+From *Camel 2.11.2/2.12* onwards when using a custom log formatter, you
+can specify parameters in the log uri, which gets configured on the
+custom log formatter. Though when you do that you should define the
+"logFormatter" as prototype scoped so its not shared if you have
+different parameters, eg:
+
+[source,java]
+---------------------------------------------------------------------------------------
+<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" scope="prototype"/>
+---------------------------------------------------------------------------------------
+
+And then we can have Camel routes using the log uri with different
+options:
+
+[source,java]
+---------------------------------------------
+<to uri="log:foo?param1=foo&param2=100"/>
+...
+<to uri="log:bar?param1=bar&param2=200"/>
+---------------------------------------------
+
+[[Log-UsingLogcomponentinOSGi]]
+Using Log component in OSGi
++++++++++++++++++++++++++++
+
+*Improvement as of Camel 2.12.4/2.13.1*
+
+When using�Log component inside OSGi (e.g., in Karaf), the underlying
+logging mechanisms are provided by PAX logging. It searches for a bundle
+which invokes�`org.slf4j.LoggerFactory.getLogger()` method and
+associates the bundle with the logger instance. Without specifying
+custom�`org.sfl4j.Logger` instance, the logger created by Log component
+is associated with `camel-core` bundle.
+
+In some scenarios it is required that the bundle associated with logger
+should be the bundle which contains route definition. To do this, either
+register single instance of�`org.slf4j.Logger` in the Registry or
+reference it using�`logger` URI parameter.
+
+[[Log-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+
+* link:tracer.html[Tracer]
+* link:how-do-i-use-log4j.html[How do I use log4j]
+* link:how-do-i-use-java-14-logging.html[How do I use Java 1.4 logging]
+* link:logeip.html[LogEIP] for using `log` directly in the DSL for human
+logs.
+
http://git-wip-us.apache.org/repos/asf/camel/blob/9c0b7baf/camel-core/src/main/docs/log.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/log.adoc b/camel-core/src/main/docs/log.adoc
deleted file mode 100644
index 0e9f414..0000000
--- a/camel-core/src/main/docs/log.adoc
+++ /dev/null
@@ -1,302 +0,0 @@
-[[Log-LogComponent]]
-Log Component
-~~~~~~~~~~~~~
-
-The *log:* component logs message exchanges to the underlying logging
-mechanism.
-
-Camel uses http://www.slf4j.org/[sfl4j] which allows you to configure
-logging via, among others:
-
-* http://logging.apache.org/log4j/[Log4j]
-* http://logback.qos.ch/[Logback]
-*
-http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html[JDK
-Util Logging logging]
-
-[[Log-URIformat]]
-URI format
-^^^^^^^^^^
-
-[source,java]
------------------------------
-log:loggingCategory[?options]
------------------------------
-
-Where *loggingCategory* is the name of the logging category to use. You
-can append query options to the URI in the following format,
-`?option=value&option=value&...`
-
-INFO:*Using Logger instance from the the Registry*
-As of *Camel 2.12.4/2.13.1*, if there's single instance
-of�`org.slf4j.Logger` found in the Registry, the *loggingCategory* is no
-longer used to create logger instance. The registered instance is used
-instead. Also it is possible to reference particular�`Logger` instance
-using�`?logger=#myLogger` URI parameter. Eventually, if there's no
-registered and URI�`logger` parameter, the logger instance is created
-using *loggingCategory*.
-
-For example, a log endpoint typically specifies the logging level using
-the `level` option, as follows:
-
-[source,java]
-----------------------------------------
-log:org.apache.camel.example?level=DEBUG
-----------------------------------------
-
-The default logger logs every exchange (_regular logging_). But Camel
-also ships with the `Throughput` logger, which is used whenever the
-`groupSize` option is specified.
-
-TIP:*Also a log in the DSL*
-There is also a `log` directly in the DSL, but it has a different
-purpose. Its meant for lightweight and human logs. See more details at
-link:logeip.html[LogEIP].
-
-[[Log-Options]]
-Options
-^^^^^^^
-
-
-// component options: START
-The Log component supports 1 options which are listed below.
-
-
-
-{% raw %}
-[width="100%",cols="2s,1m,8",options="header"]
-|=======================================================================
-| Name | Java Type | Description
-| exchangeFormatter | ExchangeFormatter | Sets a custom ExchangeFormatter to convert the Exchange to a String suitable for logging. If not specified we default to DefaultExchangeFormatter.
-|=======================================================================
-{% endraw %}
-// component options: END
-
-
-
-// endpoint options: START
-The Log component supports 27 endpoint options which are listed below:
-
-{% raw %}
-[width="100%",cols="2s,1,1m,1m,5",options="header"]
-|=======================================================================
-| Name | Group | Default | Java Type | Description
-| loggerName | producer | | String | *Required* The logger name to use
-| groupActiveOnly | producer | true | Boolean | If true will hide stats when no new messages have been received for a time interval if false show stats regardless of message traffic.
-| groupDelay | producer | | Long | Set the initial delay for stats (in millis)
-| groupInterval | producer | | Long | If specified will group message stats by this time interval (in millis)
-| groupSize | producer | | Integer | An integer that specifies a group size for throughput logging.
-| level | producer | INFO | String | Logging level to use. The default value is INFO.
-| marker | producer | | String | An optional Marker name to use.
-| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange.
-| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
-| maxChars | formatting | 10000 | int | Limits the number of characters logged per line.
-| multiline | formatting | false | boolean | If enabled then each information is outputted on a newline.
-| showAll | formatting | false | boolean | Quick option for turning all options on. (multiline maxChars has to be manually set if to be used)
-| showBody | formatting | true | boolean | Show the message body.
-| showBodyType | formatting | true | boolean | Show the body Java type.
-| showCaughtException | formatting | false | boolean | f the exchange has a caught exception show the exception message (no stack trace). A caught exception is stored as a property on the exchange (using the key link org.apache.camel.ExchangeEXCEPTION_CAUGHT and for instance a doCatch can catch exceptions.
-| showException | formatting | false | boolean | If the exchange has an exception show the exception message (no stacktrace)
-| showExchangeId | formatting | false | boolean | Show the unique exchange ID.
-| showExchangePattern | formatting | true | boolean | Shows the Message Exchange Pattern (or MEP for short).
-| showFiles | formatting | false | boolean | If enabled Camel will output files
-| showFuture | formatting | false | boolean | If enabled Camel will on Future objects wait for it to complete to obtain the payload to be logged.
-| showHeaders | formatting | false | boolean | Show the message headers.
-| showOut | formatting | false | boolean | If the exchange has an out message show the out message.
-| showProperties | formatting | false | boolean | Show the exchange properties.
-| showStackTrace | formatting | false | boolean | Show the stack trace if an exchange has an exception. Only effective if one of showAll showException or showCaughtException are enabled.
-| showStreams | formatting | false | boolean | Whether Camel should show stream bodies or not (eg such as java.io.InputStream). Beware if you enable this option then you may not be able later to access the message body as the stream have already been read by this logger. To remedy this you will have to use Stream Caching.
-| skipBodyLineSeparator | formatting | true | boolean | Whether to skip line separators when logging the message body. This allows to log the message body in one line setting this option to false will preserve any line separators from the body which then will log the body as is.
-| style | formatting | Default | OutputStyle | Sets the outputs style to use.
-|=======================================================================
-{% endraw %}
-// endpoint options: END
-
-
-[[Log-Regularloggersample]]
-Regular logger sample
-^^^^^^^^^^^^^^^^^^^^^
-
-In the route below we log the incoming orders at `DEBUG` level before
-the order is processed:
-
-[source,java]
-------------------------------------------------------------------------------------------
-from("activemq:orders").to("log:com.mycompany.order?level=DEBUG").to("bean:processOrder");
-------------------------------------------------------------------------------------------
-
-Or using Spring XML to define the route:
-
-[source,xml]
----------------------------------------------------
- <route>
- <from uri="activemq:orders"/>
- <to uri="log:com.mycompany.order?level=DEBUG"/>
- <to uri="bean:processOrder"/>
- </route>
----------------------------------------------------
-
-[[Log-Regularloggerwithformattersample]]
-Regular logger with formatter sample
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In the route below we log the incoming orders at `INFO` level before the
-order is processed.
-
-[source,java]
---------------------------------------------------------------------------------------
-from("activemq:orders").
- to("log:com.mycompany.order?showAll=true&multiline=true").to("bean:processOrder");
---------------------------------------------------------------------------------------
-
-[[Log-ThroughputloggerwithgroupSizesample]]
-Throughput logger with groupSize sample
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In the route below we log the throughput of the incoming orders at
-`DEBUG` level grouped by 10 messages.
-
-[source,java]
------------------------------------------------------------------------------------
-from("activemq:orders").
- to("log:com.mycompany.order?level=DEBUG&groupSize=10").to("bean:processOrder");
------------------------------------------------------------------------------------
-
-[[Log-ThroughputloggerwithgroupIntervalsample]]
-Throughput logger with groupInterval sample
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This route will result in message stats logged every 10s, with an
-initial 60s delay and stats should be displayed even if there isn't any
-message traffic.
-
-[source,java]
------------------------------------------------------------------------------------------------------------------------------
-from("activemq:orders").
-to("log:com.mycompany.order?level=DEBUG&groupInterval=10000&groupDelay=60000&groupActiveOnly=false").to("bean:processOrder");
------------------------------------------------------------------------------------------------------------------------------
-
-The following will be logged:
-
-[source,java]
-------------------------------------------------------------------------------------------------------------------------------------
-"Received: 1000 new messages, with total 2000 so far. Last group took: 10000 millis which is: 100 messages per second. average: 100"
-------------------------------------------------------------------------------------------------------------------------------------
-
-[[Log-Fullcustomizationoftheloggingoutput]]
-Full customization of the logging output
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Available as of Camel 2.11*
-
-With the options outlined in the link:log.html[#Formatting] section, you
-can control much of the output of the logger. However, log lines will
-always follow this structure:
-
-[source,java]
---------------------------------------------------------------------------------------------------------------
-Exchange[Id:ID-machine-local-50656-1234567901234-1-2, ExchangePattern:InOut,
-Properties:{CamelToEndpoint=log://org.apache.camel.component.log.TEST?showAll=true,
-CamelCreatedTimestamp=Thu Mar 28 00:00:00 WET 2013},
-Headers:{breadcrumbId=ID-machine-local-50656-1234567901234-1-1}, BodyType:String, Body:Hello World, Out: null]
---------------------------------------------------------------------------------------------------------------
-
-This format is unsuitable in some cases, perhaps because you need to...
-
-* ... filter the headers and properties that are printed, to strike a
-balance between insight and verbosity.
-* ... adjust the log message to whatever you deem most readable.
-* ... tailor log messages for digestion by log mining systems, e.g.
-Splunk.
-* ... print specific body types differently.
-* ... etc.
-
-Whenever you require absolute customization, you can create a class that
-implements the
-http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/spi/ExchangeFormatter.html[`ExchangeFormatter`]
-interface. Within the `format(Exchange)` method you have access to the
-full Exchange, so you can select and extract the precise information you
-need, format it in a custom manner and return it. The return value will
-become the final log message.
-
-You can have the Log component pick up your custom `ExchangeFormatter`
-in either of two ways:
-
-*Explicitly instantiating the LogComponent in your Registry:*
-
-[source,java]
----------------------------------------------------------------------
-<bean name="log" class="org.apache.camel.component.log.LogComponent">
- <property name="exchangeFormatter" ref="myCustomFormatter" />
-</bean>
----------------------------------------------------------------------
-
-*Convention over configuration:*
-
-Simply by registering a bean with the name `logFormatter`; the Log
-Component is intelligent enough to pick it up automatically.
-
-[source,java]
-----------------------------------------------------------------------
-<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" />
-----------------------------------------------------------------------
-
-NOTE: the `ExchangeFormatter` gets applied to *all Log endpoints within
-that Camel Context*. If you need different ExchangeFormatters for
-different endpoints, just instantiate the LogComponent as many times as
-needed, and use the relevant bean name as the endpoint prefix.
-
-From *Camel 2.11.2/2.12* onwards when using a custom log formatter, you
-can specify parameters in the log uri, which gets configured on the
-custom log formatter. Though when you do that you should define the
-"logFormatter" as prototype scoped so its not shared if you have
-different parameters, eg:
-
-[source,java]
----------------------------------------------------------------------------------------
-<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" scope="prototype"/>
----------------------------------------------------------------------------------------
-
-And then we can have Camel routes using the log uri with different
-options:
-
-[source,java]
----------------------------------------------
-<to uri="log:foo?param1=foo&param2=100"/>
-...
-<to uri="log:bar?param1=bar&param2=200"/>
----------------------------------------------
-
-[[Log-UsingLogcomponentinOSGi]]
-Using Log component in OSGi
-+++++++++++++++++++++++++++
-
-*Improvement as of Camel 2.12.4/2.13.1*
-
-When using�Log component inside OSGi (e.g., in Karaf), the underlying
-logging mechanisms are provided by PAX logging. It searches for a bundle
-which invokes�`org.slf4j.LoggerFactory.getLogger()` method and
-associates the bundle with the logger instance. Without specifying
-custom�`org.sfl4j.Logger` instance, the logger created by Log component
-is associated with `camel-core` bundle.
-
-In some scenarios it is required that the bundle associated with logger
-should be the bundle which contains route definition. To do this, either
-register single instance of�`org.slf4j.Logger` in the Registry or
-reference it using�`logger` URI parameter.
-
-[[Log-SeeAlso]]
-See Also
-^^^^^^^^
-
-* link:configuring-camel.html[Configuring Camel]
-* link:component.html[Component]
-* link:endpoint.html[Endpoint]
-* link:getting-started.html[Getting Started]
-
-* link:tracer.html[Tracer]
-* link:how-do-i-use-log4j.html[How do I use log4j]
-* link:how-do-i-use-java-14-logging.html[How do I use Java 1.4 logging]
-* link:logeip.html[LogEIP] for using `log` directly in the DSL for human
-logs.
-
http://git-wip-us.apache.org/repos/asf/camel/blob/9c0b7baf/camel-core/src/main/docs/mock-component.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/mock-component.adoc b/camel-core/src/main/docs/mock-component.adoc
new file mode 100644
index 0000000..b24e634
--- /dev/null
+++ b/camel-core/src/main/docs/mock-component.adoc
@@ -0,0 +1,515 @@
+ifdef::env-github[]
+:caution-caption: :boom:
+:important-caption: :exclamation:
+:note-caption: :information_source:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+
+[[Mock-MockComponent]]
+Mock Component
+~~~~~~~~~~~~~~
+
+link:testing.html[Testing] of distributed and asynchronous processing is
+notoriously difficult. The link:mock.html[Mock], link:test.html[Test]
+and link:dataset.html[DataSet] endpoints work great with the
+link:testing.html[Camel Testing Framework] to simplify your unit and
+integration testing using
+link:enterprise-integration-patterns.html[Enterprise Integration
+Patterns] and Camel's large range of link:components.html[Components]
+together with the powerful link:bean-integration.html[Bean Integration].
+
+The Mock component provides a powerful declarative testing mechanism,
+which is similar to http://www.jmock.org[jMock] in
+that it allows declarative expectations to be created on any Mock
+endpoint before a test begins. Then the test is run, which typically
+fires messages to one or more endpoints, and finally the expectations
+can be asserted in a test case to ensure the system worked as expected.
+
+This allows you to test various things like:
+
+* The correct number of messages are received on each endpoint,
+* The correct payloads are received, in the right order,
+* Messages arrive on an endpoint in order, using some
+link:expression.html[Expression] to create an order testing function,
+* Messages arrive match some kind of link:predicate.html[Predicate] such
+as that specific headers have certain values, or that parts of the
+messages match some predicate, such as by evaluating an
+link:xpath.html[XPath] or link:xquery.html[XQuery]
+link:expression.html[Expression].
+
+[NOTE]
+There is also the link:test.html[Test endpoint] which is a
+Mock endpoint, but which uses a second endpoint to provide the list of
+expected message bodies and automatically sets up the Mock endpoint
+assertions. In other words, it's a Mock endpoint that automatically sets
+up its assertions from some sample messages in a link:file2.html[File]
+or link:jpa.html[database], for example.
+
+[CAUTION]
+*Mock endpoints keep received Exchanges in memory indefinitely.* +
+ +
+Remember that Mock is designed for testing. When you add Mock endpoints
+to a route, each link:exchange.html[Exchange] sent to the endpoint will
+be stored (to allow for later validation) in memory until explicitly
+reset or the JVM is restarted. If you are sending high volume and/or
+large messages, this may cause excessive memory use. If your goal is to
+test deployable routes inline, consider using
+link:notifybuilder.html[NotifyBuilder] or
+link:advicewith.html[AdviceWith] in your tests instead of adding Mock
+endpoints to routes directly. +
+ +
+From Camel 2.10 onwards there are two new options `retainFirst`, and
+`retainLast` that can be used to limit the number of messages the Mock
+endpoints keep in memory.
+
+
+[[Mock-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source]
+----
+mock:someName[?options]
+----
+
+Where `someName` can be any string that uniquely identifies the
+endpoint.
+
+You can append query options to the URI in the following format,
+`?option=value&option=value&...`
+
+[[Mock-Options]]
+Options
+^^^^^^^
+
+
+
+
+// component options: START
+The Mock component has no options.
+// component options: END
+
+
+
+
+
+
+// endpoint options: START
+The Mock component supports 12 endpoint options which are listed below:
+
+{% raw %}
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| name | producer | | String | *Required* Name of mock endpoint
+| assertPeriod | producer | 0 | long | Sets a grace period after which the mock endpoint will re-assert to ensure the preliminary assertion is still valid. This is used for example to assert that exactly a number of messages arrives. For example if link expectedMessageCount(int) was set to 5 then the assertion is satisfied when 5 or more message arrives. To ensure that exactly 5 messages arrives then you would need to wait a little period to ensure no further message arrives. This is what you can use this link setAssertPeriod(long) method for. By default this period is disabled.
+| expectedCount | producer | -1 | int | Specifies the expected number of message exchanges that should be received by this endpoint. Beware: If you want to expect that 0 messages then take extra care as 0 matches when the tests starts so you need to set a assert period time to let the test run for a while to make sure there are still no messages arrived; for that use link setAssertPeriod(long). An alternative is to use NotifyBuilder and use the notifier to know when Camel is done routing some messages before you call the link assertIsSatisfied() method on the mocks. This allows you to not use a fixed assert period to speedup testing times. If you want to assert that exactly n'th message arrives to this mock endpoint then see also the link setAssertPeriod(long) method for further details.
+| reportGroup | producer | | int | A number that is used to turn on throughput logging based on groups of the size.
+| resultMinimumWaitTime | producer | 0 | long | Sets the minimum expected amount of time (in millis) the link assertIsSatisfied() will wait on a latch until it is satisfied
+| resultWaitTime | producer | 0 | long | Sets the maximum amount of time (in millis) the link assertIsSatisfied() will wait on a latch until it is satisfied
+| retainFirst | producer | -1 | int | Specifies to only retain the first n'th number of received Exchanges. This is used when testing with big data to reduce memory consumption by not storing copies of every Exchange this mock endpoint receives. Important: When using this limitation then the link getReceivedCounter() will still return the actual number of received Exchanges. For example if we have received 5000 Exchanges and have configured to only retain the first 10 Exchanges then the link getReceivedCounter() will still return 5000 but there is only the first 10 Exchanges in the link getExchanges() and link getReceivedExchanges() methods. When using this method then some of the other expectation methods is not supported for example the link expectedBodiesReceived(Object...) sets a expectation on the first number of bodies received. You can configure both link setRetainFirst(int) and link setRetainLast(int) methods to limit both the first and last received.
+| retainLast | producer | -1 | int | Specifies to only retain the last n'th number of received Exchanges. This is used when testing with big data to reduce memory consumption by not storing copies of every Exchange this mock endpoint receives. Important: When using this limitation then the link getReceivedCounter() will still return the actual number of received Exchanges. For example if we have received 5000 Exchanges and have configured to only retain the last 20 Exchanges then the link getReceivedCounter() will still return 5000 but there is only the last 20 Exchanges in the link getExchanges() and link getReceivedExchanges() methods. When using this method then some of the other expectation methods is not supported for example the link expectedBodiesReceived(Object...) sets a expectation on the first number of bodies received. You can configure both link setRetainFirst(int) and link setRetainLast(int) methods to limit both the first and last received.
+| sleepForEmptyTest | producer | 0 | long | Allows a sleep to be specified to wait to check that this endpoint really is empty when link expectedMessageCount(int) is called with zero
+| copyOnExchange | producer (advanced) | true | boolean | Sets whether to make a deep copy of the incoming Exchange when received at this mock endpoint. Is by default true.
+| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange.
+| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
+|=======================================================================
+{% endraw %}
+// endpoint options: END
+
+
+
+[[Mock-SimpleExample]]
+Simple Example
+^^^^^^^^^^^^^^
+
+Here's a simple example of Mock endpoint in use. First, the endpoint is
+resolved on the context. Then we set an expectation, and then, after the
+test has run, we assert that our expectations have been met:
+
+[source,java]
+----
+MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class);
+
+resultEndpoint.expectedMessageCount(2);
+
+// send some messages
+...
+
+// now lets assert that the mock:foo endpoint received 2 messages
+resultEndpoint.assertIsSatisfied();
+----
+
+You typically always call the
+http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#assertIsSatisfied()[`assertIsSatisfied()`]
+method to test that the expectations were met after running a test.
+
+Camel will by default wait 10 seconds when the `assertIsSatisfied()` is
+invoked. This can be configured by setting the
+`setResultWaitTime(millis)` method.
+
+[[Mock-UsingassertPeriod]]
+Using `assertPeriod`
+++++++++++++++++++++
+
+*Available as of Camel 2.7* +
+When the assertion is satisfied then Camel will stop waiting and
+continue from the `assertIsSatisfied` method. That means if a new
+message arrives on the mock endpoint, just a bit later, that arrival
+will not affect the outcome of the assertion. Suppose you do want to
+test that no new messages arrives after a period thereafter, then you
+can do that by setting the `setAssertPeriod` method, for example:
+
+[source,java]
+----
+MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class);
+resultEndpoint.setAssertPeriod(5000);
+resultEndpoint.expectedMessageCount(2);
+
+// send some messages
+...
+
+// now lets assert that the mock:foo endpoint received 2 messages
+resultEndpoint.assertIsSatisfied();
+----
+
+[[Mock-Settingexpectations]]
+Setting expectations
+^^^^^^^^^^^^^^^^^^^^
+
+You can see from the Javadoc of
+http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html[MockEndpoint]
+the various helper methods you can use to set expectations. The main
+methods are as follows:
+
+[width="100%",cols="1m,1",options="header",]
+|=======================================================================
+|Method |Description
+|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedMessageCount(int)[expectedMessageCount(int)]
+|To define the expected message count on the endpoint.
+
+|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedMinimumMessageCount(int)[expectedMinimumMessageCount(int)]
+|To define the minimum number of expected messages on the endpoint.
+
+|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedBodiesReceived(java.lang.Object...)[expectedBodiesReceived(...)]
+|To define the expected bodies that should be received (in order).
+
+|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedHeaderReceived(java.lang.String,%20java.lang.String)[expectedHeaderReceived(...)]
+|To define the expected header that should be received
+
+|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectsAscending(org.apache.camel.Expression)[expectsAscending(Expression)]
+|To add an expectation that messages are received in order, using the
+given link:expression.html[Expression] to compare messages.
+
+|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectsDescending(org.apache.camel.Expression)[expectsDescending(Expression)]
+|To add an expectation that messages are received in order, using the
+given link:expression.html[Expression] to compare messages.
+
+|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectsNoDuplicates(org.apache.camel.Expression)[expectsNoDuplicates(Expression)]
+|To add an expectation that no duplicate messages are received; using an
+link:expression.html[Expression] to calculate a unique identifier for
+each message. This could be something like the `JMSMessageID` if using
+JMS, or some unique reference number within the message.
+|=======================================================================
+
+Here's another example:
+
+[source,java]
+----
+resultEndpoint.expectedBodiesReceived("firstMessageBody", "secondMessageBody", "thirdMessageBody");
+----
+
+[[Mock-Addingexpectationstospecificmessages]]
+Adding expectations to specific messages
+++++++++++++++++++++++++++++++++++++++++
+
+In addition, you can use the
+http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#message(int)[`message(int
+messageIndex)`] method to add assertions about a specific message that is
+received.
+
+For example, to add expectations of the headers or body of the first
+message (using zero-based indexing like `java.util.List`), you can use
+the following code:
+
+[source,java]
+----
+resultEndpoint.message(0).header("foo").isEqualTo("bar");
+----
+
+There are some examples of the Mock endpoint in use in the
+http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/[`camel-core`
+processor tests].
+
+[[Mock-Mockingexistingendpoints]]
+Mocking existing endpoints
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.7*
+
+Camel now allows you to automatically mock existing endpoints in your
+Camel routes.
+
+[NOTE]
+*How it works* +
+ +
+*Important:* The endpoints are still in action. +
+What happens differently
+is that a link:mock.html[Mock] endpoint is injected and receives the
+message first and then delegates the message to the target endpoint. You
+can view this as a kind of intercept and delegate or endpoint listener.
+
+Suppose you have the given route below:
+
+[source,java]
+.*Route*
+----
+include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java[tags=route]
+----
+
+You can then use the `adviceWith` feature in Camel to mock all the
+endpoints in a given route from your unit test, as shown below:
+
+[source,java]
+.*`adviceWith` mocking all endpoints*
+----
+include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java[tags=e1]
+----
+
+Notice that the mock endpoints is given the URI `mock:<endpoint>`, for
+example `mock:direct:foo`. Camel logs at `INFO` level the endpoints
+being mocked:
+
+[source]
+----
+INFO Adviced endpoint [direct://foo] with mock endpoint [mock:direct:foo]
+----
+
+[NOTE]
+ **Mocked endpoints are without parameters** +
+Endpoints which are mocked will have their parameters stripped off. For
+example the endpoint `log:foo?showAll=true` will be mocked to the
+following endpoint `mock:log:foo`. Notice the parameters have been
+removed.
+
+Its also possible to only mock certain endpoints using a pattern. For
+example to mock all `log` endpoints you do as shown:
+
+[source,java]
+.*`adviceWith` mocking only log endpoints using a pattern*
+----
+include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java[tags=e2]
+----
+
+The pattern supported can be a wildcard or a regular expression. See
+more details about this at link:intercept.html[Intercept] as its the
+same matching function used by Camel.
+
+[NOTE]
+Mind that mocking endpoints causes the messages to be copied when they
+arrive on the mock. +
+That means Camel will use more memory. This may not be suitable when you
+send in a lot of messages.
+
+
+[[Mock-Mockingexistingendpointsusingthecamel-testcomponent]]
+Mocking existing endpoints using the `camel-test` component
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Instead of using the `adviceWith` to instruct Camel to mock endpoints,
+you can easily enable this behavior when using the `camel-test` Test
+Kit.
+
+The same route can be tested as follows. Notice that we return `"*"`
+from the `isMockEndpoints` method, which tells Camel to mock all
+endpoints.
+
+If you only want to mock all `log` endpoints you can return `"log*"`
+instead.
+
+[source,java]
+.*`isMockEndpoints` using camel-test kit*
+----
+include::../../../../components/camel-test/src/test/java/org/apache/camel/test/patterns/IsMockEndpointsJUnit4Test.java[tags=e1]
+----
+
+
+[[Mock-MockingexistingendpointswithXMLDSL]]
+Mocking existing endpoints with XML DSL
++++++++++++++++++++++++++++++++++++++++
+
+If you do not use the `camel-test` component for unit testing (as shown
+above) you can use a different approach when using XML files for
+routes. +
+The solution is to create a new XML file used by the unit test and then
+include the intended XML file which has the route you want to test.
+
+Suppose we have the route in the `camel-route.xml` file:
+
+[source,xml]
+.*camel-route.xml*
+----
+include::../../../../components/camel-spring/src/test/resources/org/apache/camel/spring/mock/camel-route.xml[tags=e1]
+----
+
+Then we create a new XML file as follows, where we include the
+`camel-route.xml` file and define a spring bean with the class
+`org.apache.camel.impl.InterceptSendToMockEndpointStrategy` which tells
+Camel to mock all endpoints:
+
+[source,xml]
+.*test-camel-route.xml*
+----
+include::../../../../components/camel-spring/src/test/resources/org/apache/camel/spring/mock/InterceptSendToMockEndpointStrategyTest.xml[tags=e1]
+----
+
+Then in your unit test you load the new XML file
+(`test-camel-route.xml`) instead of `camel-route.xml`.
+
+To only mock all link:log.html[Log] endpoints you can define the pattern
+in the constructor for the bean:
+
+[source,xml]
+----
+<bean id="mockAllEndpoints" class="org.apache.camel.impl.InterceptSendToMockEndpointStrategy">
+ <constructor-arg index="0" value="log*"/>
+</bean>
+----
+
+[[Mock-Mockingendpointsandskipsendingtooriginalendpoint]]
+Mocking endpoints and skip sending to original endpoint
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+*Available as of Camel 2.10*
+
+Sometimes you want to easily mock and skip sending to a certain
+endpoints. So the message is detoured and send to the mock endpoint
+only. From Camel 2.10 onwards you can now use the `mockEndpointsAndSkip`
+method using link:advicewith.html[AdviceWith] or the
+https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=Test+Kit&linkCreation=true&fromPageId=52081[Test
+Kit]. The example below will skip sending to the two endpoints
+`"direct:foo"`, and `"direct:bar"`.
+
+[source,java]
+.*adviceWith mock and skip sending to endpoints*
+----
+include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockMultipleEndpointsWithSkipTest.java[tags=e1]
+----
+
+The same example using the link:testing.html[Test Kit]
+
+[source,java]
+.*isMockEndpointsAndSkip using camel-test kit*
+----
+include::../../../../components/camel-test/src/test/java/org/apache/camel/test/patterns/IsMockEndpointsAndSkipJUnit4Test.java[tags=e1]
+----
+
+[[Mock-Limitingthenumberofmessagestokeep]]
+Limiting the number of messages to keep
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.10*
+
+The link:mock.html[Mock] endpoints will by default keep a copy of every
+link:exchange.html[Exchange] that it received. So if you test with a lot
+of messages, then it will consume memory. +
+From Camel 2.10 onwards we have introduced two options `retainFirst` and
+`retainLast` that can be used to specify to only keep N'th of the first
+and/or last link:exchange.html[Exchange]s.
+
+For example in the code below, we only want to retain a copy of the
+first 5 and last 5 link:exchange.html[Exchange]s the mock receives.
+
+[source,java]
+----
+ MockEndpoint mock = getMockEndpoint("mock:data");
+ mock.setRetainFirst(5);
+ mock.setRetainLast(5);
+ mock.expectedMessageCount(2000);
+
+ ...
+
+ mock.assertIsSatisfied();
+----
+
+Using this has some limitations. The `getExchanges()` and
+`getReceivedExchanges()` methods on the `MockEndpoint` will return only
+the retained copies of the link:exchange.html[Exchange]s. So in the
+example above, the list will contain 10 link:exchange.html[Exchange]s;
+the first five, and the last five. +
+The `retainFirst` and `retainLast` options also have limitations on
+which expectation methods you can use. For example the `expectedXXX`
+methods that work on message bodies, headers, etc. will only operate on
+the retained messages. In the example above they can test only the
+expectations on the 10 retained messages.
+
+[[Mock-Testingwitharrivaltimes]]
+Testing with arrival times
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Available as of Camel 2.7*
+
+The link:mock.html[Mock] endpoint stores the arrival time of the message
+as a property on the link:exchange.html[Exchange].
+
+[source,java]
+----
+Date time = exchange.getProperty(Exchange.RECEIVED_TIMESTAMP, Date.class);
+----
+
+You can use this information to know when the message arrived on the
+mock. But it also provides foundation to know the time interval between
+the previous and next message arrived on the mock. You can use this to
+set expectations using the `arrives` DSL on the link:mock.html[Mock]
+endpoint.
+
+For example to say that the first message should arrive between 0-2
+seconds before the next you can do:
+
+[source,java]
+----
+mock.message(0).arrives().noLaterThan(2).seconds().beforeNext();
+----
+
+You can also define this as that 2nd message (0 index based) should
+arrive no later than 0-2 seconds after the previous:
+
+[source,java]
+----
+mock.message(1).arrives().noLaterThan(2).seconds().afterPrevious();
+----
+
+You can also use between to set a lower bound. For example suppose that
+it should be between 1-4 seconds:
+
+[source,java]
+----
+mock.message(1).arrives().between(1, 4).seconds().afterPrevious();
+----
+
+You can also set the expectation on all messages, for example to say
+that the gap between them should be at most 1 second:
+
+[source,java]
+----
+mock.allMessages().arrives().noLaterThan(1).seconds().beforeNext();
+----
+
+[TIP]
+*Time units* +
+In the example above we use `seconds` as the time unit, but Camel offers
+`milliseconds`, and `minutes` as well.
+
+
+[[Mock-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+
+* link:spring-testing.html[Spring Testing]
+* link:testing.html[Testing]
http://git-wip-us.apache.org/repos/asf/camel/blob/9c0b7baf/camel-core/src/main/docs/mock.adoc
----------------------------------------------------------------------
diff --git a/camel-core/src/main/docs/mock.adoc b/camel-core/src/main/docs/mock.adoc
deleted file mode 100644
index b24e634..0000000
--- a/camel-core/src/main/docs/mock.adoc
+++ /dev/null
@@ -1,515 +0,0 @@
-ifdef::env-github[]
-:caution-caption: :boom:
-:important-caption: :exclamation:
-:note-caption: :information_source:
-:tip-caption: :bulb:
-:warning-caption: :warning:
-endif::[]
-
-[[Mock-MockComponent]]
-Mock Component
-~~~~~~~~~~~~~~
-
-link:testing.html[Testing] of distributed and asynchronous processing is
-notoriously difficult. The link:mock.html[Mock], link:test.html[Test]
-and link:dataset.html[DataSet] endpoints work great with the
-link:testing.html[Camel Testing Framework] to simplify your unit and
-integration testing using
-link:enterprise-integration-patterns.html[Enterprise Integration
-Patterns] and Camel's large range of link:components.html[Components]
-together with the powerful link:bean-integration.html[Bean Integration].
-
-The Mock component provides a powerful declarative testing mechanism,
-which is similar to http://www.jmock.org[jMock] in
-that it allows declarative expectations to be created on any Mock
-endpoint before a test begins. Then the test is run, which typically
-fires messages to one or more endpoints, and finally the expectations
-can be asserted in a test case to ensure the system worked as expected.
-
-This allows you to test various things like:
-
-* The correct number of messages are received on each endpoint,
-* The correct payloads are received, in the right order,
-* Messages arrive on an endpoint in order, using some
-link:expression.html[Expression] to create an order testing function,
-* Messages arrive match some kind of link:predicate.html[Predicate] such
-as that specific headers have certain values, or that parts of the
-messages match some predicate, such as by evaluating an
-link:xpath.html[XPath] or link:xquery.html[XQuery]
-link:expression.html[Expression].
-
-[NOTE]
-There is also the link:test.html[Test endpoint] which is a
-Mock endpoint, but which uses a second endpoint to provide the list of
-expected message bodies and automatically sets up the Mock endpoint
-assertions. In other words, it's a Mock endpoint that automatically sets
-up its assertions from some sample messages in a link:file2.html[File]
-or link:jpa.html[database], for example.
-
-[CAUTION]
-*Mock endpoints keep received Exchanges in memory indefinitely.* +
- +
-Remember that Mock is designed for testing. When you add Mock endpoints
-to a route, each link:exchange.html[Exchange] sent to the endpoint will
-be stored (to allow for later validation) in memory until explicitly
-reset or the JVM is restarted. If you are sending high volume and/or
-large messages, this may cause excessive memory use. If your goal is to
-test deployable routes inline, consider using
-link:notifybuilder.html[NotifyBuilder] or
-link:advicewith.html[AdviceWith] in your tests instead of adding Mock
-endpoints to routes directly. +
- +
-From Camel 2.10 onwards there are two new options `retainFirst`, and
-`retainLast` that can be used to limit the number of messages the Mock
-endpoints keep in memory.
-
-
-[[Mock-URIformat]]
-URI format
-^^^^^^^^^^
-
-[source]
-----
-mock:someName[?options]
-----
-
-Where `someName` can be any string that uniquely identifies the
-endpoint.
-
-You can append query options to the URI in the following format,
-`?option=value&option=value&...`
-
-[[Mock-Options]]
-Options
-^^^^^^^
-
-
-
-
-// component options: START
-The Mock component has no options.
-// component options: END
-
-
-
-
-
-
-// endpoint options: START
-The Mock component supports 12 endpoint options which are listed below:
-
-{% raw %}
-[width="100%",cols="2s,1,1m,1m,5",options="header"]
-|=======================================================================
-| Name | Group | Default | Java Type | Description
-| name | producer | | String | *Required* Name of mock endpoint
-| assertPeriod | producer | 0 | long | Sets a grace period after which the mock endpoint will re-assert to ensure the preliminary assertion is still valid. This is used for example to assert that exactly a number of messages arrives. For example if link expectedMessageCount(int) was set to 5 then the assertion is satisfied when 5 or more message arrives. To ensure that exactly 5 messages arrives then you would need to wait a little period to ensure no further message arrives. This is what you can use this link setAssertPeriod(long) method for. By default this period is disabled.
-| expectedCount | producer | -1 | int | Specifies the expected number of message exchanges that should be received by this endpoint. Beware: If you want to expect that 0 messages then take extra care as 0 matches when the tests starts so you need to set a assert period time to let the test run for a while to make sure there are still no messages arrived; for that use link setAssertPeriod(long). An alternative is to use NotifyBuilder and use the notifier to know when Camel is done routing some messages before you call the link assertIsSatisfied() method on the mocks. This allows you to not use a fixed assert period to speedup testing times. If you want to assert that exactly n'th message arrives to this mock endpoint then see also the link setAssertPeriod(long) method for further details.
-| reportGroup | producer | | int | A number that is used to turn on throughput logging based on groups of the size.
-| resultMinimumWaitTime | producer | 0 | long | Sets the minimum expected amount of time (in millis) the link assertIsSatisfied() will wait on a latch until it is satisfied
-| resultWaitTime | producer | 0 | long | Sets the maximum amount of time (in millis) the link assertIsSatisfied() will wait on a latch until it is satisfied
-| retainFirst | producer | -1 | int | Specifies to only retain the first n'th number of received Exchanges. This is used when testing with big data to reduce memory consumption by not storing copies of every Exchange this mock endpoint receives. Important: When using this limitation then the link getReceivedCounter() will still return the actual number of received Exchanges. For example if we have received 5000 Exchanges and have configured to only retain the first 10 Exchanges then the link getReceivedCounter() will still return 5000 but there is only the first 10 Exchanges in the link getExchanges() and link getReceivedExchanges() methods. When using this method then some of the other expectation methods is not supported for example the link expectedBodiesReceived(Object...) sets a expectation on the first number of bodies received. You can configure both link setRetainFirst(int) and link setRetainLast(int) methods to limit both the first and last received.
-| retainLast | producer | -1 | int | Specifies to only retain the last n'th number of received Exchanges. This is used when testing with big data to reduce memory consumption by not storing copies of every Exchange this mock endpoint receives. Important: When using this limitation then the link getReceivedCounter() will still return the actual number of received Exchanges. For example if we have received 5000 Exchanges and have configured to only retain the last 20 Exchanges then the link getReceivedCounter() will still return 5000 but there is only the last 20 Exchanges in the link getExchanges() and link getReceivedExchanges() methods. When using this method then some of the other expectation methods is not supported for example the link expectedBodiesReceived(Object...) sets a expectation on the first number of bodies received. You can configure both link setRetainFirst(int) and link setRetainLast(int) methods to limit both the first and last received.
-| sleepForEmptyTest | producer | 0 | long | Allows a sleep to be specified to wait to check that this endpoint really is empty when link expectedMessageCount(int) is called with zero
-| copyOnExchange | producer (advanced) | true | boolean | Sets whether to make a deep copy of the incoming Exchange when received at this mock endpoint. Is by default true.
-| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange.
-| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
-|=======================================================================
-{% endraw %}
-// endpoint options: END
-
-
-
-[[Mock-SimpleExample]]
-Simple Example
-^^^^^^^^^^^^^^
-
-Here's a simple example of Mock endpoint in use. First, the endpoint is
-resolved on the context. Then we set an expectation, and then, after the
-test has run, we assert that our expectations have been met:
-
-[source,java]
-----
-MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class);
-
-resultEndpoint.expectedMessageCount(2);
-
-// send some messages
-...
-
-// now lets assert that the mock:foo endpoint received 2 messages
-resultEndpoint.assertIsSatisfied();
-----
-
-You typically always call the
-http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#assertIsSatisfied()[`assertIsSatisfied()`]
-method to test that the expectations were met after running a test.
-
-Camel will by default wait 10 seconds when the `assertIsSatisfied()` is
-invoked. This can be configured by setting the
-`setResultWaitTime(millis)` method.
-
-[[Mock-UsingassertPeriod]]
-Using `assertPeriod`
-++++++++++++++++++++
-
-*Available as of Camel 2.7* +
-When the assertion is satisfied then Camel will stop waiting and
-continue from the `assertIsSatisfied` method. That means if a new
-message arrives on the mock endpoint, just a bit later, that arrival
-will not affect the outcome of the assertion. Suppose you do want to
-test that no new messages arrives after a period thereafter, then you
-can do that by setting the `setAssertPeriod` method, for example:
-
-[source,java]
-----
-MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class);
-resultEndpoint.setAssertPeriod(5000);
-resultEndpoint.expectedMessageCount(2);
-
-// send some messages
-...
-
-// now lets assert that the mock:foo endpoint received 2 messages
-resultEndpoint.assertIsSatisfied();
-----
-
-[[Mock-Settingexpectations]]
-Setting expectations
-^^^^^^^^^^^^^^^^^^^^
-
-You can see from the Javadoc of
-http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html[MockEndpoint]
-the various helper methods you can use to set expectations. The main
-methods are as follows:
-
-[width="100%",cols="1m,1",options="header",]
-|=======================================================================
-|Method |Description
-|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedMessageCount(int)[expectedMessageCount(int)]
-|To define the expected message count on the endpoint.
-
-|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedMinimumMessageCount(int)[expectedMinimumMessageCount(int)]
-|To define the minimum number of expected messages on the endpoint.
-
-|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedBodiesReceived(java.lang.Object...)[expectedBodiesReceived(...)]
-|To define the expected bodies that should be received (in order).
-
-|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectedHeaderReceived(java.lang.String,%20java.lang.String)[expectedHeaderReceived(...)]
-|To define the expected header that should be received
-
-|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectsAscending(org.apache.camel.Expression)[expectsAscending(Expression)]
-|To add an expectation that messages are received in order, using the
-given link:expression.html[Expression] to compare messages.
-
-|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectsDescending(org.apache.camel.Expression)[expectsDescending(Expression)]
-|To add an expectation that messages are received in order, using the
-given link:expression.html[Expression] to compare messages.
-
-|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#expectsNoDuplicates(org.apache.camel.Expression)[expectsNoDuplicates(Expression)]
-|To add an expectation that no duplicate messages are received; using an
-link:expression.html[Expression] to calculate a unique identifier for
-each message. This could be something like the `JMSMessageID` if using
-JMS, or some unique reference number within the message.
-|=======================================================================
-
-Here's another example:
-
-[source,java]
-----
-resultEndpoint.expectedBodiesReceived("firstMessageBody", "secondMessageBody", "thirdMessageBody");
-----
-
-[[Mock-Addingexpectationstospecificmessages]]
-Adding expectations to specific messages
-++++++++++++++++++++++++++++++++++++++++
-
-In addition, you can use the
-http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/component/mock/MockEndpoint.html#message(int)[`message(int
-messageIndex)`] method to add assertions about a specific message that is
-received.
-
-For example, to add expectations of the headers or body of the first
-message (using zero-based indexing like `java.util.List`), you can use
-the following code:
-
-[source,java]
-----
-resultEndpoint.message(0).header("foo").isEqualTo("bar");
-----
-
-There are some examples of the Mock endpoint in use in the
-http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/[`camel-core`
-processor tests].
-
-[[Mock-Mockingexistingendpoints]]
-Mocking existing endpoints
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Available as of Camel 2.7*
-
-Camel now allows you to automatically mock existing endpoints in your
-Camel routes.
-
-[NOTE]
-*How it works* +
- +
-*Important:* The endpoints are still in action. +
-What happens differently
-is that a link:mock.html[Mock] endpoint is injected and receives the
-message first and then delegates the message to the target endpoint. You
-can view this as a kind of intercept and delegate or endpoint listener.
-
-Suppose you have the given route below:
-
-[source,java]
-.*Route*
-----
-include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java[tags=route]
-----
-
-You can then use the `adviceWith` feature in Camel to mock all the
-endpoints in a given route from your unit test, as shown below:
-
-[source,java]
-.*`adviceWith` mocking all endpoints*
-----
-include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java[tags=e1]
-----
-
-Notice that the mock endpoints is given the URI `mock:<endpoint>`, for
-example `mock:direct:foo`. Camel logs at `INFO` level the endpoints
-being mocked:
-
-[source]
-----
-INFO Adviced endpoint [direct://foo] with mock endpoint [mock:direct:foo]
-----
-
-[NOTE]
- **Mocked endpoints are without parameters** +
-Endpoints which are mocked will have their parameters stripped off. For
-example the endpoint `log:foo?showAll=true` will be mocked to the
-following endpoint `mock:log:foo`. Notice the parameters have been
-removed.
-
-Its also possible to only mock certain endpoints using a pattern. For
-example to mock all `log` endpoints you do as shown:
-
-[source,java]
-.*`adviceWith` mocking only log endpoints using a pattern*
-----
-include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockEndpointsTest.java[tags=e2]
-----
-
-The pattern supported can be a wildcard or a regular expression. See
-more details about this at link:intercept.html[Intercept] as its the
-same matching function used by Camel.
-
-[NOTE]
-Mind that mocking endpoints causes the messages to be copied when they
-arrive on the mock. +
-That means Camel will use more memory. This may not be suitable when you
-send in a lot of messages.
-
-
-[[Mock-Mockingexistingendpointsusingthecamel-testcomponent]]
-Mocking existing endpoints using the `camel-test` component
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-Instead of using the `adviceWith` to instruct Camel to mock endpoints,
-you can easily enable this behavior when using the `camel-test` Test
-Kit.
-
-The same route can be tested as follows. Notice that we return `"*"`
-from the `isMockEndpoints` method, which tells Camel to mock all
-endpoints.
-
-If you only want to mock all `log` endpoints you can return `"log*"`
-instead.
-
-[source,java]
-.*`isMockEndpoints` using camel-test kit*
-----
-include::../../../../components/camel-test/src/test/java/org/apache/camel/test/patterns/IsMockEndpointsJUnit4Test.java[tags=e1]
-----
-
-
-[[Mock-MockingexistingendpointswithXMLDSL]]
-Mocking existing endpoints with XML DSL
-+++++++++++++++++++++++++++++++++++++++
-
-If you do not use the `camel-test` component for unit testing (as shown
-above) you can use a different approach when using XML files for
-routes. +
-The solution is to create a new XML file used by the unit test and then
-include the intended XML file which has the route you want to test.
-
-Suppose we have the route in the `camel-route.xml` file:
-
-[source,xml]
-.*camel-route.xml*
-----
-include::../../../../components/camel-spring/src/test/resources/org/apache/camel/spring/mock/camel-route.xml[tags=e1]
-----
-
-Then we create a new XML file as follows, where we include the
-`camel-route.xml` file and define a spring bean with the class
-`org.apache.camel.impl.InterceptSendToMockEndpointStrategy` which tells
-Camel to mock all endpoints:
-
-[source,xml]
-.*test-camel-route.xml*
-----
-include::../../../../components/camel-spring/src/test/resources/org/apache/camel/spring/mock/InterceptSendToMockEndpointStrategyTest.xml[tags=e1]
-----
-
-Then in your unit test you load the new XML file
-(`test-camel-route.xml`) instead of `camel-route.xml`.
-
-To only mock all link:log.html[Log] endpoints you can define the pattern
-in the constructor for the bean:
-
-[source,xml]
-----
-<bean id="mockAllEndpoints" class="org.apache.camel.impl.InterceptSendToMockEndpointStrategy">
- <constructor-arg index="0" value="log*"/>
-</bean>
-----
-
-[[Mock-Mockingendpointsandskipsendingtooriginalendpoint]]
-Mocking endpoints and skip sending to original endpoint
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-*Available as of Camel 2.10*
-
-Sometimes you want to easily mock and skip sending to a certain
-endpoints. So the message is detoured and send to the mock endpoint
-only. From Camel 2.10 onwards you can now use the `mockEndpointsAndSkip`
-method using link:advicewith.html[AdviceWith] or the
-https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=Test+Kit&linkCreation=true&fromPageId=52081[Test
-Kit]. The example below will skip sending to the two endpoints
-`"direct:foo"`, and `"direct:bar"`.
-
-[source,java]
-.*adviceWith mock and skip sending to endpoints*
-----
-include::../../test/java/org/apache/camel/processor/interceptor/AdviceWithMockMultipleEndpointsWithSkipTest.java[tags=e1]
-----
-
-The same example using the link:testing.html[Test Kit]
-
-[source,java]
-.*isMockEndpointsAndSkip using camel-test kit*
-----
-include::../../../../components/camel-test/src/test/java/org/apache/camel/test/patterns/IsMockEndpointsAndSkipJUnit4Test.java[tags=e1]
-----
-
-[[Mock-Limitingthenumberofmessagestokeep]]
-Limiting the number of messages to keep
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Available as of Camel 2.10*
-
-The link:mock.html[Mock] endpoints will by default keep a copy of every
-link:exchange.html[Exchange] that it received. So if you test with a lot
-of messages, then it will consume memory. +
-From Camel 2.10 onwards we have introduced two options `retainFirst` and
-`retainLast` that can be used to specify to only keep N'th of the first
-and/or last link:exchange.html[Exchange]s.
-
-For example in the code below, we only want to retain a copy of the
-first 5 and last 5 link:exchange.html[Exchange]s the mock receives.
-
-[source,java]
-----
- MockEndpoint mock = getMockEndpoint("mock:data");
- mock.setRetainFirst(5);
- mock.setRetainLast(5);
- mock.expectedMessageCount(2000);
-
- ...
-
- mock.assertIsSatisfied();
-----
-
-Using this has some limitations. The `getExchanges()` and
-`getReceivedExchanges()` methods on the `MockEndpoint` will return only
-the retained copies of the link:exchange.html[Exchange]s. So in the
-example above, the list will contain 10 link:exchange.html[Exchange]s;
-the first five, and the last five. +
-The `retainFirst` and `retainLast` options also have limitations on
-which expectation methods you can use. For example the `expectedXXX`
-methods that work on message bodies, headers, etc. will only operate on
-the retained messages. In the example above they can test only the
-expectations on the 10 retained messages.
-
-[[Mock-Testingwitharrivaltimes]]
-Testing with arrival times
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Available as of Camel 2.7*
-
-The link:mock.html[Mock] endpoint stores the arrival time of the message
-as a property on the link:exchange.html[Exchange].
-
-[source,java]
-----
-Date time = exchange.getProperty(Exchange.RECEIVED_TIMESTAMP, Date.class);
-----
-
-You can use this information to know when the message arrived on the
-mock. But it also provides foundation to know the time interval between
-the previous and next message arrived on the mock. You can use this to
-set expectations using the `arrives` DSL on the link:mock.html[Mock]
-endpoint.
-
-For example to say that the first message should arrive between 0-2
-seconds before the next you can do:
-
-[source,java]
-----
-mock.message(0).arrives().noLaterThan(2).seconds().beforeNext();
-----
-
-You can also define this as that 2nd message (0 index based) should
-arrive no later than 0-2 seconds after the previous:
-
-[source,java]
-----
-mock.message(1).arrives().noLaterThan(2).seconds().afterPrevious();
-----
-
-You can also use between to set a lower bound. For example suppose that
-it should be between 1-4 seconds:
-
-[source,java]
-----
-mock.message(1).arrives().between(1, 4).seconds().afterPrevious();
-----
-
-You can also set the expectation on all messages, for example to say
-that the gap between them should be at most 1 second:
-
-[source,java]
-----
-mock.allMessages().arrives().noLaterThan(1).seconds().beforeNext();
-----
-
-[TIP]
-*Time units* +
-In the example above we use `seconds` as the time unit, but Camel offers
-`milliseconds`, and `minutes` as well.
-
-
-[[Mock-SeeAlso]]
-See Also
-^^^^^^^^
-
-* link:configuring-camel.html[Configuring Camel]
-* link:component.html[Component]
-* link:endpoint.html[Endpoint]
-* link:getting-started.html[Getting Started]
-
-* link:spring-testing.html[Spring Testing]
-* link:testing.html[Testing]