From c9f5608ef9b20436688b267dbed09023e46f1022 Mon Sep 17 00:00:00 2001 From: Justin Bertram Date: Fri, 25 Oct 2019 11:56:40 -0500 Subject: [PATCH] NO-JIRA improve transformer docs --- docs/user-manual/en/SUMMARY.md | 1 + docs/user-manual/en/core-bridges.md | 11 +++---- docs/user-manual/en/diverts.md | 28 ++++++++-------- docs/user-manual/en/transformers.md | 50 +++++++++++++++++++++++++++++ 4 files changed, 70 insertions(+), 20 deletions(-) create mode 100644 docs/user-manual/en/transformers.md diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 5f14233078..d259f18c92 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/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) diff --git a/docs/user-manual/en/core-bridges.md b/docs/user-manual/en/core-bridges.md index 2e488da33f..abfee34cda 100644 --- a/docs/user-manual/en/core-bridges.md +++ b/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 - specified. This is the name of a user-defined class which implements the - `org.apache.activemq.artemis.core.server.transformer.Transformer` interface. - - 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. +- `transformer-class-name`. An *optional* transformer can be specified. This + gives you the opportunity to transform the message's header or body before + forwarding it. See the [transformer chapter](transformers.md) for more details + about transformer-specific configuration. - `ha`. This optional parameter determines whether or not this bridge should support high availability. True means it will connect to any available server diff --git a/docs/user-manual/en/diverts.md b/docs/user-manual/en/diverts.md index aa78980b69..a75370773a 100644 --- a/docs/user-manual/en/diverts.md +++ b/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, -all diverted messages will have the opportunity of being transformed by -the `Transformer`. When an address has multiple diverts configured, all -of them receive the same, original message. This means that the results -of a transformer on a message are not directly available for other -diverts or their filters on the same address. +Diverts can also be configured to apply a [`Transformer`](transformers.md). +If specified, all diverted messages will have the opportunity of being +transformed by the `Transformer`. When an address has multiple diverts +configured, all of them receive the same, original message. This means that +the results of a transformer on a message are not directly available for +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 -optional, and if specified the transformer will be executed for each -matching message. This allows you to change the messages body or -properties before it is diverted. In this example the transformer simply -adds a header that records the time the divert happened. +In this example a transformer class is specified without any configuration +properties. Again this is optional, and if specified the transformer will +be executed for each matching message. This allows you to change the +messages body or properties before it is diverted. In this example the +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 -details. +an address on another ActiveMQ Artemis server. Please see the example for +more details. ## Non-exclusive Divert diff --git a/docs/user-manual/en/transformers.md b/docs/user-manual/en/transformers.md new file mode 100644 index 0000000000..fbe5ad95fa --- /dev/null +++ b/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 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 + + org.foo.MyTransformer + +``` + +However, if the transformer needs any configuration properties those can be +specified using a slightly different syntax, e.g.: + +```xml + + org.foo.MyTransformerWithProperties + + + +``` + +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. \ No newline at end of file