This closes #2871

docs/user-manual/en/SUMMARY.md

@@ -56,6 +56,7 @@
 * [Client Reconnection and Session Reattachment](client-reconnection.md)
 * [Diverting and Splitting Message Flows](diverts.md)
 * [Core Bridges](core-bridges.md)
+* [Transformers](transformers.md)
 * [Duplicate Message Detection](duplicate-detection.md)
 * [Clusters](clusters.md)
 * [Federation](federation.md)

docs/user-manual/en/core-bridges.md

@@ -93,13 +93,10 @@ Let's take a look at all the parameters in turn:
   string will be forwarded. The filter string follows the ActiveMQ Artemis filter
   expression syntax described in [Filter Expressions](filter-expressions.md).
 
-- `transformer-class-name`. An optional transformer-class-name can be
+- `transformer-class-name`. An *optional* transformer can be specified. This
-  specified. This is the name of a user-defined class which implements the
+  gives you the opportunity to transform the message's header or body before
-  `org.apache.activemq.artemis.core.server.transformer.Transformer` interface.
+  forwarding it. See the [transformer chapter](transformers.md) for more details
-
+  about transformer-specific configuration.
-  If this is specified then the transformer's `transform()` method will be
-  invoked with the message before it is forwarded. This gives you the opportunity
-  to transform the message's header or body before forwarding it.
 
 - `ha`. This optional parameter determines whether or not this bridge should
   support high availability. True means it will connect to any available server

docs/user-manual/en/diverts.md

@@ -31,12 +31,12 @@ vice-versa. By configuring the `routing-type` of the divert you have the
 flexibility to deal with any situation. Valid values are `ANYCAST`,
 `MULTICAST`, `PASS`, & `STRIP`. The default is `STRIP`.
 
-Diverts can also be configured to apply a `Transformer`. If specified,
+Diverts can also be configured to apply a [`Transformer`](transformers.md).
-all diverted messages will have the opportunity of being transformed by
+If specified, all diverted messages will have the opportunity of being
-the `Transformer`. When an address has multiple diverts configured, all
+transformed by the `Transformer`. When an address has multiple diverts
-of them receive the same, original message. This means that the results
+configured, all of them receive the same, original message. This means that
-of a transformer on a message are not directly available for other
+the results of a transformer on a message are not directly available for
-diverts or their filters on the same address.
+other diverts or their filters on the same address.
 
 See the documentation on [adding runtime dependencies](using-server.md) to 
 understand how to make your transformer available to the broker.
@@ -100,16 +100,18 @@ other messages will continue to be routed to the normal address. The
 filter string is optional, if not specified then all messages will be
 considered matched.
 
-In this example a transformer class is specified. Again this is
+In this example a transformer class is specified without any configuration
-optional, and if specified the transformer will be executed for each
+properties. Again this is optional, and if specified the transformer will
-matching message. This allows you to change the messages body or
+be executed for each matching message. This allows you to change the
-properties before it is diverted. In this example the transformer simply
+messages body or properties before it is diverted. In this example the
-adds a header that records the time the divert happened.
+transformer simply adds a header that records the time the divert happened.
+See the [transformer chapter](transformers.md) for more details about
+transformer-specific configuration.
 
 This example is actually diverting messages to a local store and forward
 queue, which is configured with a bridge which forwards the message to
-an address on another ActiveMQ Artemis server. Please see the example for more
+an address on another ActiveMQ Artemis server. Please see the example for
-details.
+more details.
 
 ## Non-exclusive Divert
 

docs/user-manual/en/transformers.md

@@ -0,0 +1,50 @@
+# Transformers
+
+A transfomer, as the name suggests, is a component which transforms a message.
+For example, a transformer could modify the body of a message or add or remove
+properties. Both [diverts](diverts.md) and [core bridges](core-bridges.md)
+support.
+
+A transformer is simply a class which implements the interface
+`org.apache.activemq.artemis.core.server.transformer.Transformer`:
+
+```java
+public interface Transformer {
+
+   default void init(Map<String, String> properties) { }
+
+   Message transform(Message message);
+}
+```
+
+The `init` method is called immediately after the broker instantiates the class.
+There is a default method implementation so implementing `init` is optional.
+However, if the transformer needs any configuration properties it should
+implement `init` and the broker will pass the configured key/value pairs to the
+transformer using a `java.util.Map`.
+
+## Configuration
+
+The most basic configuration requires only specifying the transformer's class
+name, e.g.:
+
+```xml
+<transformer-class-name>
+   org.foo.MyTransformer
+</transformer-class-name>
+```
+
+However, if the transformer needs any configuration properties those can be
+specified using a slightly different syntax, e.g.:
+
+```xml
+<transformer>
+   <class-name>org.foo.MyTransformerWithProperties</class-name>
+   <property key="transformerKey1" value="transformerValue1"/>
+   <property key="transformerKey2" value="transformerValue2"/>
+</transformer>
+```
+
+Any transformer implementation needs to be added to the broker's classpath. See
+the documentation on [adding runtime dependencies](using-server.md#adding-runtime-dependencies)
+to understand how to make your transformer available to the broker.