diff --git a/.gitignore b/.gitignore index 9661e9c66e..3727d4590b 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ ratReport.txt .factorypath **/.editorconfig **/derby.log +examples/**/readme.html # for native build CMakeCache.txt diff --git a/artemis-distribution/src/main/assembly/dep.xml b/artemis-distribution/src/main/assembly/dep.xml index 229017fcc1..66705828ac 100644 --- a/artemis-distribution/src/main/assembly/dep.xml +++ b/artemis-distribution/src/main/assembly/dep.xml @@ -220,6 +220,7 @@ **/target/** **/**/*.iml **/**/*.dat + **/**/*.md diff --git a/examples/common/footer.html b/examples/common/footer.html new file mode 100644 index 0000000000..691287b6e3 --- /dev/null +++ b/examples/common/footer.html @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/examples/protocols/openwire/message-recovery/readme.html b/examples/common/header.html similarity index 72% rename from examples/protocols/openwire/message-recovery/readme.html rename to examples/common/header.html index 2bb884f0fc..f2229f5fe2 100644 --- a/examples/protocols/openwire/message-recovery/readme.html +++ b/examples/common/header.html @@ -18,18 +18,10 @@ under the License. --> - - ActiveMQ Artemis JMS Queue Example + + ActiveMQ Artemis Example - - -

JMS Queue Message Listener for openwire

- - 
This example will start and stop the server within the example.
- -

This example shows how to use send messages to a queue, and having these messages recovered from the journal.

- - - + + diff --git a/examples/features/clustered/client-side-load-balancing/pom.xml b/examples/features/clustered/client-side-load-balancing/pom.xml index 14b87158c3..b3523211e9 100644 --- a/examples/features/clustered/client-side-load-balancing/pom.xml +++ b/examples/features/clustered/client-side-load-balancing/pom.xml @@ -197,7 +197,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/clustered/client-side-load-balancing/readme.html b/examples/features/clustered/client-side-load-balancing/readme.html deleted file mode 100644 index 9d3aba5165..0000000000 --- a/examples/features/clustered/client-side-load-balancing/readme.html +++ /dev/null @@ -1,49 +0,0 @@ - - - - - ActiveMQ Artemis JMS Client-Side Load-Balancing Example - - - - - -

JMS Client-Side Load-Balancing Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates how connnections created from a single JMS Connection factory can be created - to different nodes of the cluster. In other words it demonstrates how ActiveMQ Artemis does client side load balancing of - connections across the cluster.

-

The particular load-balancing policy can be chosen to be random, round-robin or user-defined. Please see the user - guide for more details of how to configure the specific load-balancing policy. In this example we will use - the default round-robin load balancing policy.

-

The list of servers over which ActiveMQ Artemis will round-robin the connections can either be specified explicitly - in the connection factory when instantiating it directly, when configuring it on the server or configured - to use UDP discovery to discover the list of servers over which to round-robin. This example will use UDP - discovery to obtain the list.

-

This example starts three servers which all broadcast their location using UDP discovery. The UDP broadcast configuration - can be seen in the broker.xml file.

-

A JMS ConnectionFactory is deployed on each server specifying the discovery group that will be used by that - connection factory.

-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - - diff --git a/examples/features/clustered/client-side-load-balancing/readme.md b/examples/features/clustered/client-side-load-balancing/readme.md new file mode 100644 index 0000000000..6b66fbd4e6 --- /dev/null +++ b/examples/features/clustered/client-side-load-balancing/readme.md @@ -0,0 +1,15 @@ +# JMS Client-Side Load-Balancing Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to create and start the broker manually. + +This example demonstrates how connections created from a single JMS Connection factory can be created to different nodes of the cluster. In other words it demonstrates how ActiveMQ Artemis does **client side load balancing** of connections across the cluster. + +The particular load-balancing policy can be chosen to be random, round-robin or user-defined. Please see the user guide for more details of how to configure the specific load-balancing policy. In this example we will use the default round-robin load balancing policy. + +The list of servers over which ActiveMQ Artemis will round-robin the connections can either be specified explicitly in the connection factory when instantiating it directly, when configuring it on the broker or configured to use UDP discovery to discover the list of servers over which to round-robin. This example will use UDP discovery to obtain the list. + +This example starts three servers which all broadcast their location using UDP discovery. The UDP broadcast configuration can be seen in the `broker.xml` file. + +A JMS ConnectionFactory is deployed on each broker specifying the discovery group that will be used by that connection factory. + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-durable-subscription/pom.xml b/examples/features/clustered/clustered-durable-subscription/pom.xml index 4dfdb3deaa..3a2b628cfd 100644 --- a/examples/features/clustered/clustered-durable-subscription/pom.xml +++ b/examples/features/clustered/clustered-durable-subscription/pom.xml @@ -155,7 +155,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-durable-subscription/readme.html b/examples/features/clustered/clustered-durable-subscription/readme.html deleted file mode 100644 index c0a7b2ec82..0000000000 --- a/examples/features/clustered/clustered-durable-subscription/readme.html +++ /dev/null @@ -1,65 +0,0 @@ - - - - - ActiveMQ Artemis JMS Durable Subscription Example - - - - - -

JMS Durable Subscription Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a clustered JMS durable subscription. - Normally durable subscriptions exist on a single node and can only have one subscriber at any one time, - however, with ActiveMQ Artemis it's possible to create durable subscription instances with the same name and client-id - on different nodes of the cluster, and consume from them simultaneously. - This allows the work of processing messages from a durable subscription to be spread across the cluster in - a similar way to how JMS Queues can be load balanced across the cluster -

-

In this example we first configure the two nodes to form a cluster, then we then create a durable subscriber - with the same name and client-id on both nodes, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that the messages are round robin'd between - the two subscription instances. Note that each durable subscription instance with the same name and client-id - does not receive its own copy of the messages. This is because the instances on different nodes form a - single "logical" durable subscription, in the same way multiple JMS Queue instances on different nodes - form a single "local" JMS Queue

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly. -

Here's the relevant snippet from the server configuration, which tells the server to form a cluster between the two nodes - and to load balance the messages between the nodes.

-

The cli create method will define this section by default if you use --clustered as a parameter

- 
-     <cluster-connection name="my-cluster">
-        <retry-interval>500</retry-interval>
-        <use-duplicate-detection>true</use-duplicate-detection>
-        <message-load-balancing>STRICT</message-load-balancing>
-        <max-hops>1</max-hops>
-        <discovery-group-ref discovery-group-name="my-discovery-group"/>
-     </cluster-connection>
-     
-
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - - diff --git a/examples/features/clustered/clustered-durable-subscription/readme.md b/examples/features/clustered/clustered-durable-subscription/readme.md new file mode 100644 index 0000000000..dd82ec7d76 --- /dev/null +++ b/examples/features/clustered/clustered-durable-subscription/readme.md @@ -0,0 +1,25 @@ +# JMS Clustered Durable Subscription Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a clustered JMS durable subscription. Normally durable subscriptions exist on a single node and can only have one subscriber at any one time, however, with ActiveMQ Artemis it's possible to create durable subscription instances with the same name and client-id on different nodes of the cluster, and consume from them simultaneously. This allows the work of processing messages from a durable subscription to be spread across the cluster in a similar way to how JMS Queues can be load balanced across the cluster + +In this example we first configure the two nodes to form a cluster, then we then create a durable subscriber with the same name and client-id on both nodes, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that the messages are round robin'd between the two subscription instances. Note that each durable subscription instance with the same name and client-id **does not** receive its own copy of the messages. This is because the instances on different nodes form a single "logical" durable subscription, in the same way multiple JMS Queue instances on different nodes form a single "local" JMS Queue + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a cluster between the two nodes and to load balance the messages between the nodes. + +The cli create method will define a similar section by default if you use `--clustered` as a parameter + + + 500 + true + STRICT + 1 + + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the "Clusters" chapter of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server0/broker.xml index 42464b598c..4b86dadbe4 100644 --- a/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server1/broker.xml index 969a7a2a8c..e22a8ceefc 100644 --- a/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-durable-subscription/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-grouping/pom.xml b/examples/features/clustered/clustered-grouping/pom.xml index 61293f980d..aa02e52824 100644 --- a/examples/features/clustered/clustered-grouping/pom.xml +++ b/examples/features/clustered/clustered-grouping/pom.xml @@ -29,7 +29,7 @@ under the License. clustered-grouping jar - ActiveMQ Artemis JMS CLustered Grouping Example + ActiveMQ Artemis JMS Clustered Grouping Example ${project.basedir}/../../../.. @@ -193,7 +193,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-grouping/readme.html b/examples/features/clustered/clustered-grouping/readme.html deleted file mode 100644 index e066ca948a..0000000000 --- a/examples/features/clustered/clustered-grouping/readme.html +++ /dev/null @@ -1,79 +0,0 @@ - - - - - ActiveMQ Artemis JMS Clustered Grouping Example - - - -

JMS Clustered Grouping Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates how to ensure strict ordering across a cluster using clustered message grouping

-

We create 3 nodes each with a grouping message handler, one with a Local handler and 2 with a Remote handler.

-

The local handler acts as an arbitrator for the 2 remote handlers, holding the information on routes and communicating - the routing info with the remote handlers on the other 2 nodes

-

We then send some messages to each node with the same group id set and ensure the same consumer receives all of them

-

Here's the relevant snippet from the server configuration that has the local handler

- 
-     
-       <cluster-connections>
-          <cluster-connection name="my-cluster">
-             <connector-ref>netty-connector</connector-ref>
-             <retry-interval>500</retry-interval>
-             <use-duplicate-detection>true</use-duplicate-detection>
-             <message-load-balancing>STRICT</message-load-balancing>
-             <max-hops>1</max-hops>
-             <discovery-group-ref discovery-group-name="my-discovery-group"/>
-          </cluster-connection>
-       </cluster-connections>
-
-       <grouping-handler name="my-grouping-handler">
-          <type>LOCAL</type>
-          <address>jms</address>
-          <timeout>5000</timeout>
-       </grouping-handler>
-     
-
- -

Here's the relevant snippet from the server configuration that has the remote handlers

- 
-     
-       <cluster-connections>
-          <cluster-connection name="my-cluster">
-             <retry-interval>500</retry-interval>
-             <use-duplicate-detection>true</use-duplicate-detection>
-             <message-load-balancing>STRICT</message-load-balancing>
-             <max-hops>1</max-hops>
-             <discovery-group-ref discovery-group-name="my-discovery-group"/>
-          </cluster-connection>
-       </cluster-connections>
-
-       <grouping-handler name="my-grouping-handler">
-          <type>REMOTE</type>
-          <address>jms</address>
-          <timeout>5000</timeout>
-       </grouping-handler>
-     
-
- - - diff --git a/examples/features/clustered/clustered-grouping/readme.md b/examples/features/clustered/clustered-grouping/readme.md new file mode 100644 index 0000000000..e8eb9d05e8 --- /dev/null +++ b/examples/features/clustered/clustered-grouping/readme.md @@ -0,0 +1,48 @@ +# JMS Clustered Grouping Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates how to ensure strict ordering across a cluster using clustered message grouping + +We create 3 nodes each with a grouping message handler, one with a Local handler and 2 with a Remote handler. + +The local handler acts as an arbitrator for the 2 remote handlers, holding the information on routes and communicating the routing info with the remote handlers on the other 2 nodes + +We then send some messages to each node with the same group id set and ensure the same consumer receives all of them + +Here's the relevant snippet from the broker configuration that has the local handler + + + + netty-connector + 500 + true + STRICT + 1 + + + + + + LOCAL +
jms
+ 5000 + + +Here's the relevant snippet from the broker configuration that has the remote handlers + + + + 500 + true + STRICT + 1 + + + + + + REMOTE +
jms
+ 5000 + \ No newline at end of file diff --git a/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server0/broker.xml index 26c84677d4..9ee69f5846 100644 --- a/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -93,7 +91,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server1/broker.xml index 3641e8e71b..fa926f7b71 100644 --- a/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -90,7 +88,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server2/broker.xml b/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server2/broker.xml index 864c240925..e0494d8165 100644 --- a/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server2/broker.xml +++ b/examples/features/clustered/clustered-grouping/src/main/resources/activemq/server2/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -90,7 +88,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-jgroups/pom.xml b/examples/features/clustered/clustered-jgroups/pom.xml index 8a8a1c2817..1e0c6eb071 100644 --- a/examples/features/clustered/clustered-jgroups/pom.xml +++ b/examples/features/clustered/clustered-jgroups/pom.xml @@ -158,7 +158,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/clustered/clustered-jgroups/readme.html b/examples/features/clustered/clustered-jgroups/readme.html deleted file mode 100644 index 27319977ca..0000000000 --- a/examples/features/clustered/clustered-jgroups/readme.html +++ /dev/null @@ -1,67 +0,0 @@ - - - - - ActiveMQ Artemis Clustering with JGroups Example - - - - - -

ActiveMQ Artemis Clustering with JGroups Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates the working of a two node cluster using JGroups as the underlying topology broadcasting/discovery - technique.

-

We deploy a queue on to the cluster, then create a consumer on the queue on each node, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that both consumers receive the sent messages - in a round-robin fashion.

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly.

-

To enable ActiveMQ Artemis to use JGroups you need to configure JGroups configuration file and make sure it is on the classpath - by placing in the configuration directory, the file test-jgroups-file_ping.xml is the configuration used in this - exaample

-

You then configure the jgroups file used by the broadcast and discovery groups in the configuration along with the - channel name which you want this cluster to share.

- 
-     
-   <broadcast-groups>
-      <broadcast-group name="my-broadcast-group">
-         <broadcast-period>5000</broadcast-period>
-         <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
-         <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
-         <connector-ref>netty-connector</connector-ref>
-      </broadcast-group>
-   </broadcast-groups>
-
-   <discovery-groups>
-      <discovery-group name="my-discovery-group">
-         <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
-         <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
-         <refresh-timeout>10000</refresh-timeout>
-      </discovery-group>
-   </discovery-groups>
-     
-
-

For more information on ActiveMQ Artemis clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/clustered-jgroups/readme.md b/examples/features/clustered/clustered-jgroups/readme.md new file mode 100644 index 0000000000..9783268390 --- /dev/null +++ b/examples/features/clustered/clustered-jgroups/readme.md @@ -0,0 +1,34 @@ +# ActiveMQ Artemis Clustering with JGroups Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates the working of a two node cluster using JGroups as the underlying topology broadcasting/discovery technique. + +We deploy a queue on to the cluster, then create a consumer on the queue on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **both** consumers receive the sent messages in a round-robin fashion. + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +To enable ActiveMQ Artemis to use JGroups you need to configure JGroups configuration file and make sure it is on the classpath by placing in the configuration directory, the file test-jgroups-file_ping.xml is the configuration used in this exaample + +You then configure the jgroups file used by the broadcast and discovery groups in the configuration along with the channel name which you want this cluster to share. + + + + 5000 + test-jgroups-file_ping.xml + activemq_broadcast_channel + netty-connector + + + + + + test-jgroups-file_ping.xml + activemq_broadcast_channel + 10000 + + + +For more information on ActiveMQ Artemis clustering in general, please see the "Clusters" chapter of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server0/broker.xml index cc82b8ead3..5bb1234795 100644 --- a/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -85,7 +83,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server1/broker.xml index 8b65e68052..55310622f5 100644 --- a/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-jgroups/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-queue/pom.xml b/examples/features/clustered/clustered-queue/pom.xml index 5f1f0edbfd..5953992726 100644 --- a/examples/features/clustered/clustered-queue/pom.xml +++ b/examples/features/clustered/clustered-queue/pom.xml @@ -151,7 +151,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-queue/readme.html b/examples/features/clustered/clustered-queue/readme.html deleted file mode 100644 index a39fc4c6b4..0000000000 --- a/examples/features/clustered/clustered-queue/readme.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - ActiveMQ Artemis JMS Load Balanced Clustered Queue Example - - - - - -

JMS Load Balanced Clustered Queue Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster.

-

We then create a consumer on the queue on each node, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that both consumers receive the sent messages - in a round-robin fashion.

-

In other words, ActiveMQ Artemis load balances the sent messages across all consumers on the cluster

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly.

-

Here's the relevant snippet from the server configuration, which tells the server to form a cluster between the two nodes - and to load balance the messages between the nodes.

- 
-     <cluster-connection name="my-cluster">
-        <connector-ref>netty-connector</connector-ref>
-        <retry-interval>500</retry-interval>
-        <use-duplicate-detection>true</use-duplicate-detection>
-        <message-load-balancing>STRICT</message-load-balancing>
-        <max-hops>1</max-hops>
-        <discovery-group-ref discovery-group-name="my-discovery-group"/>
-     </cluster-connection>
-     
-
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/clustered-queue/readme.md b/examples/features/clustered/clustered-queue/readme.md new file mode 100644 index 0000000000..769ce8b792 --- /dev/null +++ b/examples/features/clustered/clustered-queue/readme.md @@ -0,0 +1,26 @@ +# JMS Load Balanced Clustered Queue Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster. + +We then create a consumer on the queue on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **both** consumers receive the sent messages in a round-robin fashion. + +In other words, ActiveMQ Artemis **load balances** the sent messages across all consumers on the cluster + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a cluster between the two nodes and to load balance the messages between the nodes. + + + netty-connector + 500 + true + STRICT + 1 + + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-queue/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-queue/src/main/resources/activemq/server0/broker.xml index cee673a5f3..452ad362de 100644 --- a/examples/features/clustered/clustered-queue/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-queue/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -83,7 +81,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-queue/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-queue/src/main/resources/activemq/server1/broker.xml index de6f9e6482..5bfc79fec3 100644 --- a/examples/features/clustered/clustered-queue/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-queue/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-static-discovery-uri/pom.xml b/examples/features/clustered/clustered-static-discovery-uri/pom.xml index bc921cbebd..68e82db405 100644 --- a/examples/features/clustered/clustered-static-discovery-uri/pom.xml +++ b/examples/features/clustered/clustered-static-discovery-uri/pom.xml @@ -238,7 +238,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-static-discovery-uri/readme.html b/examples/features/clustered/clustered-static-discovery-uri/readme.html deleted file mode 100644 index 0dc1205b56..0000000000 --- a/examples/features/clustered/clustered-static-discovery-uri/readme.html +++ /dev/null @@ -1,57 +0,0 @@ - - - - - ActiveMQ Artemis JMS Load Balanced Static Clustered Queue Example - - - - - -

JMS Load Balanced Static Clustered Queue Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster - from a static list of nodes.

-

We then create a consumer on the queue on each node, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that both consumers receive the sent messages - in a round-robin fashion.

-

In other words, ActiveMQ Artemis load balances the sent messages across all consumers on the cluster

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly.

-

Here's the relevant snippet from the server configuration, which tells the server to form a cluster between the two nodes - and to load balance the messages between the nodes.

- 
-     <cluster-connection name="my-cluster">
-        <connector-ref>netty-connector</connector-ref>
-        <retry-interval>500</retry-interval>
-        <use-duplicate-detection>true</use-duplicate-detection>
-        <message-load-balancing>STRICT</message-load-balancing>
-        <max-hops>1</max-hops>
-        <static-connectors>
-           <connector-ref>server1-connector</connector-ref>
-        </static-connectors>
-     </cluster-connection>
-     
-
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/clustered-static-discovery-uri/readme.md b/examples/features/clustered/clustered-static-discovery-uri/readme.md new file mode 100644 index 0000000000..d2f9ca1ecc --- /dev/null +++ b/examples/features/clustered/clustered-static-discovery-uri/readme.md @@ -0,0 +1,28 @@ +# JMS Load Balanced Static Clustered Queue Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster from a _static_ list of nodes. + +We then create a consumer on the queue on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **both** consumers receive the sent messages in a round-robin fashion. + +In other words, ActiveMQ Artemis **load balances** the sent messages across all consumers on the cluster + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a cluster between the two nodes and to load balance the messages between the nodes. + + + netty-connector + 500 + true + STRICT + 1 + + server1-connector + + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server0/broker.xml index 07ee7958c5..9bb273da7b 100644 --- a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -59,7 +57,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server1/broker.xml index a3b1b3ec6b..9e335d6ac3 100644 --- a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -59,7 +57,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server2/broker.xml b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server2/broker.xml index 9ef613824c..e49293437c 100644 --- a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server2/broker.xml +++ b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server2/broker.xml @@ -14,10 +14,8 @@ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. - --> - - - + --> + ./data/bindings @@ -56,7 +54,7 @@ - +
diff --git a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server3/broker.xml b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server3/broker.xml index 6049674432..915c5c825c 100644 --- a/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server3/broker.xml +++ b/examples/features/clustered/clustered-static-discovery-uri/src/main/resources/activemq/server3/broker.xml @@ -14,10 +14,8 @@ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. - --> - - - + --> + ./data/bindings @@ -57,7 +55,7 @@ - +
diff --git a/examples/features/clustered/clustered-static-discovery/pom.xml b/examples/features/clustered/clustered-static-discovery/pom.xml index ff1cafc0da..43a1151c6b 100644 --- a/examples/features/clustered/clustered-static-discovery/pom.xml +++ b/examples/features/clustered/clustered-static-discovery/pom.xml @@ -238,7 +238,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-static-discovery/readme.html b/examples/features/clustered/clustered-static-discovery/readme.html deleted file mode 100644 index 0dc1205b56..0000000000 --- a/examples/features/clustered/clustered-static-discovery/readme.html +++ /dev/null @@ -1,57 +0,0 @@ - - - - - ActiveMQ Artemis JMS Load Balanced Static Clustered Queue Example - - - - - -

JMS Load Balanced Static Clustered Queue Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster - from a static list of nodes.

-

We then create a consumer on the queue on each node, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that both consumers receive the sent messages - in a round-robin fashion.

-

In other words, ActiveMQ Artemis load balances the sent messages across all consumers on the cluster

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly.

-

Here's the relevant snippet from the server configuration, which tells the server to form a cluster between the two nodes - and to load balance the messages between the nodes.

- 
-     <cluster-connection name="my-cluster">
-        <connector-ref>netty-connector</connector-ref>
-        <retry-interval>500</retry-interval>
-        <use-duplicate-detection>true</use-duplicate-detection>
-        <message-load-balancing>STRICT</message-load-balancing>
-        <max-hops>1</max-hops>
-        <static-connectors>
-           <connector-ref>server1-connector</connector-ref>
-        </static-connectors>
-     </cluster-connection>
-     
-
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/clustered-static-discovery/readme.md b/examples/features/clustered/clustered-static-discovery/readme.md new file mode 100644 index 0000000000..d2f9ca1ecc --- /dev/null +++ b/examples/features/clustered/clustered-static-discovery/readme.md @@ -0,0 +1,28 @@ +# JMS Load Balanced Static Clustered Queue Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster from a _static_ list of nodes. + +We then create a consumer on the queue on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **both** consumers receive the sent messages in a round-robin fashion. + +In other words, ActiveMQ Artemis **load balances** the sent messages across all consumers on the cluster + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a cluster between the two nodes and to load balance the messages between the nodes. + + + netty-connector + 500 + true + STRICT + 1 + + server1-connector + + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server0/broker.xml index e66abf18ae..3d55545a89 100644 --- a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -70,7 +68,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server1/broker.xml index ed89dab2e9..c1fcaa7579 100644 --- a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -70,7 +68,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server2/broker.xml b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server2/broker.xml index a4fd583fb3..d88570e2ff 100644 --- a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server2/broker.xml +++ b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server2/broker.xml @@ -14,10 +14,8 @@ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. - --> - - - + --> + ./data/bindings @@ -68,7 +66,7 @@ - +
diff --git a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server3/broker.xml b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server3/broker.xml index 4c07def60b..6757e56783 100644 --- a/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server3/broker.xml +++ b/examples/features/clustered/clustered-static-discovery/src/main/resources/activemq/server3/broker.xml @@ -14,10 +14,8 @@ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. - --> - - - + --> + ./data/bindings @@ -68,7 +66,7 @@ - +
diff --git a/examples/features/clustered/clustered-static-oneway/pom.xml b/examples/features/clustered/clustered-static-oneway/pom.xml index c77f0498c3..74b9bbe22f 100644 --- a/examples/features/clustered/clustered-static-oneway/pom.xml +++ b/examples/features/clustered/clustered-static-oneway/pom.xml @@ -198,6 +198,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-static-oneway/readme.html b/examples/features/clustered/clustered-static-oneway/readme.html deleted file mode 100644 index e7fb9354a3..0000000000 --- a/examples/features/clustered/clustered-static-oneway/readme.html +++ /dev/null @@ -1,63 +0,0 @@ - - - - - ActiveMQ Artemis JMS Load Balanced Static Clustered Queue Example - - - - - -

JMS Load Balanced Static Clustered One Way Queue Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a JMS queue deployed on three different nodes. The three nodes are configured to form a one way cluster - from a static list of nodes.

-

A one way cluster is different from a symmetrical cluster in that each node is only connected to one another node in - a chain type fashion, so server 0 -> server 1 -> server 2

-

We then create a consumer on the queue on each node, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that all consumers receive the sent messages - in a round-robin fashion.

-

In other words, ActiveMQ Artemis load balances the sent messages across all consumers on the cluster

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly.

-

Here's the relevant snippet from the server configuration, which tells the server to form a one way cluster between the three nodes - and to load balance the messages between the nodes. Note that we have set allow-direct-connections-only to true, - this means that this server will only ever connect the address's specified in the list of connectors. ALso notice - that max-hops is 2, this is because server 0 is not directly connected to server 2, 2 hops in fact, so we - allow any updates from servers up to 2 hops away

- 
-     
-     <cluster-connection name="my-cluster">
-        <connector-ref>netty-connector</connector-ref>
-        <retry-interval>500</retry-interval>
-        <use-duplicate-detection>true</use-duplicate-detection>
-        <message-load-balancing>STRICT</message-load-balancing>
-        <max-hops>2</max-hops>
-        <static-connectors allow-direct-connections-only="true">
-            <connector-ref>server1-connector</connector-ref>
-         </static-connectors>
-     </cluster-connection>
-     
-
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/clustered-static-oneway/readme.md b/examples/features/clustered/clustered-static-oneway/readme.md new file mode 100644 index 0000000000..a6c2faad23 --- /dev/null +++ b/examples/features/clustered/clustered-static-oneway/readme.md @@ -0,0 +1,30 @@ +# JMS Load Balanced Static Clustered One Way Queue Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a JMS queue deployed on three different nodes. The three nodes are configured to form a one way cluster from a _static_ list of nodes. + +A one way cluster is different from a symmetrical cluster in that each node is only connected to one another node in a chain type fashion, so broker 0 -> broker 1 -> broker 2 + +We then create a consumer on the queue on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **all** consumers receive the sent messages in a round-robin fashion. + +In other words, ActiveMQ Artemis **load balances** the sent messages across all consumers on the cluster + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a one way cluster between the three nodes and to load balance the messages between the nodes. Note that we have set _allow-direct-connections-only_ to true, this means that this broker will only ever connect the address's specified in the list of connectors. ALso notice that _max-hops_ is 2, this is because broker 0 is not directly connected to broker 2, 2 hops in fact, so we allow any updates from servers up to 2 hops away + + + netty-connector + 500 + true + STRICT + 2 + + server1-connector + + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server0/broker.xml index 6557c6a4a6..a6f03dfa45 100644 --- a/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server0/broker.xml @@ -14,10 +14,8 @@ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. - --> - - - + --> + broker0 @@ -70,7 +68,7 @@ - +
diff --git a/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server1/broker.xml index 265cd6b5dd..ea626203ea 100644 --- a/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server1/broker.xml @@ -14,10 +14,8 @@ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. - --> - - - + --> + broker1 @@ -70,7 +68,7 @@ - +
diff --git a/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server2/broker.xml b/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server2/broker.xml index 272fa84e33..dd5e390383 100644 --- a/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server2/broker.xml +++ b/examples/features/clustered/clustered-static-oneway/src/main/resources/activemq/server2/broker.xml @@ -14,10 +14,8 @@ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ~ See the License for the specific language governing permissions and ~ limitations under the License. - --> - - - + --> + broker2 @@ -65,7 +63,7 @@ - +
diff --git a/examples/features/clustered/clustered-topic-uri/pom.xml b/examples/features/clustered/clustered-topic-uri/pom.xml index 7cdea9119f..836e2149e6 100644 --- a/examples/features/clustered/clustered-topic-uri/pom.xml +++ b/examples/features/clustered/clustered-topic-uri/pom.xml @@ -29,7 +29,7 @@ under the License. clustered-topic-uri jar - ActiveMQ Artemis JMS Clustered Topic Example + ActiveMQ Artemis JMS Clustered Topic URI Example ${project.basedir}/../../../.. @@ -151,6 +151,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-topic-uri/readme.html b/examples/features/clustered/clustered-topic-uri/readme.html deleted file mode 100644 index e7998a28ff..0000000000 --- a/examples/features/clustered/clustered-topic-uri/readme.html +++ /dev/null @@ -1,46 +0,0 @@ - - - - - ActiveMQ Artemis JMS Clustered Topic Example - - - - - -

JMS Clustered Topic Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a JMS Topic deployed on two different nodes. The two nodes are configured to form a cluster.

-

We then create a subscriber on the topic on each node, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that both subscribers receive all the - sent messages.

-

A JMS Topic is an example of publish-subscribe messaging where all subscribers receive all the - messages sent to the topic (assuming they have no message selectors).

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly. -

Here's the relevant snippet from the server configuration, which tells the server to form a cluster between the two nodes - and to load balance the messages between the nodes.

-

This example differes from different-topic as it will use an URI to define the cluster connection.

- 
<cluster-connection-uri name="my-cluster" address="uri="multicast://my-discovery-group?messageLoadBalancingType=STRICT;retryInterval=500;connectorName=netty-connector;maxHops=1"/>
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/clustered-topic-uri/readme.md b/examples/features/clustered/clustered-topic-uri/readme.md new file mode 100644 index 0000000000..22b9d18116 --- /dev/null +++ b/examples/features/clustered/clustered-topic-uri/readme.md @@ -0,0 +1,21 @@ +# JMS Clustered Topic URI Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a JMS Topic deployed on two different nodes. The two nodes are configured to form a cluster. + +We then create a subscriber on the topic on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **both** subscribers receive all the sent messages. + +A JMS Topic is an example of **publish-subscribe** messaging where all subscribers receive all the messages sent to the topic (assuming they have no message selectors). + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a cluster between the two nodes and to load balance the messages between the nodes. + +This example differs from different-topic as it will use an URI to define the cluster connection. + + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server0/broker.xml index 2f1129c071..d6e9ef8bc1 100644 --- a/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -78,7 +76,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server1/broker.xml index aa6337c93b..9450a55957 100644 --- a/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-topic-uri/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -76,7 +74,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-topic/pom.xml b/examples/features/clustered/clustered-topic/pom.xml index a7ac39bd89..b4ddbda017 100644 --- a/examples/features/clustered/clustered-topic/pom.xml +++ b/examples/features/clustered/clustered-topic/pom.xml @@ -151,6 +151,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/clustered-topic/readme.html b/examples/features/clustered/clustered-topic/readme.html deleted file mode 100644 index a36fd05a5c..0000000000 --- a/examples/features/clustered/clustered-topic/readme.html +++ /dev/null @@ -1,54 +0,0 @@ - - - - - ActiveMQ Artemis JMS Clustered Topic Example - - - - - -

JMS Clustered Topic Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a JMS Topic deployed on two different nodes. The two nodes are configured to form a cluster.

-

We then create a subscriber on the topic on each node, and we create a producer on only one of the nodes.

-

We then send some messages via the producer, and we verify that both subscribers receive all the - sent messages.

-

A JMS Topic is an example of publish-subscribe messaging where all subscribers receive all the - messages sent to the topic (assuming they have no message selectors).

-

This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly. -

Here's the relevant snippet from the server configuration, which tells the server to form a cluster between the two nodes - and to load balance the messages between the nodes.

- 
-     <cluster-connection name="my-cluster">
-        <retry-interval>500</retry-interval>
-        <use-duplicate-detection>true</use-duplicate-detection>
-        <message-load-balancing>STRICT</message-load-balancing>
-        <max-hops>1</max-hops>
-        <discovery-group-ref discovery-group-name="my-discovery-group"/>
-     </cluster-connection>
-     
-
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/clustered-topic/readme.md b/examples/features/clustered/clustered-topic/readme.md new file mode 100644 index 0000000000..397d0e7388 --- /dev/null +++ b/examples/features/clustered/clustered-topic/readme.md @@ -0,0 +1,25 @@ +# JMS Clustered Topic Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a JMS Topic deployed on two different nodes. The two nodes are configured to form a cluster. + +We then create a subscriber on the topic on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **both** subscribers receive all the sent messages. + +A JMS Topic is an example of **publish-subscribe** messaging where all subscribers receive all the messages sent to the topic (assuming they have no message selectors). + +This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use JNDI, these could be instantiated directly. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a cluster between the two nodes and to load balance the messages between the nodes. + + + 500 + true + STRICT + 1 + + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/clustered-topic/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/clustered-topic/src/main/resources/activemq/server0/broker.xml index 38d3f3b4ca..466f0ee8f8 100644 --- a/examples/features/clustered/clustered-topic/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/clustered-topic/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -85,7 +83,7 @@ under the License. - +
diff --git a/examples/features/clustered/clustered-topic/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/clustered-topic/src/main/resources/activemq/server1/broker.xml index afe16c1f75..dfa7b8b65a 100644 --- a/examples/features/clustered/clustered-topic/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/clustered-topic/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -83,7 +81,7 @@ under the License. - +
diff --git a/examples/features/clustered/queue-message-redistribution/pom.xml b/examples/features/clustered/queue-message-redistribution/pom.xml index 79acc8ef8d..79d4746442 100644 --- a/examples/features/clustered/queue-message-redistribution/pom.xml +++ b/examples/features/clustered/queue-message-redistribution/pom.xml @@ -152,7 +152,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/clustered/queue-message-redistribution/readme.html b/examples/features/clustered/queue-message-redistribution/readme.html deleted file mode 100644 index 35fcafe808..0000000000 --- a/examples/features/clustered/queue-message-redistribution/readme.html +++ /dev/null @@ -1,61 +0,0 @@ - - - - - ActiveMQ Artemis Message Redistribution Example - - - - - -

Message Redistribution Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- - -

This example demonstrates message redistribution between queues with the same name deployed in different - nodes of a cluster.

-

As demontrated in the clustered queue example, if queues with the same name are deployed on different nodes of - a cluster, ActiveMQ Artemis can be configured to load balance messages between the nodes on the server side.

-

However, if the consumer(s) on a particular node are closed, then messages in the queue at that node can - appear to be stranded, since they have no local consumers.

-

If this is undesirable, ActiveMQ Artemis can be configured to redistribute messages from the node - with no consumers, to nodes where there are consumers. If the consumers have JMS selectors set on them, then they - will only be redistributed to nodes with consumers whose selectors match.

-

By default, message redistribution is disabled, but can be enabled by specifying some AddressSettings configuration - in either activemq-queues.xml or broker.xml

-

Setting redistribution-delay to 0 will cause redistribution to occur immediately - once there are no more matching consumers on a particular queue instance. Setting it to a positive value > 0 specifies - a delay in milliseconds before attempting to redistribute. The delay is useful in the case that another consumer is - likely to be created on the queue, to avoid unnecessary redistribution.

-

Here's the relevant snippet from the activemq-queues.xml configuration, which tells the server - to use a redistribution delay of 0 on any jms queues, i.e. any queues whose name starts with - jms.

- 
-     
-  <address-setting match="jms.#">
-      <redistribution-delay>0</redistribution-delay>
-   </address-setting>
-   
-
-

For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/queue-message-redistribution/readme.md b/examples/features/clustered/queue-message-redistribution/readme.md new file mode 100644 index 0000000000..f1a7575003 --- /dev/null +++ b/examples/features/clustered/queue-message-redistribution/readme.md @@ -0,0 +1,23 @@ +# Message Redistribution Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates message redistribution between queues with the same name deployed in different nodes of a cluster. + +As demontrated in the clustered queue example, if queues with the same name are deployed on different nodes of a cluster, ActiveMQ Artemis can be configured to load balance messages between the nodes on the broker side. + +However, if the consumer(s) on a particular node are closed, then messages in the queue at that node can appear to be stranded, since they have no local consumers. + +If this is undesirable, ActiveMQ Artemis can be configured to **redistribute** messages from the node with no consumers, to nodes where there are consumers. If the consumers have JMS selectors set on them, then they will only be redistributed to nodes with consumers whose selectors match. + +By default, message redistribution is disabled, but can be enabled by specifying some AddressSettings configuration in either `activemq-queues.xml` or `broker.xml` + +Setting `redistribution-delay` to `0` will cause redistribution to occur immediately once there are no more matching consumers on a particular queue instance. Setting it to a positive value > 0 specifies a delay in milliseconds before attempting to redistribute. The delay is useful in the case that another consumer is likely to be created on the queue, to avoid unnecessary redistribution. + +Here's the relevant snippet from the `activemq-queues.xml` configuration, which tells the broker to use a redistribution delay of `0` on any jms queues, i.e. any queues whose name starts with `jms.` + + + 0 + + +For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/queue-message-redistribution/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/queue-message-redistribution/src/main/resources/activemq/server0/broker.xml index 976c0e7f76..a691057336 100644 --- a/examples/features/clustered/queue-message-redistribution/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/queue-message-redistribution/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - - - - +--> + ./data/bindings @@ -85,7 +83,7 @@ under the License. - - - - - ActiveMQ Artemis JMS Symmetric Cluster Example - - - - - -

JMS Symmetric Cluster Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- - -

This examples demonstrates a symmetric cluster set-up with ActiveMQ Artemis.

-

ActiveMQ Artemis has extremely flexible clustering which allows you to set-up servers in - many different topologies.

-

The most common topology that you'll perhaps be familiar with if you are used to application - server clustering is a symmetric cluster.

-

With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured the same - as every other node, and every node is connected to every other node in the cluster.

-

By connecting node in such a way, we can, from a JMS point of view, give the impression of distributed - JMS queues and topics.

-

The configuration used in this example is very similar to the configuration used by ActiveMQ - when installed as a clustered profile in JBoss Application Server.

-

To set up ActiveMQ Artemis to form a symmetric cluster we simply need to mark each server as clustered - and we need to define a cluster-connection in broker.xml.

-

The cluster-connection tells the nodes what other nodes to make connections to. - With a cluster-connection each node that we connect to can either be specified - indivually, or we can use UDP discovery to find out what other nodes are in the cluster.

-

Using UDP discovery makes configuration simpler since we don't have to know what nodes are - available at any one time.

-

Here's the relevant snippet from the server configuration, which tells the server to form a cluster - with the other nodes:

- 
-     
-   <cluster-connection name="my-cluster">
-      <connector-ref>netty-connector</connector-ref>
-	   <retry-interval>500</retry-interval>
-	   <use-duplicate-detection>true</use-duplicate-detection>
-	   <message-load-balancing>STRICT</message-load-balancing>
-	   <max-hops>1</max-hops>
-	   <discovery-group-ref discovery-group-name="my-discovery-group"/>
-   </cluster-connection>
-   
-
-

In this example we create a symmetric cluster of six live nodes, and we also pair each live node - with it's own backup node. (A backup node is not strictly necessary for a symmetric cluster).

-

In this example will we will demonstrate this by deploying a JMS topic and Queue on all nodes of the cluster - , sending messages to the queue and topic from different nodes, and verifying messages are received correctly - by consumers on different nodes.

-

For more information on configuring ActiveMQ Artemis clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/clustered/symmetric-cluster/readme.md b/examples/features/clustered/symmetric-cluster/readme.md new file mode 100644 index 0000000000..e06202870a --- /dev/null +++ b/examples/features/clustered/symmetric-cluster/readme.md @@ -0,0 +1,38 @@ +# JMS Symmetric Cluster Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This examples demonstrates a **symmetric cluster** set-up with ActiveMQ Artemis. + +ActiveMQ Artemis has extremely flexible clustering which allows you to set-up servers in many different topologies. + +The most common topology that you'll perhaps be familiar with if you are used to application broker clustering is a **symmetric cluster**. + +With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured the same as every other node, and every node is connected to every other node in the cluster. + +By connecting node in such a way, we can, from a JMS point of view, give the impression of distributed JMS queues and topics. + +The configuration used in this example is very similar to the configuration used by ActiveMQ when installed as a clustered profile in JBoss Application Server. + +To set up ActiveMQ Artemis to form a symmetric cluster we simply need to mark each broker as `clustered` and we need to define a `cluster-connection` in `broker.xml`. + +The `cluster-connection` tells the nodes what other nodes to make connections to. With a `cluster-connection` each node that we connect to can either be specified indivually, or we can use UDP discovery to find out what other nodes are in the cluster. + +Using UDP discovery makes configuration simpler since we don't have to know what nodes are available at any one time. + +Here's the relevant snippet from the broker configuration, which tells the broker to form a cluster with the other nodes: + + + netty-connector + 500 + true + STRICT + 1 + + + +In this example we create a symmetric cluster of six live nodes, and we also pair each live node with it's own backup node. (A backup node is not strictly necessary for a symmetric cluster). + +In this example will we will demonstrate this by deploying a JMS topic and Queue on all nodes of the cluster , sending messages to the queue and topic from different nodes, and verifying messages are received correctly by consumers on different nodes. + +For more information on configuring ActiveMQ Artemis clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/clustered/symmetric-cluster/src/main/java/org/apache/activemq/artemis/jms/example/SymmetricClusterExample.java b/examples/features/clustered/symmetric-cluster/src/main/java/org/apache/activemq/artemis/jms/example/SymmetricClusterExample.java index 1e3ea2b872..1ed6a28ca3 100644 --- a/examples/features/clustered/symmetric-cluster/src/main/java/org/apache/activemq/artemis/jms/example/SymmetricClusterExample.java +++ b/examples/features/clustered/symmetric-cluster/src/main/java/org/apache/activemq/artemis/jms/example/SymmetricClusterExample.java @@ -45,7 +45,7 @@ import org.apache.activemq.artemis.api.jms.JMSFactoryType; * servers at different times, and verify that they transparently fail over onto their backup * servers. *

- * Please see the readme.html file for more information. + * Please see the readme for more information. */ public class SymmetricClusterExample { diff --git a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server0/broker.xml b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server0/broker.xml index f5388150f5..c5539911ed 100644 --- a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -86,7 +84,7 @@ under the License. - +

diff --git a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server1/broker.xml b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server1/broker.xml index be1dbb3fb1..e4cd04633c 100644 --- a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server2/broker.xml b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server2/broker.xml index 1f860f4c54..3289e4cb48 100644 --- a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server2/broker.xml +++ b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server2/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server3/broker.xml b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server3/broker.xml index 207e75b66f..30e5c1ea51 100644 --- a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server3/broker.xml +++ b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server3/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server4/broker.xml b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server4/broker.xml index 92b5ac9597..7b2a110416 100644 --- a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server4/broker.xml +++ b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server4/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -83,7 +81,7 @@ under the License. - +
diff --git a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server5/broker.xml b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server5/broker.xml index bd4a4aba39..e8acf784ec 100644 --- a/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server5/broker.xml +++ b/examples/features/clustered/symmetric-cluster/src/main/resources/activemq/server5/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -83,7 +81,7 @@ under the License. - +
diff --git a/examples/features/ha/application-layer-failover/pom.xml b/examples/features/ha/application-layer-failover/pom.xml index 960907601c..8fb4ad5785 100644 --- a/examples/features/ha/application-layer-failover/pom.xml +++ b/examples/features/ha/application-layer-failover/pom.xml @@ -99,7 +99,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/ha/application-layer-failover/readme.html b/examples/features/ha/application-layer-failover/readme.html deleted file mode 100644 index c5248aade5..0000000000 --- a/examples/features/ha/application-layer-failover/readme.html +++ /dev/null @@ -1,169 +0,0 @@ - - - - - ActiveMQ Artemis Application-Layer Failover Example - - - - - -

Application-Layer Failover Example

- - 
To run the example, simply type mvn verify from this directory. This example will always spawn and stop multiple servers.
- -

ActiveMQ Artemis implements fully transparent automatic failover of connections from a live node to a backup node which requires - no special coding. This is described in a different example and requires server replication.

-

However, ActiveMQ Artemis also supports Application-Layer failover which is useful in the case where replication is not enabled.

-

With Application-Layer failover, it's up to the application to register a JMS ExceptionListener with ActiveMQ Artemis. - This listener will then be called by ActiveMQ Artemis in the event that connection failure is detected.

-

User code in the ExceptionListener can then recreate any JMS Connection, Session, etc on another node and the application - can continue.

-

Application-Layer failover is an alternative approach to High Availability (HA).

-

Application-Layer failover differs from automatic failover in that some client side coding is required in order - to implement this. Also, with Application-Layer failover, since the old Session object dies and a new is created, any uncommitted - work in the old Session will be lost, and any unacknowledged messages might be redelivered.

-

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- -

Example step-by-step

-

In this example, the live server is server 1, which will failover onto server 0.

-

The connection will initially be created to server1, server 1 will crash, and the client will carry on - on server 0, the new server. With Application-Layer failover the node that is failed over onto, does not need to - be specially configured as a backup server, it can be any node.

- -
    -
  1. We create our JMS Connection, Session, MessageProducer and MessageConsumer on server 1
    2. - 
    -           createJMSObjects(1);
-
    - -
  2. We set a JMS ExceptionListener on the connection. On failure this will be called and the connection, - session, etc. will be manually recreated on the backup node.
    3. - 
    -           connection.setExceptionListener(new ExampleListener());
-
    - -
  3. We send some messages to server 1, the live server.
    4. - 
    -           
-         final int numMessages = 10;
-
-         for (int i = 0; i < numMessages; i++)
-         {
-            TextMessage message = session.createTextMessage("This is text message " + i);
-
-            producer.send(message);
-
-            System.out.println("Sent message: " + message.getText());
-         }
-           
-
    - -
  4. We consume those messages on server 1.
    5. - 
    -          
-          for (int i = 0; i < numMessages; i++)
-         {
-            TextMessage message0 = (TextMessage)consumer.receive(5000);
-
-            System.out.println("Got message: " + message0.getText());
-         }
-          
-
    - -
  5. We now cause server 1, the live server to crash. After a little while the connection's - ExceptionListener will register the failure and reconnection will occur.
    6. - 
    -           killServer(1);
-
    - -
  6. The connection's ExceptionListener gets called, and we lookup the JMS objects and - recreate the connection, session, etc on the other node 0.
    7. - 
    -           
-   private class ExampleListener implements ExceptionListener
-   {
-      public void onException(JMSException exception)
-      {
-         try
-         {
-            // Close the old resources
-
-            closeResources();
-
-            // Create new JMS objects on the backup server
-
-            createJMSObjects(0);
-
-            failoverLatch.countDown();
-         }
-         catch (Exception e)
-         {
-            System.err.println("Failed to handle failover");
-
-            e.printStackTrace();
-         }
-      }
-   }
-           
-
    - -
  7. We are now connected to the other node. We now send some more messages.
    8. - 
    -           
-   for (int i = numMessages; i < numMessages * 2; i++)
-         {
-            TextMessage message = session.createTextMessage("This is text message " + i);
-
-            producer.send(message);
-
-            System.out.println("Sent message: " + message.getText());
-         }
-           
-
    - -
  8. And consume them.
    9. - 
    -           
-   for (int i = 0; i < numMessages; i++)
-         {
-            TextMessage message0 = (TextMessage)consumer.receive(5000);
-
-            System.out.println("Got message: " + message0.getText());
-         }
-           
-
    - - -
  9. And finally (no pun intended), always remember to close your resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
    10. - - 
    -           
-	finally
-	{
-	   closeResources();
-	}
-           
-
    - -
- - diff --git a/examples/features/ha/application-layer-failover/readme.md b/examples/features/ha/application-layer-failover/readme.md new file mode 100644 index 0000000000..1ef46b489f --- /dev/null +++ b/examples/features/ha/application-layer-failover/readme.md @@ -0,0 +1,17 @@ +# JMS Application-Layer Failover Example + +To run the example, simply type **mvn verify** from this directory. This example will always spawn and stop multiple brokers. + +ActiveMQ Artemis implements fully transparent **automatic** failover of connections from a live node to a backup node which requires no special coding. This is described in a different example and requires broker replication. + +However, ActiveMQ Artemis also supports **Application-Layer** failover which is useful in the case where replication is not enabled. + +With Application-Layer failover, it's up to the application to register a JMS ExceptionListener with ActiveMQ Artemis. This listener will then be called by ActiveMQ Artemis in the event that connection failure is detected. + +User code in the ExceptionListener can then recreate any JMS Connection, Session, etc on another node and the application can continue. + +Application-Layer failover is an alternative approach to High Availability (HA). + +Application-Layer failover differs from automatic failover in that some client side coding is required in order to implement this. Also, with Application-Layer failover, since the old Session object dies and a new is created, any uncommitted work in the old Session will be lost, and any unacknowledged messages might be redelivered. + +For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/ha/client-side-failoverlistener/pom.xml b/examples/features/ha/client-side-failoverlistener/pom.xml index 30d22aa6b7..8fb778092c 100644 --- a/examples/features/ha/client-side-failoverlistener/pom.xml +++ b/examples/features/ha/client-side-failoverlistener/pom.xml @@ -27,9 +27,9 @@ under the License. 2.5.0-SNAPSHOT - client-side-fileoverlistener + client-side-failoverlistener jar - ActiveMQ Artemis JMS Client Side Failover listener Example + ActiveMQ Artemis JMS Client Side Failover Listener Example ${project.basedir}/../../../.. @@ -106,7 +106,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/client-side-failoverlistener/readme.html b/examples/features/ha/client-side-failoverlistener/readme.html deleted file mode 100644 index 3fe1f4dbfb..0000000000 --- a/examples/features/ha/client-side-failoverlistener/readme.html +++ /dev/null @@ -1,37 +0,0 @@ - - - - - ActiveMQ Artemis Client Side Failover Listener Example - - - - - -

Client Side Kickoff Example

- 
To run the example, simply type mvn verify from this directory. This example will always spawn and stop multiple servers.
- -

This example demonstrates how you can listen on failover event on the client side.

- -

In this example there are two nodes running in a cluster, both server will be running for start, - but after a while the first server will crash. This will trigger a fail-over event.

- - - diff --git a/examples/features/ha/client-side-failoverlistener/readme.md b/examples/features/ha/client-side-failoverlistener/readme.md new file mode 100644 index 0000000000..c766986881 --- /dev/null +++ b/examples/features/ha/client-side-failoverlistener/readme.md @@ -0,0 +1,7 @@ +# JMS Client Side Failover Listener Example + +To run the example, simply type **mvn verify** from this directory. This example will always spawn and stop multiple servers. + +This example demonstrates how you can listen on failover event on the client side. + +In this example there are two nodes running in a cluster, both broker will be running for start, but after a while the first broker will crash. This will trigger a fail-over event. \ No newline at end of file diff --git a/examples/features/ha/colocated-failover-scale-down/pom.xml b/examples/features/ha/colocated-failover-scale-down/pom.xml index ca20c13637..ec329a386d 100644 --- a/examples/features/ha/colocated-failover-scale-down/pom.xml +++ b/examples/features/ha/colocated-failover-scale-down/pom.xml @@ -100,7 +100,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/colocated-failover-scale-down/readme.html b/examples/features/ha/colocated-failover-scale-down/readme.html deleted file mode 100644 index 8be50305d8..0000000000 --- a/examples/features/ha/colocated-failover-scale-down/readme.html +++ /dev/null @@ -1,65 +0,0 @@ - - - - - ActiveMQ Artemis JMS Colocated Failover Scale Down Example - - - - - -

JMS Colocated Failover Recover Only Example

- 
To run the example, simply type mvn verify from this directory. This example will always spawn and stop multiple servers.
- - -

This example demonstrates how you can colocate live and backup servers in the same VM. We do this by creating an - HA Policy that is colocated. colocated means that backup servers can be created and maintained by live servers on behalf - of other requesting live servers. In this example we create a colocated shared store server that will scale down. - That is it will not become live but scale down the journal to the colocated live server. -

This example starts 2 live servers each will request the other to create a backup.

-

The first live server will be killed and the backup in the second will recover the journal and recreate its state - in the live server it shares its VM with.

-

The following shows how to configure the backup, the slave is configured <scale-down/> which means - that the backup server will not fully start on fail over, instead it will just recover the journal and write it - to its parent live server.

- 
-     <ha-policy>
-         <shared-store>
-             <colocated>
-                 <backup-port-offset>100</backup-port-offset>
-                 <backup-request-retries>-1</backup-request-retries>
-                 <backup-request-retry-interval>2000</backup-request-retry-interval>
-                 <max-backups>1</max-backups>
-                 <request-backup>true</request-backup>
-                 <master/>
-                 <slave>
-                     <scale-down/>
-                 </slave>
-             </colocated>
-         </shared-store>
-     </ha-policy>
-     
-
-

Notice that we dont need to specify a scale down connector as it will use most appropriate - from the list of available connectors which in this case is the first INVM connector

-

One other thing to notice is that the cluster connection has its reconnect attempts set to 5, this is so it will - disconnect instead of trying to reconnect to a backup that doesn't exist.

- - diff --git a/examples/features/ha/colocated-failover-scale-down/readme.md b/examples/features/ha/colocated-failover-scale-down/readme.md new file mode 100644 index 0000000000..3b9c81a7d6 --- /dev/null +++ b/examples/features/ha/colocated-failover-scale-down/readme.md @@ -0,0 +1,31 @@ +# JMS Colocated Failover Recover Only Example + +To run the example, simply type **mvn verify** from this directory. This example will always spawn and stop multiple servers. + +This example demonstrates how you can colocate live and backup servers in the same VM. We do this by creating an HA Policy that is colocated. Colocated means that backup servers can be created and maintained by live servers on behalf of other requesting live servers. In this example we create a colocated shared store broker that will scale down. That is it will not become live but scale down the journal to the colocated live server. + +This example starts 2 live servers each will request the other to create a backup. + +The first live broker will be killed and the backup in the second will recover the journal and recreate its state in the live broker it shares its VM with. + +The following shows how to configure the backup, the slave is configured **** which means that the backup broker will not fully start on fail over, instead it will just recover the journal and write it to its parent live server. + + + + + 100 + -1 + 2000 + 1 + true + + + + + + + + +Notice that we dont need to specify a scale down connector as it will use most appropriate from the list of available connectors which in this case is the first INVM connector + +One other thing to notice is that the cluster connection has its reconnect attempts set to 5, this is so it will disconnect instead of trying to reconnect to a backup that doesn't exist. \ No newline at end of file diff --git a/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server0/broker.xml index cd83afe12f..38a763376b 100644 --- a/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -117,7 +115,7 @@ under the License. - +
diff --git a/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server1/broker.xml index 88a878aec3..08e387c455 100644 --- a/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/colocated-failover-scale-down/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -115,7 +113,7 @@ under the License. - +
diff --git a/examples/features/ha/colocated-failover/pom.xml b/examples/features/ha/colocated-failover/pom.xml index 5cf10a83cd..ce840055ae 100644 --- a/examples/features/ha/colocated-failover/pom.xml +++ b/examples/features/ha/colocated-failover/pom.xml @@ -100,6 +100,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/colocated-failover/readme.html b/examples/features/ha/colocated-failover/readme.html deleted file mode 100644 index a3700d4e39..0000000000 --- a/examples/features/ha/colocated-failover/readme.html +++ /dev/null @@ -1,56 +0,0 @@ - - - - - ActiveMQ Artemis JMS Colocated Failover Example - - - - - -

JMS Colocated Failover Shared Store Example

- 
To run the example, simply type mvn verify from this directory. This example will always spawn and stop multiple servers.
- -

This example demonstrates how you can colocate live and backup servers in the same VM. We do this by creating an - HA Policy that is colocated. colocated means that backup servers can be created and maintained by live servers on behalf - of other requesting live servers. In this example we create a colocated shared store server. -

This example starts 2 live servers each with a backup server that backs up the other live server.

-

The first live server will be killed and the backup in the second will become live

-

The following shows how to configure the live servers to request and allow backups to be deployed

- 
-     <ha-policy>
-         <shared-store>
-             <colocated>
-                 <backup-port-offset>100</backup-port-offset>
-                 <backup-request-retries>-1</backup-request-retries>
-                 <backup-request-retry-interval>2000</backup-request-retry-interval>
-                 <max-backups>1</max-backups>
-                 <request-backup>true</request-backup>
-                 <master/>
-                 <slave/>
-             </colocated>
-         </shared-store>
-     </ha-policy>
-     
-
-

notice that we have used a template to set some sensible defaults but overridden the backup strategy so back ups - are full servers

- - diff --git a/examples/features/ha/colocated-failover/readme.md b/examples/features/ha/colocated-failover/readme.md new file mode 100644 index 0000000000..b338e5a8ab --- /dev/null +++ b/examples/features/ha/colocated-failover/readme.md @@ -0,0 +1,27 @@ +# JMS Colocated Failover Shared Store Example + +To run the example, simply type **mvn verify** from this directory. This example will always spawn and stop multiple brokers. + +This example demonstrates how you can colocate live and backup brokers in the same VM. We do this by creating an HA Policy that is colocated. Colocated means that backup brokers can be created and maintained by live brokers on behalf of other live brokers requesting a backup. In this example we create a colocated shared store broker. + +This example starts 2 live brokers each with a backup broker that backs up the other live broker. + +The first live broker will be killed and the backup in the second will become live + +The following shows how to configure the live brokers to request and allow backups to be deployed + + + + + 100 + -1 + 2000 + 1 + true + + + + + + +notice that we have used a template to set some sensible defaults but overridden the backup strategy so back ups are full brokers. \ No newline at end of file diff --git a/examples/features/ha/colocated-failover/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/colocated-failover/src/main/resources/activemq/server0/broker.xml index eca60a9df9..69427a840a 100644 --- a/examples/features/ha/colocated-failover/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/colocated-failover/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -103,7 +101,7 @@ under the License. - +
diff --git a/examples/features/ha/colocated-failover/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/colocated-failover/src/main/resources/activemq/server1/broker.xml index 81c0abc07a..ef3b4171b2 100644 --- a/examples/features/ha/colocated-failover/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/colocated-failover/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -102,7 +100,7 @@ under the License. - +
diff --git a/examples/features/ha/ha-policy-autobackup/pom.xml b/examples/features/ha/ha-policy-autobackup/pom.xml index 43ce5cc519..12a5cca4c9 100644 --- a/examples/features/ha/ha-policy-autobackup/pom.xml +++ b/examples/features/ha/ha-policy-autobackup/pom.xml @@ -100,7 +100,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server0/broker.xml index 534e2ac2c6..a06f16959c 100644 --- a/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server0/broker.xml @@ -16,11 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - - +--> + ${data.dir}/server0/data/messaging/bindings @@ -96,7 +93,7 @@ under the License. - +
diff --git a/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server1/broker.xml index 5b6958225a..b0102ffa9e 100644 --- a/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/ha-policy-autobackup/src/main/resources/activemq/server1/broker.xml @@ -16,11 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - - +--> + ${data.dir}/server0/data/messaging/bindings @@ -96,7 +93,7 @@ under the License. - +
diff --git a/examples/features/ha/multiple-failover-failback/pom.xml b/examples/features/ha/multiple-failover-failback/pom.xml index a5e31ea41e..1ca63a8bca 100644 --- a/examples/features/ha/multiple-failover-failback/pom.xml +++ b/examples/features/ha/multiple-failover-failback/pom.xml @@ -120,7 +120,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/multiple-failover/pom.xml b/examples/features/ha/multiple-failover/pom.xml index 51f47a31fb..c1018362b6 100644 --- a/examples/features/ha/multiple-failover/pom.xml +++ b/examples/features/ha/multiple-failover/pom.xml @@ -120,7 +120,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/non-transaction-failover/pom.xml b/examples/features/ha/non-transaction-failover/pom.xml index 52f09445ea..1f6493f3d7 100644 --- a/examples/features/ha/non-transaction-failover/pom.xml +++ b/examples/features/ha/non-transaction-failover/pom.xml @@ -106,7 +106,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/non-transaction-failover/readme.html b/examples/features/ha/non-transaction-failover/readme.html deleted file mode 100644 index 647e7b84cc..0000000000 --- a/examples/features/ha/non-transaction-failover/readme.html +++ /dev/null @@ -1,157 +0,0 @@ - - - - - ActiveMQ Artemis JMS Failover Without Transactions Example - - - - - -

JMS Failover Without Transactions Example

- - 
To run the example, simply type mvn verify from this directory.
- - -

This example demonstrates two servers coupled as a live-backup pair for high availability (HA), and a client - connection failing over from live to backup when the live server is crashed.

-

Failover behavior differs whether the JMS session is transacted or not.

-

When a non-transacted JMS session is used, once and only once delivery is not guaranteed - and it is possible some messages will be lost or delivered twice, depending when the failover to the backup server occurs.

-

It is up to the client to deal with such cases. To ensure once and only once delivery, the client must - use transacted JMS sessions (as shown in the example for failover with transactions).

-

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- -

Example step-by-step

-

In this example, the live server is server 1, and the backup server is server 0

-

The connection will initially be created to server1, server 1 will crash, and the client will carry on - seamlessly on server 0, the backup server.

-
    -
  1. Get an initial context for looking up JNDI from server #1.
    2. - 
    -           initialContext = getContext(1);
-
    - -
  2. Look up the JMS resources from JNDI on server #1.
    3. - 
    -           Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");
-           ConnectionFactory connectionFactory = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
-
    - -
  3. Create a JMS Connection
    4. - 
    -           connection = connectionFactory.createConnection();
-
    - -
  4. Create a JMS non-transacted Session with client acknowledgement
    5. - 
    -           Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);
-
    - -
  5. Start the connection to ensure delivery occurs
    6. - 
    -           connection.start();
-
    - -
  6. Create a JMS MessageProducer and MessageConsumer
    7. - 
    -           MessageProducer producer = session.createProducer(queue);
-           MessageConsumer consumer = session.createConsumer(queue);
-
    - -
  7. Send some messages to server #1
    8. - 
    -           for (int i = 0; i < numMessages; i++)
-           {
-              TextMessage message = session.createTextMessage("This is text message " + i);
-              producer.send(message);
-              System.out.println("Sent message: " + message.getText());
-           }
-
    - -
  8. Receive and acknowledge half of the sent messages
    9. - 
    -           TextMessage message0 = null;
-           for (int i = 0; i < numMessages / 2; i++)
-           {
-              message0 = (TextMessage)consumer.receive(5000);
-              System.out.println("Got message: " + message0.getText());
-           }
-           message0.acknowledge();
-
    - -
  9. Receive the second half of the sent messages but do not acknowledge them yet
    10. - 
    -           for (int i = numMessages / 2; i < numMessages; i++)
-           {
-              message0 = (TextMessage)consumer.receive(5000);
-              System.out.println("Got message: " + message0.getText());
-           }
-
    - -
  10. Crash server #1, the live server, and wait a little while to make sure it has really crashed.
    11. - 
    -           killServer(1);
-           Thread.sleep(2000);
-
    - -
  11. Acknowledging the second half of the sent messages will fail as failover to the backup server has occurred
    12. - 
    -           try
-           {
-              message0.acknowledge();
-           }
-           catch (JMSException e)
-           {
-              System.err.println("Got exception while acknowledging message: " + e.getMessage());
-           }
-
    - -
  12. Consume again the second half of the messages againg. Note that they are not considered as redelivered
    13. - 
    -           for (int i = numMessages / 2; i < numMessages; i++)
-           {
-              message0 = (TextMessage)consumer.receive(5000);
-              System.out.printf("Got message: %s (redelivered?: %s)\n", message0.getText(), message0.getJMSRedelivered());
-           }
-           message0.acknowledge();
-
    - -
  13. And finally, always remember to close your resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
    14. - - 
    -           finally
-           {
-              if (connection != null)
-              {
-                 connection.close();
-              }
-
-              if (initialContext != null)
-              {
-                 initialContext.close();
-              }
-           }
-
    - -
- - diff --git a/examples/features/ha/non-transaction-failover/readme.md b/examples/features/ha/non-transaction-failover/readme.md new file mode 100644 index 0000000000..6c51d89281 --- /dev/null +++ b/examples/features/ha/non-transaction-failover/readme.md @@ -0,0 +1,13 @@ +# JMS Non Transaction Failover Example + +To run the example, simply type **mvn verify** from this directory. + +This example demonstrates two servers coupled as a live-backup pair for high availability (HA), and a client connection failing over from live to backup when the live broker is crashed. + +Failover behavior differs whether the JMS session is transacted or not. + +When a _non-transacted_ JMS session is used, once and only once delivery is not guaranteed and it is possible some messages will be lost or delivered twice, depending when the failover to the backup broker occurs. + +It is up to the client to deal with such cases. To ensure once and only once delivery, the client must use transacted JMS sessions (as shown in the "transaction-failover" example). + +For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/ha/replicated-failback-static/pom.xml b/examples/features/ha/replicated-failback-static/pom.xml index 6020fcc186..348f82a72f 100644 --- a/examples/features/ha/replicated-failback-static/pom.xml +++ b/examples/features/ha/replicated-failback-static/pom.xml @@ -102,6 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/replicated-failback-static/readme.html b/examples/features/ha/replicated-failback-static/readme.html deleted file mode 100644 index cab789a0a5..0000000000 --- a/examples/features/ha/replicated-failback-static/readme.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - ActiveMQ Artemis JMS Failback using Static selectors Example - - - - - -

JMS Multiple Failover using Replication Example

- - 
To run the example, simply type mvn verify from this directory.
- -

This example demonstrates three servers coupled as a live-backup-backup group for high availability (HA) using replication, and a client - connection failing over from live to backup when the live server is crashed and then to the second backup once the new live fails.

- -

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/ha/replicated-failback-static/readme.md b/examples/features/ha/replicated-failback-static/readme.md new file mode 100644 index 0000000000..f48c885582 --- /dev/null +++ b/examples/features/ha/replicated-failback-static/readme.md @@ -0,0 +1,7 @@ +# JMS Replicated Failback Static Example + +To run the example, simply type **mvn verify** from this directory. + +This example is the same as the "replicated-failback" example but with a "static" clustering configuration (i.e. not using UDP multicast). + +For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server0/broker.xml index 205de1b6f0..f18406283d 100644 --- a/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -75,7 +73,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server1/broker.xml index 230d635032..f2b860f4ef 100644 --- a/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/replicated-failback-static/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -77,7 +75,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-failback/pom.xml b/examples/features/ha/replicated-failback/pom.xml index c843cf3546..8e179b6262 100644 --- a/examples/features/ha/replicated-failback/pom.xml +++ b/examples/features/ha/replicated-failback/pom.xml @@ -101,6 +101,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/ha/replicated-failback/readme.html b/examples/features/ha/replicated-failback/readme.html deleted file mode 100644 index 4e53739ac0..0000000000 --- a/examples/features/ha/replicated-failback/readme.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - ActiveMQ Artemis JMS Multiple Failover using Replication Example - - - - - -

JMS Multiple Failover using Replication Example

- - 
To run the example, simply type mvn verify from this directory.
- -

This example demonstrates three servers coupled as a live-backup-backup group for high availability (HA) using replication, and a client - connection failing over from live to backup when the live server is crashed and then to the second backup once the new live fails.

- -

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/ha/replicated-failback/readme.md b/examples/features/ha/replicated-failback/readme.md new file mode 100644 index 0000000000..8dfe609e06 --- /dev/null +++ b/examples/features/ha/replicated-failback/readme.md @@ -0,0 +1,7 @@ +# JMS Replicated Failback Example + +To run the example, simply type **mvn verify** from this directory. + +This example demonstrates two servers coupled as a live-backup pair for high availability (HA) using replication and a client connection failing over from live to backup when the live broker is crashed and then back to the original live when it is restarted (i.e. "failback"). + +For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/ha/replicated-failback/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/replicated-failback/src/main/resources/activemq/server0/broker.xml index 7b32414f4e..6fce88dea4 100644 --- a/examples/features/ha/replicated-failback/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/replicated-failback/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -89,7 +87,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-failback/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/replicated-failback/src/main/resources/activemq/server1/broker.xml index 58f47380c4..84350913ba 100644 --- a/examples/features/ha/replicated-failback/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/replicated-failback/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -90,7 +88,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-multiple-failover/pom.xml b/examples/features/ha/replicated-multiple-failover/pom.xml index e296bdf7c6..04c73999f5 100644 --- a/examples/features/ha/replicated-multiple-failover/pom.xml +++ b/examples/features/ha/replicated-multiple-failover/pom.xml @@ -115,7 +115,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/replicated-multiple-failover/readme.html b/examples/features/ha/replicated-multiple-failover/readme.html deleted file mode 100644 index da37085d34..0000000000 --- a/examples/features/ha/replicated-multiple-failover/readme.html +++ /dev/null @@ -1,45 +0,0 @@ - - - - - ActiveMQ Artemis JMS Multiple Failover using Replication Example - - - - - -

JMS Multiple Failover using Replication Example

- - 
To run the example, simply type mvn verify from this directory.
- - -

This example demonstrates three servers coupled as a live-backup-backup group for high availability (HA) using replication, and a client - connection failing over from live to backup when the live server is crashed and then to the second backup once the new live fails.

- -

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- -

Example step-by-step

-

To run the example, simply type mvn verify -Pexample from this directory

-

In this example, the live server is server 1, and the backup server is server 0

-

The connection will initially be created to server1, server 1 will crash, and the client will carry on - seamlessly on server 0, the backup server.

- - diff --git a/examples/features/ha/replicated-multiple-failover/readme.md b/examples/features/ha/replicated-multiple-failover/readme.md new file mode 100644 index 0000000000..06e44d05d5 --- /dev/null +++ b/examples/features/ha/replicated-multiple-failover/readme.md @@ -0,0 +1,7 @@ +# JMS Multiple Failover using Replication Example + +To run the example, simply type **mvn verify** from this directory. + +This example demonstrates three servers coupled as a live-backup-backup group for high availability (HA) using replication, and a client connection failing over from live to backup when the live broker is crashed and then to the second backup once the new live fails. + +For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server0/broker.xml index d9c39e5f65..fa4d9ec541 100644 --- a/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -83,7 +81,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server1/broker.xml index bc03fe1a48..963a567ec3 100644 --- a/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -83,7 +81,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server2/broker.xml b/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server2/broker.xml index 8b4d782f9c..4b170ce57b 100644 --- a/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server2/broker.xml +++ b/examples/features/ha/replicated-multiple-failover/src/main/resources/activemq/server2/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -83,7 +81,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-transaction-failover/pom.xml b/examples/features/ha/replicated-transaction-failover/pom.xml index 83843ad1df..8226f7b2ee 100644 --- a/examples/features/ha/replicated-transaction-failover/pom.xml +++ b/examples/features/ha/replicated-transaction-failover/pom.xml @@ -98,6 +98,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/replicated-transaction-failover/readme.html b/examples/features/ha/replicated-transaction-failover/readme.html deleted file mode 100644 index 4206588e8f..0000000000 --- a/examples/features/ha/replicated-transaction-failover/readme.html +++ /dev/null @@ -1,148 +0,0 @@ - - - - - ActiveMQ Artemis JMS Failover With Transaction using Replication Example - - - - - -

JMS Failover With Transaction using Replication Example

- -

This example demonstrates two servers coupled as a live-backup pair for high availability (HA) using replication, and a client - connection failing over from live to backup when the live server is crashed.

-

Failover behavior differs whether the JMS session is transacter or not.

-

When a transacted JMS session is used, once-and-only once delivery is guaranteed.

-
    -
  • if the failover occurs while there is an in-flight transaction, the transaction will be flagged as rollback only. In that case, the JMS client - will need to retry the transaction work.
    • -
  • if the failover occurs while there is no in-flight transaction, the failover will be transparent to the user.
    • -
-

ActiveMQ Artemis also provides an example for non-transaction failover.

-

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- -

Example step-by-step

-

To run the example, simply type mvn verify -Pexample from this directory

-

In this example, the live server is server 1, and the backup server is server 0

-

The connection will initially be created to server1, server 1 will crash, and the client will carry on - seamlessly on server 0, the backup server.

- -
    -
  1. Get an initial context for looking up JNDI from server #1.
    2. - 
    -           initialContext = getContext(1);
-
    - -
  2. Look up the JMS resources from JNDI on server #1.
    3. - 
    -           Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");
-           ConnectionFactory connectionFactory = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
-
    - -
  3. Create a JMS Connection
    4. - 
    -           connection = connectionFactory.createConnection();
-
    - -
  4. Create a JMS transacted Session
    5. - 
    -           Session session = connection.createSession(true, 0);
-
    - -
  5. Start the connection to ensure delivery occurs
    6. - 
    -           connection.start();
-
    - -
  6. Create a JMS MessageProducer
    7. - 
    -           MessageProducer producer = session.createProducer(queue);
-
    - -
  7. Create a JMS MessageConsumer
    8. - 
    -           MessageConsumer consumer = session.createConsumer(queue);
-
    - -
  8. Send half of the messages, kill the live server and send the remaining messages
    9. - 
    -           sendMessages(session, producer, numMessages, true);
-
    - -

    When server #1 crashes, the client automatically detects the failure and automatically - fails over from server #1 to server #0 (in your real program you wouldn't need to sleep). -

    - -
  9. As failover occurred during transaction, the session has been marked for rollback only and commit will fail
    10. - 
    -           try
-           {
-              session.commit();
-           } catch (TransactionRolledBackException e)
-           {
-              System.err.println("transaction has been rolled back: " + e.getMessage());
-           }
-
    - -
  10. We resend all the messages
    11. - 
    -           sendMessages(session, producer, numMessages, false);
-
    - -
  11. We commit the session successfully: the messages will be all delivered to the activated backup server
    12. - 
    -           session.commit();
-
    - - -
  12. We are now transparently reconnected to server #0, the backup server. - We consume the messages sent before the crash of the live server, commit the session, and check there are no other message on the queue
    13. - 
    -        for (int i = 0; i < numMessages; i++)
-        {
-           TextMessage message0 = (TextMessage)consumer.receive(5000);
-           System.out.println("Got message: " + message0.getText());
-        }
-        session.commit();
-        System.out.println("Other message on the server? " + consumer.receive(5000));
-
    - -
  13. And finally, always remember to close your resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
    14. - - 
    -           finally
-           {
-              if (connection != null)
-              {
-                 connection.close();
-              }
-
-              if (initialContext != null)
-              {
-                 initialContext.close();
-              }
-           }
-
    - -
- - diff --git a/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server0/broker.xml index 4e40497a7b..23cb9f8849 100644 --- a/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -84,7 +82,7 @@ under the License. - +
diff --git a/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server1/broker.xml index 16f62ec035..96ca80b044 100644 --- a/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/replicated-transaction-failover/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -85,7 +83,7 @@ under the License. - +
diff --git a/examples/features/ha/scale-down/pom.xml b/examples/features/ha/scale-down/pom.xml index 008ccc1148..77ea727b99 100644 --- a/examples/features/ha/scale-down/pom.xml +++ b/examples/features/ha/scale-down/pom.xml @@ -98,7 +98,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/scale-down/readme.html b/examples/features/ha/scale-down/readme.html deleted file mode 100644 index 4786db3f14..0000000000 --- a/examples/features/ha/scale-down/readme.html +++ /dev/null @@ -1,51 +0,0 @@ - - - - - ActiveMQ Artemis JMS Scale Down Example - - - - - -

JMS Colocated Failover Shared Store Example

- - 
To run the example, simply type mvn verify from this directory.
- - -

This example demonstrates how you can configure a live server to scale down messages to another live server on shutdown. -

This example starts 2 live servers each one with a connector configured for the other live server.

-

The second live server is killed and its messages are scaled down to the first server on shutdown.

-

The following shows how to configure the live servers to scale down to one another.

- 
-     
-     <ha-policy>
-         <live-only>
-             <scale-down>
-                 <connectors>
-                     <connector-ref>server0-connector</connector-ref>
-                 </connectors>
-             </scale-down>
-         </live-only>
-     </ha-policy>
-     
-
- - diff --git a/examples/features/ha/scale-down/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/scale-down/src/main/resources/activemq/server0/broker.xml index 8f64759826..1be0a4fa6a 100644 --- a/examples/features/ha/scale-down/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/scale-down/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -105,7 +103,7 @@ under the License. - +
diff --git a/examples/features/ha/scale-down/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/scale-down/src/main/resources/activemq/server1/broker.xml index ea9569313f..23437bf113 100644 --- a/examples/features/ha/scale-down/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/scale-down/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -96,7 +94,7 @@ under the License. - +
diff --git a/examples/features/ha/stop-server-failover/pom.xml b/examples/features/ha/stop-server-failover/pom.xml index 4ea900fc13..3abccbfc45 100644 --- a/examples/features/ha/stop-server-failover/pom.xml +++ b/examples/features/ha/stop-server-failover/pom.xml @@ -155,7 +155,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/stop-server-failover/readme.html b/examples/features/ha/stop-server-failover/readme.html deleted file mode 100644 index 9486cd6995..0000000000 --- a/examples/features/ha/stop-server-failover/readme.html +++ /dev/null @@ -1,44 +0,0 @@ - - - - - ActiveMQ Artemis JMS Failover Without Transactions Example - - - - - -

JMS Failover Without Transactions Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- - -

This example demonstrates two servers coupled as a live-backup pair for high availability (HA), and a client - connection failing over from live to backup when the live server is crashed.

-

Failover behavior differs whether the JMS session is transacted or not.

-

When a non-transacted JMS session is used, once and only once delivery is not guaranteed - and it is possible some messages will be lost or delivered twice, depending when the failover to the backup server occurs.

-

It is up to the client to deal with such cases. To ensure once and only once delivery, the client must - use transacted JMS sessions (as shown in the example for failover with transactions).

-

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- - - diff --git a/examples/features/ha/transaction-failover/pom.xml b/examples/features/ha/transaction-failover/pom.xml index df482e9e63..a46a76743a 100644 --- a/examples/features/ha/transaction-failover/pom.xml +++ b/examples/features/ha/transaction-failover/pom.xml @@ -97,7 +97,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/ha/transaction-failover/readme.html b/examples/features/ha/transaction-failover/readme.html deleted file mode 100644 index 15f119f6a3..0000000000 --- a/examples/features/ha/transaction-failover/readme.html +++ /dev/null @@ -1,46 +0,0 @@ - - - - - ActiveMQ Artemis JMS Failover With Transaction Example - - - - - -

JMS Failover With Transaction Example

- - 
To run the example, simply type mvn verify from this directory.
- - -

This example demonstrates two servers coupled as a live-backup pair for high availability (HA), and a client - connection failing over from live to backup when the live server is crashed.

-

Failover behavior differs whether the JMS session is transacter or not.

-

When a transacted JMS session is used, once-and-only once delivery is guaranteed.

-
    -
  • if the failover occurs while there is an in-flight transaction, the transaction will be flagged as rollback only. In that case, the JMS client - will need to retry the transaction work.
    • -
  • if the failover occurs while there is no in-flight transaction, the failover will be transparent to the user.
    • -
-

ActiveMQ Artemis also provides an example for non-transaction failover.

-

For more information on ActiveMQ Artemis failover and HA, and clustering in general, please see the clustering - section of the user manual.

- - diff --git a/examples/features/ha/transaction-failover/src/main/resources/activemq/server0/broker.xml b/examples/features/ha/transaction-failover/src/main/resources/activemq/server0/broker.xml index 4c691a26a6..8617372c9a 100644 --- a/examples/features/ha/transaction-failover/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/ha/transaction-failover/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ../data/bindings @@ -86,7 +84,7 @@ under the License. - +
diff --git a/examples/features/ha/transaction-failover/src/main/resources/activemq/server1/broker.xml b/examples/features/ha/transaction-failover/src/main/resources/activemq/server1/broker.xml index 2500a14c00..450405fbce 100644 --- a/examples/features/ha/transaction-failover/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/ha/transaction-failover/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ../data/bindings @@ -86,7 +84,7 @@ under the License. - +
diff --git a/examples/features/perf/perf/pom.xml b/examples/features/perf/perf/pom.xml index ae011eb241..39d111fbb6 100644 --- a/examples/features/perf/perf/pom.xml +++ b/examples/features/perf/perf/pom.xml @@ -61,9 +61,17 @@ under the License. qpid-jms-client ${qpid.jms.version} - + + + + org.apache.maven.plugins + maven-clean-plugin + + + + server @@ -165,5 +173,16 @@ under the License. + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + diff --git a/examples/features/perf/perf/readme.html b/examples/features/perf/perf/readme.html deleted file mode 100644 index ab2d50e45f..0000000000 --- a/examples/features/perf/perf/readme.html +++ /dev/null @@ -1,39 +0,0 @@ - - - - - ActiveMQ Artemis JMS Queue Selector Example - - - - - -

JMS Simple Performance

- -

To start the server run mvn verify -Pserver

- -

To start the listener run mvn -Plistener verify

- -

To start the sender run mvn -Psender verify

- -

To configure the clients simply edit the perf.properties or client.jndi.properties in the - src/main/resources directory

- - diff --git a/examples/features/perf/soak/README b/examples/features/perf/soak/README deleted file mode 100644 index b69a1acf14..0000000000 --- a/examples/features/perf/soak/README +++ /dev/null @@ -1,85 +0,0 @@ -**************************************************** -* Soak Test For Manual Reconnection of JMS Clients * -**************************************************** - -Running the Soak Tests -======================= - -Run The Server Standalone -========================== - -Use the Profile server - mvn -Pserver verify - -That will create a server under ./target/server0 - - -You can define the property server.dir under the same Profile to create other servers. or you could do it manually if desired using the regular ./artemis create - - $ mvn -Dserver.dir=server1 -Pserver verify - -server1 should contain a copy of configuration equivalent to that found under the server0 director with different -settings. - -To run a server with the same configuration but on a different host. Check out this source on the host machine and -change: -* activemq.remoting.netty.host property in broker.xml -* bindAddress and rmiBindAddress properties in activemq-beans.xml - - $ mvn verify -P server - - -To run the server just start it manually - -Configure Server Dump -===================== - -The server can "dump" info at regular interval. In broker.xml, set - - 10000 - -to have infos every 10s: - -**** Server Dump **** -date: Mon Aug 17 18:19:07 CEST 2009 -free memory: 500,79 MiB -max memory: 1,95 GiB -total memory: 507,13 MiB -available memory: 99,68% -total paging memory: 0,00 B -# of thread: 19 -# of conns: 0 -******************** - -Run The Clients -=============== - -The clients can be run separate from the server using: - - $ mvn verify -Premote - -Parameters are specified in soak.properties. - -The duration of the tests is configured by duration-in-minutes (defaults to 2 minutes, set to --1 to run the test indefinitely). - -To configure the soak properties different to the defaults for the clients, use the system property -To specify the JNDI server to connect to, use the system property jndi.address - - $ mvn verify -Premote -Dsoak.props= -Pjndi.address=jnp:remote.host:1099 - -Every 1000th message, the clients will display their recent activity: - -INFO: received 10000 messages in 5,71s (total: 55s) - -At the end of the run, the sender and receiver will sum up their activity: - -INFO: Received 223364 messages in 2,01 minutes - -Kill The Server And Check Manual Reconnection -============================================== - -You can kill the server (ctl+c or kill -9), the clients are configured to reconnect -indefinitely to the same single server (even in case of clean shutdown) -Once the server restarts, all the clients will resume their activities after reconnecting -to the server. diff --git a/examples/features/perf/soak/pom.xml b/examples/features/perf/soak/pom.xml index 360c2c45c5..f6a65958bc 100644 --- a/examples/features/perf/soak/pom.xml +++ b/examples/features/perf/soak/pom.xml @@ -44,6 +44,15 @@ under the License. ${project.basedir}/../../../.. + + + + org.apache.maven.plugins + maven-clean-plugin + + + + server @@ -157,6 +166,16 @@ under the License. - + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + diff --git a/examples/features/perf/soak/readme.md b/examples/features/perf/soak/readme.md new file mode 100644 index 0000000000..efc93b7c71 --- /dev/null +++ b/examples/features/perf/soak/readme.md @@ -0,0 +1,70 @@ +# Soak Test For Manual Reconnection of JMS Clients * + +## Run The Server Standalone + +Use the Profile server + + mvn -Pserver verify + +That will create a broker under ./target/server0 + +You can define the property server.dir under the same Profile to create other servers. or you could do it manually if desired using the regular ./artemis create + + mvn -Dserver.dir=server1 -Pserver verify + +server1 should contain a copy of configuration equivalent to that found under the server0 director with different +settings. + +To run a broker with the same configuration but on a different host. Check out this source on the host machine and +change: + +* `activemq.remoting.netty.host` property in broker.xml + + mvn verify -P server + +To run the broker just start it manually + +## Configure Server Dump + +The broker can "dump" info at regular interval. In broker.xml, set + + 10000 + +to have infos every 10s: + + **** Server Dump **** + date: Mon Aug 17 18:19:07 CEST 2009 + free memory: 500,79 MiB + max memory: 1,95 GiB + total memory: 507,13 MiB + available memory: 99,68% + total paging memory: 0,00 B + # of thread: 19 + # of conns: 0 + ******************** + +## Run The Clients + +The clients can be run separate from the broker using: + + mvn verify -Premote + +Parameters are specified in soak.properties. + +The duration of the tests is configured by duration-in-minutes (defaults to 2 minutes, set to -1 to run the test indefinitely). + +To configure the soak properties different to the defaults for the clients, use the system property to specify the JNDI broker to connect to, use the system property `jndi.address`: + + mvn verify -Premote -Dsoak.props= -Pjndi.address=jnp:remote.host:1099 + +Every 1000th message, the clients will display their recent activity: + + INFO: received 10000 messages in 5,71s (total: 55s) + +At the end of the run, the sender and receiver will sum up their activity: + + INFO: Received 223364 messages in 2,01 minutes + +## Kill The Server And Check Manual Reconnection + +You can kill the broker (ctl+c or kill -9), the clients are configured to reconnect indefinitely to the same single broker (even in case of clean shutdown) Once the broker restarts, all the clients will resume their activities after reconnecting to the server. diff --git a/examples/features/perf/soak/server0/broker.xml b/examples/features/perf/soak/server0/broker.xml index 7fc57d39d1..a36bd1a79a 100644 --- a/examples/features/perf/soak/server0/broker.xml +++ b/examples/features/perf/soak/server0/broker.xml @@ -16,8 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - +--> + tcp://localhost:61616?tcpNoDelay=false;tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576 @@ -35,7 +35,7 @@ under the License. 30000 - +
diff --git a/examples/features/standard/README.md b/examples/features/standard/README.md index e9d9e36112..c26876f41d 100644 --- a/examples/features/standard/README.md +++ b/examples/features/standard/README.md @@ -7,7 +7,7 @@ To run an individual example firstly cd into the example directory and run mvn verify ``` -Most examples offer a way to start them without creating and starting the server (say if you want to do it manually) +Most examples offer a way to start them without creating and starting the broker (say if you want to do it manually) ```sh mvn verify -PnoServer diff --git a/examples/features/standard/bridge/pom.xml b/examples/features/standard/bridge/pom.xml index e525763557..1e58fdf984 100644 --- a/examples/features/standard/bridge/pom.xml +++ b/examples/features/standard/bridge/pom.xml @@ -160,7 +160,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/standard/bridge/readme.html b/examples/features/standard/bridge/readme.html deleted file mode 100644 index 698c6c2e3b..0000000000 --- a/examples/features/standard/bridge/readme.html +++ /dev/null @@ -1,74 +0,0 @@ - - - - - ActiveMQ Artemis Core Bridge Example - - - - - -

Core Bridge Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates a core bridge deployed on one server, which consumes messages from a - local queue and forwards them to an address on a second server.

- -

Core bridges are used to create message flows between any two ActiveMQ Artemis servers which are remotely separated. - Core bridges are resilient and will cope with temporary connection failure allowing them to be an ideal - choice for forwarding over unreliable connections, e.g. a WAN.

-

They can also be configured with an optional filter expression, and will only forward messages that - match that filter.

-

Furthermore they can be configured to use an optional Transformer class. A user-defined Transformer class - can be specified which is called at forwarding time. This gives the user the opportunity to transform - the message in some ways, e.g. changing its properties or body

-

ActiveMQ Artemis also includes a JMS Bridge. This is similar to a core bridge, but uses the JMS API - and can be used to bridge between any two JMS 1.1 compliant messaging systems. The core bridge is limited to bridging - between ActiveMQ Artemis instances, but may provide better performance than the JMS bridge. The JMS bridge is covered in - a separate example.

-

For more information on bridges, please see the ActiveMQ Artemis user manual.

- -

In this example we will demonstrate a simple sausage factory for aardvarks.

-

We have a JMS queue on server 0 named sausage-factory, and we have a - JMS queue on server 1 named mincing-machine

-

We want to forward any messages that are sent to the sausage-factory queue on server 0, to the mincing-machine - on server 1.

-

We only want to make aardvark sausages, so we only forward messages where the property "name" is set - to "aardvark". It is known that other things, such are Sasquatches are also sent to the sausage-factory and we - want to reject those.

-

Moreover it is known that Aardvarks normally wear blue hats, and it's important that we only make sausages using - Aardvarks with green hats, so on the way we are going transform the property "hat" from "green" to "blue".

-

Here's a snippet from broker.xml showing the bridge configuration

- 
-     
-     <bridge name="my-bridge">
-          <queue-name>jms.queue.sausage-factory</queue-name>
-          <forwarding-address>jms.queue.mincing-machine</forwarding-address>
-          <filter string="name='aardvark'"/>
-          <transformer-class-name>org.apache.activemq.artemis.jms.example.HatColourChangeTransformer</transformer-class-name>
-          <reconnect-attempts>-1</reconnect-attempts>
-          <static-connectors>
-             <connector-ref>remote-connector</connector-ref>
-          </static-connectors>
-     </bridge>
-     
-
- - diff --git a/examples/features/standard/bridge/readme.md b/examples/features/standard/bridge/readme.md new file mode 100644 index 0000000000..66fcb75daf --- /dev/null +++ b/examples/features/standard/bridge/readme.md @@ -0,0 +1,38 @@ +# Core Bridge Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a core bridge deployed on one server, which consumes messages from a local queue and forwards them to an address on a second server. + +Core bridges are used to create message flows between any two ActiveMQ Artemis servers which are remotely separated. Core bridges are resilient and will cope with temporary connection failure allowing them to be an ideal choice for forwarding over unreliable connections, e.g. a WAN. + +They can also be configured with an optional filter expression, and will only forward messages that match that filter. + +Furthermore they can be configured to use an optional Transformer class. A user-defined Transformer class can be specified which is called at forwarding time. This gives the user the opportunity to transform the message in some ways, e.g. changing its properties or body + +ActiveMQ Artemis also includes a **JMS Bridge**. This is similar to a core bridge, but uses the JMS API and can be used to bridge between any two JMS 1.1 compliant messaging systems. The core bridge is limited to bridging between ActiveMQ Artemis instances, but may provide better performance than the JMS bridge. The JMS bridge is covered in a separate example. + +For more information on bridges, please see the ActiveMQ Artemis user manual. + +In this example we will demonstrate a simple sausage factory for aardvarks. + +We have a JMS queue on broker 0 named `sausage-factory`, and we have a JMS queue on broker 1 named `mincing-machine` + +We want to forward any messages that are sent to the `sausage-factory` queue on broker 0, to the `mincing-machine` on broker 1. + +We only want to make aardvark sausages, so we only forward messages where the property `name` is set to `aardvark`. It is known that other things, such are Sasquatches are also sent to the `sausage-factory` and we want to reject those. + +Moreover it is known that Aardvarks normally wear blue hats, and it's important that we only make sausages using Aardvarks with green hats, so on the way we are going transform the property `hat` from `green` to `blue`. + +Here's a snippet from `broker.xml` showing the bridge configuration + + + jms.queue.sausage-factory + jms.queue.mincing-machine + + org.apache.activemq.artemis.jms.example.HatColourChangeTransformer + -1 + + remote-connector + + \ No newline at end of file diff --git a/examples/features/standard/bridge/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/bridge/src/main/resources/activemq/server0/broker.xml index afb3cd67a3..50471ba4b9 100644 --- a/examples/features/standard/bridge/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/bridge/src/main/resources/activemq/server0/broker.xml @@ -16,7 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> +--> + @@ -72,7 +73,7 @@ under the License. - +
diff --git a/examples/features/standard/bridge/src/main/resources/activemq/server1/broker.xml b/examples/features/standard/bridge/src/main/resources/activemq/server1/broker.xml index 8952c624be..c260d7cd79 100644 --- a/examples/features/standard/bridge/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/standard/bridge/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -47,7 +45,7 @@ under the License. - +
diff --git a/examples/features/standard/broker-plugin/pom.xml b/examples/features/standard/broker-plugin/pom.xml index 1c89064b6b..0cd1da5e00 100644 --- a/examples/features/standard/broker-plugin/pom.xml +++ b/examples/features/standard/broker-plugin/pom.xml @@ -120,7 +120,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/standard/broker-plugin/readme.html b/examples/features/standard/broker-plugin/readme.html deleted file mode 100644 index e76ae088ff..0000000000 --- a/examples/features/standard/broker-plugin/readme.html +++ /dev/null @@ -1,34 +0,0 @@ - - - - - ActiveMQ Artemis JMS QueueBrowser Example - - - - - -

Broker Plugin Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

AMQP Messages should be by definition immutable at the server's. So, we don't recommend changing message contents. - However if you require you can use this example as a basis for adding properties on making changes

- - diff --git a/examples/features/standard/broker-plugin/readme.md b/examples/features/standard/broker-plugin/readme.md new file mode 100644 index 0000000000..8862e73161 --- /dev/null +++ b/examples/features/standard/broker-plugin/readme.md @@ -0,0 +1,5 @@ +# Broker Plugin Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +AMQP Messages should be by definition immutable at the server's. So, we don't recommend changing message contents. However if you require you can use this example as a basis for adding properties on making changes \ No newline at end of file diff --git a/examples/features/standard/browser/pom.xml b/examples/features/standard/browser/pom.xml index b6bdfe2af9..af2274e8d9 100644 --- a/examples/features/standard/browser/pom.xml +++ b/examples/features/standard/browser/pom.xml @@ -103,7 +103,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/browser/readme.html b/examples/features/standard/browser/readme.html deleted file mode 100644 index 9f9e01a1cc..0000000000 --- a/examples/features/standard/browser/readme.html +++ /dev/null @@ -1,40 +0,0 @@ - - - - - ActiveMQ Artemis JMS QueueBrowser Example - - - - - -

JMS QueueBrowser Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example shows you how to use a JMS QueueBrowser with ActiveMQ Artemis.
- Queues are a standard part of JMS, please consult the JMS 1.1 specification for full details.
- A QueueBrowser is used to look at messages on the queue without removing them. - It can scan the entire content of a queue or only messages matching a message selector.

-

- The example will send 2 messages on a queue, use a QueueBrowser to browse - the queue (looking at the message without removing them) and finally consume the 2 messages -

- - diff --git a/examples/features/standard/browser/readme.md b/examples/features/standard/browser/readme.md new file mode 100644 index 0000000000..4f9cf3122e --- /dev/null +++ b/examples/features/standard/browser/readme.md @@ -0,0 +1,11 @@ +# JMS QueueBrowser Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to use a JMS [QueueBrowser](http://java.sun.com/javaee/5/docs/api/javax/jms/QueueBrowser.html) with ActiveMQ Artemis. + +Queues are a standard part of JMS, please consult the JMS 1.1 specification for full details. + +A QueueBrowser is used to look at messages on the queue without removing them. It can scan the entire content of a queue or only messages matching a message selector. + +The example will send 2 messages on a queue, use a QueueBrowser to browse the queue (looking at the message without removing them) and finally consume the 2 messages. \ No newline at end of file diff --git a/examples/features/standard/cdi/readme.md b/examples/features/standard/cdi/readme.md index 7e981ca543..3cf4c68f1b 100644 --- a/examples/features/standard/cdi/readme.md +++ b/examples/features/standard/cdi/readme.md @@ -17,7 +17,7 @@ # under the License. # --> -# ActiveMQ Artemis CDI Integration Example +# CDI Example This is a simple example that demonstrates how to use CDI to integrate with ActiveMQ Artemis on the client side. It is designed mainly for connecting to a remote broker rather than embedding within your application. diff --git a/examples/features/standard/client-kickoff/pom.xml b/examples/features/standard/client-kickoff/pom.xml index 5b51591e9e..4d3d2d342d 100644 --- a/examples/features/standard/client-kickoff/pom.xml +++ b/examples/features/standard/client-kickoff/pom.xml @@ -105,7 +105,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/client-kickoff/readme.html b/examples/features/standard/client-kickoff/readme.html deleted file mode 100644 index 67d17db7d0..0000000000 --- a/examples/features/standard/client-kickoff/readme.html +++ /dev/null @@ -1,54 +0,0 @@ - - - - - ActiveMQ Artemis Client Kickoff Example - - - - - -

Client Kickoff Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example shows how to kick off a client connected to ActiveMQ - using JMX

- -

The example will connect to ActiveMQ Artemis. Using JMX, we will list the remote addresses connected to the - server and close the corresponding connections. The client will be kicked off from ActiveMQ Artemis receiving - an exception that its JMS connection was interrupted.

- -

Example configuration

- -

ActiveMQ Artemis exposes its managed resources by default on the platform MBeanServer.

-

To access this MBeanServer remotely, the Java Virtual machine must be started with system properties: - 

-             -Dcom.sun.management.jmxremote
-             -Dcom.sun.management.jmxremote.port=3000
-             -Dcom.sun.management.jmxremote.ssl=false
-             -Dcom.sun.management.jmxremote.authenticate=false
-
-

These properties are explained in the Java management guide - (please note that for this example, we will disable user authentication for simplicity).

-

With these properties, ActiveMQ Artemis server will be manageable remotely using standard JMX URL on port 3000.

-

- - diff --git a/examples/features/standard/client-kickoff/readme.md b/examples/features/standard/client-kickoff/readme.md new file mode 100644 index 0000000000..b822df9218 --- /dev/null +++ b/examples/features/standard/client-kickoff/readme.md @@ -0,0 +1,22 @@ +# Client Kickoff Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how to kick off a client connected to ActiveMQ using [JMX](http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/) + +The example will connect to ActiveMQ Artemis. Using JMX, we will list the remote addresses connected to the broker and close the corresponding connections. The client will be kicked off from ActiveMQ Artemis receiving an exception that its JMS connection was interrupted. + +## Example configuration + +ActiveMQ Artemis exposes its managed resources by default on the platform MBeanServer. + +To access this MBeanServer remotely, the Java Virtual machine must be started with system properties: + + -Dcom.sun.management.jmxremote + -Dcom.sun.management.jmxremote.port=3000 + -Dcom.sun.management.jmxremote.ssl=false + -Dcom.sun.management.jmxremote.authenticate=false + +These properties are explained in the Java [management guide](http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html#gdenl) (please note that for this example, we will disable user authentication for simplicity). + +With these properties, ActiveMQ Artemis broker will be manageable remotely using standard JMX URL on port `3000`. \ No newline at end of file diff --git a/examples/features/standard/client-kickoff/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/client-kickoff/src/main/resources/activemq/server0/broker.xml index 455eabef26..9530a31ead 100644 --- a/examples/features/standard/client-kickoff/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/client-kickoff/src/main/resources/activemq/server0/broker.xml @@ -16,9 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - +--> + ./data/bindings @@ -36,7 +35,5 @@ under the License. tcp://localhost:61616 - - diff --git a/examples/features/standard/consumer-rate-limit/pom.xml b/examples/features/standard/consumer-rate-limit/pom.xml index 791063c1c2..6357f20628 100644 --- a/examples/features/standard/consumer-rate-limit/pom.xml +++ b/examples/features/standard/consumer-rate-limit/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/consumer-rate-limit/readme.html b/examples/features/standard/consumer-rate-limit/readme.html deleted file mode 100644 index 415de007ba..0000000000 --- a/examples/features/standard/consumer-rate-limit/readme.html +++ /dev/null @@ -1,47 +0,0 @@ - - - - - ActiveMQ Artemis JMS Message Consumer Rate Limiting - - - - - -

JMS Message Consumer Rate Limiting

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

With ActiveMQ Artemis you can specify a maximum consume rate at which a JMS MessageConsumer will consume messages. - This can be specified when creating or configuring the connection factory. See jndi.properties.

-

If this value is specified then ActiveMQ Artemis will ensure that messages are never consumed at a rate higher than - the specified rate. This is a form of consumer throttling.

-

Example step-by-step

-

In this example we specify a consumer-max-rate of 10 messages per second in the jndi.properties - file when configuring the connection factory:

- 
-     
-connectionFactory.ConnectionFactory=tcp://localhost:61616?consumerMaxRate=10
-     
-
-

We then simply consume as many messages as we can in 10 seconds and note how many messages are actually consumed.

-

We note that the number of messages consumed per second never exceeds the specified value of 10 messages per second.

- - - diff --git a/examples/features/standard/consumer-rate-limit/readme.md b/examples/features/standard/consumer-rate-limit/readme.md new file mode 100644 index 0000000000..923c068ce8 --- /dev/null +++ b/examples/features/standard/consumer-rate-limit/readme.md @@ -0,0 +1,17 @@ +# JMS Message Consumer Rate Limiting + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +With ActiveMQ Artemis you can specify a maximum consume rate at which a JMS MessageConsumer will consume messages. This can be specified when creating or configuring the connection factory. See `jndi.properties`. + +If this value is specified then ActiveMQ Artemis will ensure that messages are never consumed at a rate higher than the specified rate. This is a form of consumer _throttling_. + +## Example step-by-step + +In this example we specify a `consumer-max-rate` of `10` messages per second in the `jndi.properties` file when configuring the connection factory: + + connectionFactory.ConnectionFactory=tcp://localhost:61616?consumerMaxRate=10 + +We then simply consume as many messages as we can in 10 seconds and note how many messages are actually consumed. + +We note that the number of messages consumed per second never exceeds the specified value of `10` messages per second. \ No newline at end of file diff --git a/examples/features/standard/dead-letter/pom.xml b/examples/features/standard/dead-letter/pom.xml index 288f06da5b..a67975af60 100644 --- a/examples/features/standard/dead-letter/pom.xml +++ b/examples/features/standard/dead-letter/pom.xml @@ -103,7 +103,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/dead-letter/readme.html b/examples/features/standard/dead-letter/readme.html deleted file mode 100644 index e293936b9d..0000000000 --- a/examples/features/standard/dead-letter/readme.html +++ /dev/null @@ -1,66 +0,0 @@ - - - - - ActiveMQ Artemis Dead Letter Example - - - - - -

Dead Letter Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example shows you how to define and deal with dead letter messages.

-

Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume them is rolled back). - Such a message goes back to the JMS destination ready to be redelivered. - However, this means it is possible for a message to be delivered again and again without any success and remain in the destination, clogging the system.

-

To prevent this, messaging systems define dead letter messages: after a specified unsuccessful delivery attempts, the message is removed from the destination - and instead routed to a dead letter address where they can be consumed for further investigation. -

- The example will show how to configure ActiveMQ Artemis to route a message to a dead letter address after 3 unsuccessful delivery attempts.
- The example will send 1 message to a queue. We will deliver the message 3 times and rollback the session every time.
- On the 4th attempt, there won't be any message to consume: it will have been moved to a dead letter address.
- We will then consume this dead letter message. -

-

Example setup

-

Dead letter addresses and maximum delivery attempts are defined in the configuration file broker.xml:

- 
-         <address-setting match="jms.queue.exampleQueue">
-            <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
-            <max-delivery-attempts>3</max-delivery-attempts>
-         </address-setting>
-         
-
-

This configuration will moved dead letter messages from exampleQueue to the deadLetterQueue.

-

ActiveMQ Artemis allows to specify either a Queue by prefixing the dead-letter-address with jms.queue. - or a Topic by prefixing with jms.topic..
- In this example, we will use a Queue to hold the dead letter messages.

-

The maximum attempts of delivery is 3. Once this figure is reached, a message is considered a dead letter message and is moved to - the deadLetterQueue. -

Since we want to consume messages from this deadLetterQueue, we also need to add a JNDI binding to perform a lookup. - This is configured in activemq-jms.xml

- 
-         <queue name="deadLetterQueue">
-            <entry name="/queue/deadLetterQueue"/>
-         </queue>
-
- - diff --git a/examples/features/standard/dead-letter/readme.md b/examples/features/standard/dead-letter/readme.md new file mode 100644 index 0000000000..68a5adc184 --- /dev/null +++ b/examples/features/standard/dead-letter/readme.md @@ -0,0 +1,32 @@ +# Dead Letter Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to define and deal with dead letter messages. + +Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume them is rolled back). Such a message goes back to the JMS destination ready to be redelivered. However, this means it is possible for a message to be delivered again and again without any success and remain in the destination, clogging the system. + +To prevent this, messaging systems define dead letter messages: after a specified unsuccessful delivery attempts, the message is removed from the destination and instead routed to a _dead letter address_ where they can be consumed for further investigation. + +The example will show how to configure ActiveMQ Artemis to route a message to a dead letter address after 3 unsuccessful delivery attempts. + +The example will send 1 message to a queue. We will deliver the message 3 times and rollback the session every time. + +On the 4th attempt, there won't be any message to consume: it will have been moved to a _dead letter address_. + +We will then consume this dead letter message. + +## Example setup + +_Dead letter addresses_ and _maximum delivery attempts_ are defined in the configuration file [broker.xml](src/main/resources/activemq/server0/broker.xml): + + + deadLetterQueue + 3 + + +This configuration will moved dead letter messages from `exampleQueue` to the `deadLetterQueue`. + +ActiveMQ Artemis allows to specify either an address or a queue. In this example, we will use a queue to hold the dead letter messages. + +The maximum attempts of delivery is `3`. Once this figure is reached, a message is considered a dead letter message and is moved to the `deadLetterQueue`. \ No newline at end of file diff --git a/examples/features/standard/dead-letter/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/dead-letter/src/main/resources/activemq/server0/broker.xml index f3675a7c57..b01abf652b 100644 --- a/examples/features/standard/dead-letter/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/dead-letter/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -57,7 +55,7 @@ under the License. - +
diff --git a/examples/features/standard/delayed-redelivery/pom.xml b/examples/features/standard/delayed-redelivery/pom.xml index 6d225ba275..4f9737d3f1 100644 --- a/examples/features/standard/delayed-redelivery/pom.xml +++ b/examples/features/standard/delayed-redelivery/pom.xml @@ -103,7 +103,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/standard/delayed-redelivery/readme.html b/examples/features/standard/delayed-redelivery/readme.html deleted file mode 100644 index e535c47120..0000000000 --- a/examples/features/standard/delayed-redelivery/readme.html +++ /dev/null @@ -1,56 +0,0 @@ - - - - - ActiveMQ Artemis Delayed Redelivery Example - - - - - -

Delayed Redelivery Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example demonstrates how ActiveMQ Artemis can be configured to provide a delayed redelivery in the case - where a message needs to be redelivered.

-

Delaying redelivery can often be useful in the case that clients regularly fail or roll-back. Without a delayed - redelivery, the system can get into a "thrashing" state, with delivery being attempted, the client rolling back, and - delivery being re-attempted ad infinitum in quick succession, using up valuable CPU and network resources.

-

Re-delivery occurs when the session is closed with unacknowledged messages. The unacknowledged messages will - be redelivered.

-

By providing a redelivery delay, it can be specified that a delay of, say, 10 seconds is implemented between rollback - and redelivery. The specific delay is configurable on both a global and per destination level, by using wild-card - matching on the address settings.

- -

Example setup

-

Redelivery delay is specified in the configuration file broker.xml:

-

In this example we set the redelivery delay to 5 seconds for the specific example queue. We could set redelivery delay on - on multiple queues by specifying a wild-card in the match, e.g. match="jms.#" would apply the settings - to all JMS queues and topics.

-

We then consume a message in a transacted session, and rollback, and note that the message is not redelivered until - after 5 seconds.

- 
-         <address-setting match="jms.queue.exampleQueue">
-            <redelivery-delay>5000</redelivery-delay>
-         </address-setting>
-         
-
- - diff --git a/examples/features/standard/delayed-redelivery/readme.md b/examples/features/standard/delayed-redelivery/readme.md new file mode 100644 index 0000000000..cd3b529fa3 --- /dev/null +++ b/examples/features/standard/delayed-redelivery/readme.md @@ -0,0 +1,23 @@ +# Delayed Redelivery Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates how ActiveMQ Artemis can be configured to provide a delayed redelivery in the case where a message needs to be redelivered. + +Delaying redelivery can often be useful in the case that clients regularly fail or roll-back. Without a delayed redelivery, the system can get into a "thrashing" state, with delivery being attempted, the client rolling back, and delivery being re-attempted ad infinitum in quick succession, using up valuable CPU and network resources. + +Re-delivery occurs when the session is closed with unacknowledged messages. The unacknowledged messages will be redelivered. + +By providing a redelivery delay, it can be specified that a delay of, say, 10 seconds is implemented between rollback and redelivery. The specific delay is configurable on both a global and per destination level, by using wild-card matching on the address settings. + +## Example setup + +Redelivery delay is specified in the configuration file [broker.xml](src/main/resources/activemq/server0/broker.xml): + +In this example we set the redelivery delay to 5 seconds for the specific example queue. We could set redelivery delay on on multiple queues by specifying a wild-card in the match, e.g. `match="jms.#"` would apply the settings to all JMS queues and topics. + +We then consume a message in a transacted session, and rollback, and note that the message is not redelivered until after 5 seconds. + + + 5000 + \ No newline at end of file diff --git a/examples/features/standard/delayed-redelivery/src/main/java/org/apache/activemq/artemis/jms/example/DelayedRedeliveryExample.java b/examples/features/standard/delayed-redelivery/src/main/java/org/apache/activemq/artemis/jms/example/DelayedRedeliveryExample.java index e70fd6cfcf..9d69154b78 100644 --- a/examples/features/standard/delayed-redelivery/src/main/java/org/apache/activemq/artemis/jms/example/DelayedRedeliveryExample.java +++ b/examples/features/standard/delayed-redelivery/src/main/java/org/apache/activemq/artemis/jms/example/DelayedRedeliveryExample.java @@ -29,7 +29,7 @@ import javax.naming.InitialContext; * This example demonstrates how ActiveMQ Artemis can be configured with a redelivery delay in the event a message * is redelivered. * - * Please see the readme.html for more information + * Please see the readme for more information */ public class DelayedRedeliveryExample { diff --git a/examples/features/standard/delayed-redelivery/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/delayed-redelivery/src/main/resources/activemq/server0/broker.xml index d86844b39a..cf83c7d1fe 100644 --- a/examples/features/standard/delayed-redelivery/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/delayed-redelivery/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -56,7 +54,7 @@ under the License. - +
diff --git a/examples/features/standard/divert/pom.xml b/examples/features/standard/divert/pom.xml index 9745afda43..c8fa81a432 100644 --- a/examples/features/standard/divert/pom.xml +++ b/examples/features/standard/divert/pom.xml @@ -152,7 +152,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/divert/readme.html b/examples/features/standard/divert/readme.html deleted file mode 100644 index 63fb71073c..0000000000 --- a/examples/features/standard/divert/readme.html +++ /dev/null @@ -1,119 +0,0 @@ - - - - - ActiveMQ Artemis Divert Example - - - - - -

Divert Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

ActiveMQ Artemis diverts allow messages to be transparently "diverted" from one address to another - with just some simple configuration defined on the server side.

-

Diverts can be defined to be exclusive or non-exclusive.

-

With an exclusive divert the message is intercepted and does not get sent to the queues originally - bound to that address - it only gets diverted.

-

With a non-exclusive divert the message continues to go to the queues bound to the address, - but also a copy of the message gets sent to the address specified in the divert. Consequently non-exclusive - diverts can be used to "snoop" on another address

-

Diverts can also be configured to have an optional filter. If specified then only matching messages - will be diverted.

-

Diverts can be configured to apply a Transformer. If specified, all diverted messages will have the - opportunity of being transformed by the Transformer.

-

Diverts are a very sophisticated concept, which when combined with bridges can be used to create - interesting and complex routings. The set of diverts can be thought of as a type of routing table - for messages.

- -

Example step-by-step

-

In this example we will imagine a fictitious company which has two offices; one in London and another in New York.

-

The company accepts orders for it's products only at it's London office, and also generates price-updates - for it's products, also only from it's London office. However only the New York office is interested in receiving - price updates for New York products. Any prices for New York products need to be forwarded to the New York office.

-

There is an unreliable WAN linking the London and New York offices.

-

The company also requires a copy of any order received to be available to be inspected by management.

-

In order to achieve this, we will create a queue orderQueue on the London server in to which orders arrive.

-

We will create a topic, spyTopic on the London server, and there will be two subscribers both in London.

-

We will create a non-exclusive divert on the London server which will siphon off a copy of each order - received to the topic spyTopic.

-

Here's the xml config for that divert, from broker.xml

- 
-        
-     <divert name="order-divert">
-         <address>jms.queue.orders</address>
-         <forwarding-address>jms.topic.spyTopic</forwarding-address>
-         <exclusive>false</exclusive>
-      </divert>
-         
-
-

For the prices we will create a topic on the London server, priceUpdates to which all price updates - are sent. We will create another topic on the New York server newYorkPriceUpdates to which all New York - price updates need to be forwarded.

-

Diverts can only be used to divert messages from one local address to another local address - so we cannot divert directly to an address on another server.

-

Instead we divert to a local store and forward queue they we define in the configuration. This is just a normal queue - that we use for storing messages before forwarding to another node.

-

Here's the configuration for it:

- 
-        
-     <queues>
-        <queue name="jms.queue.priceForwarding">
-           <address>jms.queue.priceForwarding</address>
-        </queue>
-     </queues>
-         
-
-

Here's the configuration for the divert:

- 
-        
-     <divert name="prices-divert">
-	     <address>jms.topic.priceUpdates</address>
-	     <forwarding-address>jms.queue.priceForwarding</forwarding-address>
-	     <filter string="office='New York'"/>
-	     <transformer-class-name>org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer</transformer-class-name>
-	     <exclusive>true</exclusive>
-	  </divert>
-	     
-
-

Note we specify a filter in the divert, so only New York prices get diverted. We also specify a Transformer class - since we are going to insert a header in the message at divert time, recording the time the diversion happened.

-

And finally we define a bridge that moves messages from the local queue to the address on the New York server. - Bridges move messages from queues to remote addresses and are ideal to use when the target server may be stopped and - started independently, and/or the network might be unreliable. Bridges guarantee once and only once delivery - of messages from their source queues to their target addresses.

-

Here is the bridge configuration:

- 
-	     
-	  <bridges>
-	     <bridge name="price-forward-bridge">
-	        <queue-name>jms.queue.priceForwarding</queue-name>
-	        <forwarding-address>jms.topic.newYorkPriceUpdates</forwarding-address>
-	        <reconnect-attempts>-1</reconnect-attempts>
-          <static-connectors>
-             <connector-ref>newyork-connector</connector-ref>
-          </static-connectors>
-	     </bridge>
-      </bridges>
-         
-
- - diff --git a/examples/features/standard/divert/readme.md b/examples/features/standard/divert/readme.md new file mode 100644 index 0000000000..86510243f7 --- /dev/null +++ b/examples/features/standard/divert/readme.md @@ -0,0 +1,82 @@ +# Divert Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +ActiveMQ Artemis diverts allow messages to be transparently "diverted" from one address to another with just some simple configuration defined on the broker side. + +Diverts can be defined to be **exclusive** or **non-exclusive**. + +With an **exclusive** divert the message is intercepted and does not get sent to the queues originally bound to that address - it only gets diverted. + +With a **non-exclusive** divert the message continues to go to the queues bound to the address, but also a **copy** of the message gets sent to the address specified in the divert. Consequently non-exclusive diverts can be used to "snoop" on another address + +Diverts can also be configured to have an optional filter. If specified then only matching messages will be diverted. + +Diverts can be configured to apply a Transformer. If specified, all diverted messages will have the opportunity of being transformed by the Transformer. + +Diverts are a very sophisticated concept, which when combined with bridges can be used to create interesting and complex routings. The set of diverts can be thought of as a type of _routing table_ for messages. + +## Example step-by-step + +In this example we will imagine a fictitious company which has two offices; one in London and another in New York. + +The company accepts orders for it's products only at it's London office, and also generates price-updates for it's products, also only from it's London office. However only the New York office is interested in receiving price updates for New York products. Any prices for New York products need to be forwarded to the New York office. + +There is an unreliable WAN linking the London and New York offices. + +The company also requires a copy of any order received to be available to be inspected by management. + +In order to achieve this, we will create a queue `orderQueue` on the London broker in to which orders arrive. + +We will create a topic, `spyTopic` on the London server, and there will be two subscribers both in London. + +We will create a _non-exclusive_ divert on the London broker which will siphon off a copy of each order received to the topic `spyTopic`. + +Here's the xml config for that divert, from `broker.xml` + + +
orders
+ spyTopic + false + + +For the prices we will create a topic on the London server, `priceUpdates` to which all price updates are sent. We will create another topic on the New York broker `newYorkPriceUpdates` to which all New York price updates need to be forwarded. + +Diverts can only be used to divert messages from one **local** address to another **local** address so we cannot divert directly to an address on another server. + +Instead we divert to a local _store and forward queue_ they we define in the configuration. This is just a normal queue that we use for storing messages before forwarding to another node. + +Here's the configuration for it: + +
+ + + +
+ +Here's the configuration for the divert: + + +
priceUpdates
+ priceForwarding + + org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer + true + + +Note we specify a filter in the divert, so only New York prices get diverted. We also specify a Transformer class since we are going to insert a header in the message at divert time, recording the time the diversion happened. + +And finally we define a bridge that moves messages from the local queue to the address on the New York server. Bridges move messages from queues to remote addresses and are ideal to use when the target broker may be stopped and started independently, and/or the network might be unreliable. Bridges guarantee once and only once delivery of messages from their source queues to their target addresses. + +Here is the bridge configuration: + + + + priceForwarding + newYorkPriceUpdates + -1 + + newyork-connector + + + \ No newline at end of file diff --git a/examples/features/standard/divert/src/main/java/org/apache/activemq/artemis/jms/example/DivertExample.java b/examples/features/standard/divert/src/main/java/org/apache/activemq/artemis/jms/example/DivertExample.java index 98740fef32..babb06971c 100644 --- a/examples/features/standard/divert/src/main/java/org/apache/activemq/artemis/jms/example/DivertExample.java +++ b/examples/features/standard/divert/src/main/java/org/apache/activemq/artemis/jms/example/DivertExample.java @@ -33,7 +33,7 @@ import org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory; * This examples demonstrates the use of ActiveMQ Artemis "Diverts" to transparently divert or copy messages * from one address to another. * - * Please see the readme.html for more information. + * Please see the readme for more information. */ public class DivertExample { diff --git a/examples/features/standard/divert/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/divert/src/main/resources/activemq/server0/broker.xml index 5e36d6eb25..a6fcc0b7d7 100644 --- a/examples/features/standard/divert/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/divert/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -96,18 +94,15 @@ under the License. - +
- - - - +
- +
diff --git a/examples/features/standard/divert/src/main/resources/activemq/server1/broker.xml b/examples/features/standard/divert/src/main/resources/activemq/server1/broker.xml index 4b2ee1301d..9bf01ef093 100644 --- a/examples/features/standard/divert/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/standard/divert/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -50,7 +48,7 @@ under the License. - +
diff --git a/examples/features/standard/durable-subscription/pom.xml b/examples/features/standard/durable-subscription/pom.xml index 7c537bfd8d..578117f73d 100644 --- a/examples/features/standard/durable-subscription/pom.xml +++ b/examples/features/standard/durable-subscription/pom.xml @@ -103,7 +103,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/durable-subscription/readme.html b/examples/features/standard/durable-subscription/readme.html deleted file mode 100644 index 61b591fc97..0000000000 --- a/examples/features/standard/durable-subscription/readme.html +++ /dev/null @@ -1,39 +0,0 @@ - - - - - ActiveMQ Artemis JMS Durable Subscription Example - - - - - -

JMS Durable Subscription Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
-

This example demonstrates how to use a durable subscription with ActiveMQ Artemis.

-

Durable subscriptions are a standard part of JMS, please consult the JMS 1.1 specification for full details.

-

Unlike non durable subscriptions, the key function of durable subscriptions is that the messages contained in them - persist longer than the lifetime of the subscriber - i.e. they will accumulate messages sent to the topic even - if the subscriber is not currently connected. They will also survive server restarts. Note that for the messages to - be persisted, the messages sent to them must be marked as persistent messages.

- - - diff --git a/examples/features/standard/durable-subscription/readme.md b/examples/features/standard/durable-subscription/readme.md new file mode 100644 index 0000000000..6b74040058 --- /dev/null +++ b/examples/features/standard/durable-subscription/readme.md @@ -0,0 +1,9 @@ +# JMS Durable Subscription Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates how to use a durable subscription with ActiveMQ Artemis. + +Durable subscriptions are a standard part of JMS, please consult the JMS 1.1 specification for full details. + +Unlike non durable subscriptions, the key function of durable subscriptions is that the messages contained in them persist longer than the lifetime of the subscriber - i.e. they will accumulate messages sent to the topic even if the subscriber is not currently connected. They will also survive broker restarts. Note that for the messages to be persisted, the messages sent to them must be marked as persistent messages. \ No newline at end of file diff --git a/examples/features/standard/durable-subscription/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/durable-subscription/src/main/resources/activemq/server0/broker.xml index d3352b1e77..91d733a4d0 100644 --- a/examples/features/standard/durable-subscription/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/durable-subscription/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -50,7 +48,7 @@ under the License. - +
diff --git a/examples/features/standard/embedded-simple/pom.xml b/examples/features/standard/embedded-simple/pom.xml index 40e9fc209d..610934b746 100644 --- a/examples/features/standard/embedded-simple/pom.xml +++ b/examples/features/standard/embedded-simple/pom.xml @@ -77,7 +77,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/embedded-simple/readme.html b/examples/features/standard/embedded-simple/readme.html deleted file mode 100644 index dae7359ae1..0000000000 --- a/examples/features/standard/embedded-simple/readme.html +++ /dev/null @@ -1,35 +0,0 @@ - - - - - ActiveMQ Artemis Embedded Broker with External Config Example - - - - - -

Embedded Broker with External Config Example

- 
To run the example, simply type mvn verify from this directory
- -

This examples shows how to setup and run an embedded broker using ActiveMQ Artemis.

-

ActiveMQ Artemis was designed using POJOs (Plain Old Java Objects) which means embedding ActiveMQ Artemis in your own application is as simple as instantiating a few objects.

-

This example uses an external configuration file (i.e. broker.xml).

- - diff --git a/examples/features/standard/embedded-simple/readme.md b/examples/features/standard/embedded-simple/readme.md new file mode 100644 index 0000000000..7b85d02c39 --- /dev/null +++ b/examples/features/standard/embedded-simple/readme.md @@ -0,0 +1,9 @@ +# Embedded Broker with External Config Example + +To run the example, simply type **mvn verify** from this directory. + +This examples shows how to setup and run an embedded broker using ActiveMQ Artemis. + +ActiveMQ Artemis was designed using POJOs (Plain Old Java Objects) which means embedding ActiveMQ Artemis in your own application is as simple as instantiating a few objects. + +This example uses an external configuration file (i.e. broker.xml). \ No newline at end of file diff --git a/examples/features/standard/embedded-simple/src/main/resources/broker.xml b/examples/features/standard/embedded-simple/src/main/resources/broker.xml index a67720c30d..52e32debd1 100644 --- a/examples/features/standard/embedded-simple/src/main/resources/broker.xml +++ b/examples/features/standard/embedded-simple/src/main/resources/broker.xml @@ -20,10 +20,7 @@ under the License. - - - + xsi:schemaLocation="urn:activemq /schema/artemis-configuration.xsd"> false diff --git a/examples/features/standard/embedded/pom.xml b/examples/features/standard/embedded/pom.xml index ff99767ff3..a69522c791 100644 --- a/examples/features/standard/embedded/pom.xml +++ b/examples/features/standard/embedded/pom.xml @@ -77,7 +77,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/embedded/readme.html b/examples/features/standard/embedded/readme.html deleted file mode 100644 index d277c911fc..0000000000 --- a/examples/features/standard/embedded/readme.html +++ /dev/null @@ -1,36 +0,0 @@ - - - - - ActiveMQ Artemis Embedded Broker with Programmatic Config Example - - - - - -

Embedded Broker with Programmatic Config Example

- 
To run the example, simply type mvn verify from this directory
- -

This examples shows how to setup and run an embedded broker using ActiveMQ Artemis.

-

ActiveMQ Artemis was designed using POJOs (Plain Old Java Objects) which means embedding ActiveMQ Artemis in your own application - is as simple as instantiating a few objects.

-

This example does not use any configuration files. The server is configured using POJOs and can be easily ported to any dependency injection framework.

- - diff --git a/examples/features/standard/embedded/readme.md b/examples/features/standard/embedded/readme.md new file mode 100644 index 0000000000..c70c044ba9 --- /dev/null +++ b/examples/features/standard/embedded/readme.md @@ -0,0 +1,9 @@ +# Embedded Broker with Programmatic Config Example + +To run the example, simply type **mvn verify** from this directory. + +This examples shows how to setup and run an embedded broker using ActiveMQ Artemis. + +ActiveMQ Artemis was designed using POJOs (Plain Old Java Objects) which means embedding ActiveMQ Artemis in your own application is as simple as instantiating a few objects. + +This example does not use any configuration files. The broker is configured using POJOs and can be easily ported to any dependency injection framework. \ No newline at end of file diff --git a/examples/features/standard/expiry/pom.xml b/examples/features/standard/expiry/pom.xml index 4c8f1f7a9c..84c4641fa4 100644 --- a/examples/features/standard/expiry/pom.xml +++ b/examples/features/standard/expiry/pom.xml @@ -103,7 +103,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/expiry/readme.html b/examples/features/standard/expiry/readme.html deleted file mode 100644 index d13cac068a..0000000000 --- a/examples/features/standard/expiry/readme.html +++ /dev/null @@ -1,61 +0,0 @@ - - - - - ActiveMQ Artemis Message Expiration Example - - - - - -

JMS Expiration Example

- 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example shows you how to configure ActiveMQ Artemis so messages are expipired after a certain time.

-

Messages can be retained in the messaging system for a limited period of time before being removed. - JMS specification states that clients should not receive messages that have been expired (but it does not guarantee this will not happen).

-

ActiveMQ Artemis can assign a expiry address to a given queue so that when messages are expired, they are removed from the queue and - routed to this address. These "expired" messages can later be consumed for further inspection. -

- The example will send 1 message with a short time-to-live to a queue. We will wait for the message to expire and checks that the message - is no longer in the queue it was sent to. - We will instead consume it from an expiry queue where it was moved when it expired. -

-

Example setup

-

Expiry destinations are defined in the configuration file broker.xml:

- 
-         <address-setting match="jms.queue.exampleQueue">
-            <expiry-address>jms.queue.expiryQueue</expiry-address>
-         </address-setting>
-         
-
-

This configuration will moved expired messages from the exampleQueue to the expiryQueue

-

ActiveMQ Artemis allows to specify either a Queue by prefixing the expiry-address with jms.queue. - or a Topic by prefixing with jms.topic..
- In this example, we will use a Queue to hold the expired messages.

-

Since we want to consume messages from this expiryQueue, we also need to add a JNDI binding to perform a lookup. - This is configured in activemq-jms.xml

- 
-         <queue name="expiryQueue">
-            <entry name="/queue/expiryQueue"/>
-         </queue>
-
- - diff --git a/examples/features/standard/expiry/readme.md b/examples/features/standard/expiry/readme.md new file mode 100644 index 0000000000..963e6de5ac --- /dev/null +++ b/examples/features/standard/expiry/readme.md @@ -0,0 +1,17 @@ +# JMS Expiration Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure ActiveMQ Artemis so messages are expipired after a certain time. + +Messages can be retained in the messaging system for a limited period of time before being removed. JMS specification states that clients should not receive messages that have been expired (but it does not guarantee this will not happen). + +ActiveMQ Artemis can assign a _expiry address_ to a given queue so that when messages are expired, they are removed from the queue and routed to this address. These "expired" messages can later be consumed for further inspection. + +The example will send 1 message with a short _time-to-live_ to a queue. We will wait for the message to expire and checks that the message is no longer in the queue it was sent to. We will instead consume it from an _expiry queue_ where it was moved when it expired. + +## Example setup + +Expiry destinations are defined in the configuration file broker.xml. + +This configuration will moved expired messages from the `exampleQueue` to the `expiryQueue`. diff --git a/examples/features/standard/expiry/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/expiry/src/main/resources/activemq/server0/broker.xml index fd26edde15..12faf9b296 100644 --- a/examples/features/standard/expiry/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/expiry/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -56,7 +54,7 @@ under the License. - +
diff --git a/examples/features/standard/http-transport/pom.xml b/examples/features/standard/http-transport/pom.xml index 38c3a60ef6..02e4d45b1e 100644 --- a/examples/features/standard/http-transport/pom.xml +++ b/examples/features/standard/http-transport/pom.xml @@ -103,7 +103,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/http-transport/readme.html b/examples/features/standard/http-transport/readme.html deleted file mode 100644 index 061c9390bc..0000000000 --- a/examples/features/standard/http-transport/readme.html +++ /dev/null @@ -1,52 +0,0 @@ - - - - - ActiveMQ Artemis JMS HTTP Transport Example - - - - - -

JMS HTTP Example

- - - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example shows you how to configure ActiveMQ Artemis to use the HTTP protocol as its transport layer.

- -

ActiveMQ Artemis supports a variety of network protocols to be its underlying transport without any specific code change.

- -

This example is taken from the queue example without any code change. By changing the configuration file, one can get ActiveMQ Artemis working with HTTP transport.

-

All you need to do is open the server0/broker.xml and enable HTTP like the following

- - - 
-      
-      <connector name="netty-connector">tcp://localhost:8080?httpEnabled=true</connector>
-
-      <!-- Acceptors -->
-
-      <acceptor name="netty-acceptor">tcp://localhost:8080 </acceptor>
-      
-
- - - diff --git a/examples/features/standard/http-transport/readme.md b/examples/features/standard/http-transport/readme.md new file mode 100644 index 0000000000..5c1951cce5 --- /dev/null +++ b/examples/features/standard/http-transport/readme.md @@ -0,0 +1,9 @@ +# JMS HTTP Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure ActiveMQ Artemis to use the HTTP protocol as its transport layer. + +ActiveMQ Artemis supports a variety of network protocols to be its underlying transport without any specific code change. + +This example is taken from the queue example without any code change. By changing the client's URL in `jndi.properties` one can get ActiveMQ Artemis working with the HTTP transport. \ No newline at end of file diff --git a/examples/features/standard/http-transport/src/main/java/org/apache/activemq/artemis/jms/example/HttpTransportExample.java b/examples/features/standard/http-transport/src/main/java/org/apache/activemq/artemis/jms/example/HttpTransportExample.java index bb189d304d..721e6c6e0d 100644 --- a/examples/features/standard/http-transport/src/main/java/org/apache/activemq/artemis/jms/example/HttpTransportExample.java +++ b/examples/features/standard/http-transport/src/main/java/org/apache/activemq/artemis/jms/example/HttpTransportExample.java @@ -23,29 +23,29 @@ import javax.jms.MessageProducer; import javax.jms.Queue; import javax.jms.Session; import javax.jms.TextMessage; - -import org.apache.activemq.artemis.api.jms.ActiveMQJMSClient; -import org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory; +import javax.naming.InitialContext; /** - * A simple JMS Queue example that uses HTTP protocol. + * A simple JMS Queue example that uses the HTTP protocol. */ public class HttpTransportExample { public static void main(final String[] args) throws Exception { Connection connection = null; + InitialContext initialContext = null; try { - // Step 2. Perfom a lookup on the queue - Queue queue = ActiveMQJMSClient.createQueue("exampleQueue"); + // Step 1. Create an initial context to perform the JNDI lookup. + initialContext = new InitialContext(); + + // Step 2. Perform a lookup on the queue + Queue queue = (Queue) initialContext.lookup("queue/exampleQueue"); // Step 3. Perform a lookup on the Connection Factory - ConnectionFactory cf = new ActiveMQConnectionFactory("tcp://localhost:8080?httpEnabled=true"); + ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("ConnectionFactory"); // Step 4.Create a JMS Connection connection = cf.createConnection(); - System.out.println("connection created: " + connection); - // Step 5. Create a JMS Session Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); @@ -70,8 +70,11 @@ public class HttpTransportExample { TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000); System.out.println("Received message: " + messageReceived.getText()); - } finally { + // Step 12. Be sure to close our JMS resources! + if (initialContext != null) { + initialContext.close(); + } if (connection != null) { connection.close(); } diff --git a/examples/features/standard/http-transport/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/http-transport/src/main/resources/activemq/server0/broker.xml index db5d5880cd..cb1f0d944e 100644 --- a/examples/features/standard/http-transport/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/http-transport/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -50,7 +48,7 @@ under the License. - +
diff --git a/examples/features/standard/http-transport/src/main/resources/jndi.properties b/examples/features/standard/http-transport/src/main/resources/jndi.properties new file mode 100644 index 0000000000..5f8076dfb2 --- /dev/null +++ b/examples/features/standard/http-transport/src/main/resources/jndi.properties @@ -0,0 +1,20 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory +connectionFactory.ConnectionFactory=tcp://localhost:8080?httpEnabled=true +queue.queue/exampleQueue=exampleQueue diff --git a/examples/features/standard/instantiate-connection-factory/pom.xml b/examples/features/standard/instantiate-connection-factory/pom.xml index bd63910282..8ab03507f5 100644 --- a/examples/features/standard/instantiate-connection-factory/pom.xml +++ b/examples/features/standard/instantiate-connection-factory/pom.xml @@ -104,7 +104,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/instantiate-connection-factory/readme.html b/examples/features/standard/instantiate-connection-factory/readme.html deleted file mode 100644 index b084471cd9..0000000000 --- a/examples/features/standard/instantiate-connection-factory/readme.html +++ /dev/null @@ -1,49 +0,0 @@ - - - - - ActiveMQ Artemis JMS Instantiate Connection Factory Example - - - - - -

JMS Instantiate Connection Factory Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

Usually, JMS Objects such as ConnectionFactories, Queue and Topic instances are looked up from JNDI - before being used by the client code. This objects are called "administered objects" in JMS specification - terminology.

-

However, in some cases a JNDI server may not be available or desired. To come to the rescue ActiveMQ - also supports the direct instantiation of these administered objects on the client side.

-

This allows the full set of JMS functionality to be available without requiring a JNDI server!

-

This example is very simple and based on the simple Queue example, however in this example we - instantiate the JMS Queue and ConnectionFactory objects directly.

-

A wide variety of methods are available for instantiating ConnectionFactory objects. In this example - we use a simple method which just takes the server connection details so it knows where to make the - connection to.

-

Other methods are available so all the connection factory parameters can be specified - including specifying UDP discovery so the client does not need hard-wired knowledge of where the servers - are that it wishes to connect to, or for specifying live-backup pairs of servers for failover.

-

For more information on instantiating ConnectionFactories directly please consult the user manual and - javadoc.

- - diff --git a/examples/features/standard/interceptor-client-amqp/pom.xml b/examples/features/standard/interceptor-amqp/pom.xml similarity index 88% rename from examples/features/standard/interceptor-client-amqp/pom.xml rename to examples/features/standard/interceptor-amqp/pom.xml index 35d90cadd2..de4e5b1361 100644 --- a/examples/features/standard/interceptor-client-amqp/pom.xml +++ b/examples/features/standard/interceptor-amqp/pom.xml @@ -27,7 +27,7 @@ under the License. 2.5.0-SNAPSHOT - interceptor-client-amqp + interceptor-amqp jar ActiveMQ Artemis AMQP Interceptor Example @@ -115,7 +115,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/interceptor-amqp/readme.md b/examples/features/standard/interceptor-amqp/readme.md new file mode 100644 index 0000000000..73735b5763 --- /dev/null +++ b/examples/features/standard/interceptor-amqp/readme.md @@ -0,0 +1,21 @@ +# AMQP Interceptor Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to implement and configure a simple incoming, server-side AMQP interceptor with ActiveMQ Artemis. + +ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. To intercept AMQP packets all that needs to be done is to implement the `org.apache.activemq.artemis.protocol.amqp.broker.AmqpInterceptor` interface. + +Once you have your own interceptor class add it to the broker.xml as follows: + + + ... + + org.apache.activemq.artemis.amqp.example.SimpleAmqpInterceptor + + ... + + +With an interceptor you can handle various events in message processing. In this example, a simple interceptor, SimpleAmqpInterceptor, is implemented and configured. When the example is running, the interceptor will display the value of a string property of a sample AMQP message. + +With our interceptor we always return `true` from the `intercept` method. If we were to return `false` that signifies that no more interceptors are to run. Throw an exception to abort processing of the packet. \ No newline at end of file diff --git a/examples/features/standard/interceptor-client-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/InterceptorExample.java b/examples/features/standard/interceptor-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/InterceptorExample.java similarity index 100% rename from examples/features/standard/interceptor-client-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/InterceptorExample.java rename to examples/features/standard/interceptor-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/InterceptorExample.java diff --git a/examples/features/standard/interceptor-client-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/SimpleAmqpInterceptor.java b/examples/features/standard/interceptor-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/SimpleAmqpInterceptor.java similarity index 100% rename from examples/features/standard/interceptor-client-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/SimpleAmqpInterceptor.java rename to examples/features/standard/interceptor-amqp/src/main/java/org/apache/activemq/artemis/amqp/example/SimpleAmqpInterceptor.java diff --git a/examples/features/standard/interceptor-amqp/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/interceptor-amqp/src/main/resources/activemq/server0/broker.xml new file mode 100644 index 0000000000..e03bff6652 --- /dev/null +++ b/examples/features/standard/interceptor-amqp/src/main/resources/activemq/server0/broker.xml @@ -0,0 +1,53 @@ + + + + + + ./data/paging + + ./data/bindings + + ./data/journal + + ./data/large-messages + + + org.apache.activemq.artemis.amqp.example.SimpleAmqpInterceptor + + + + + tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE + + + + + + + + + + + + + + + + diff --git a/examples/features/standard/interceptor-client-amqp/readme.html b/examples/features/standard/interceptor-client-amqp/readme.html deleted file mode 100644 index 20bbc5c042..0000000000 --- a/examples/features/standard/interceptor-client-amqp/readme.html +++ /dev/null @@ -1,71 +0,0 @@ - - - - - ActiveMQ Artemis AMQP Interceptor Example - - - - - -

AMQP Interceptor Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- - -

This example shows you how to implement and configure a simple incoming, server-side AMQP interceptor with ActiveMQ Artemis.

- -

ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. All that needs to do is to implement the - Interceptor interface, as defined below:

- 
-     
-         public interface AmqpInterceptor
-         {
-            boolean intercept(final AMQPMessage message, RemotingConnection connection);
-         }
-     
-
-

Once you have your own interceptor class, add it to the broker.xml, as follows:

- 
-     
-        <configuration>
-        ...
-           <remoting-incoming-interceptors>
-              <class-name>org.apache.activemq.artemis.amqp.example.SimpleAMQPInterceptor</class-name>
-           </remoting-incoming-interceptors>
-        ...
-        </configuration>
-     
-
- -

With interceptor, you can handle various events in message processing. In this example, a simple interceptor, SimpleAMQPInterceptor, is implemented and configured. - When the example is running, the interceptor examine and log properties of the AMQP message.

- -

With our interceptor we always return true from the intercept method. If we were - to return false that signifies that no more interceptors are to run. - Throw an exception to abort processing of the packet.

- - - - - - - - diff --git a/examples/features/standard/interceptor-client-amqp/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/interceptor-client-amqp/src/main/resources/activemq/server0/broker.xml deleted file mode 100644 index 6374087dbf..0000000000 --- a/examples/features/standard/interceptor-client-amqp/src/main/resources/activemq/server0/broker.xml +++ /dev/null @@ -1,176 +0,0 @@ - - - - - - - - 0.0.0.0 - - true - - - ASYNCIO - - ./data/paging - - - org.apache.activemq.artemis.amqp.example.SimpleAmqpInterceptor - - - ./data/bindings - - ./data/journal - - ./data/large-messages - - true - - 2 - - -1 - - - - - - - - - - - - - - - - - - - - - - 5000 - - - 90 - - - 100Mb - - - - tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE - - - - tcp://0.0.0.0:5672?protocols=AMQP - - - tcp://0.0.0.0:61613?protocols=STOMP - - - tcp://0.0.0.0:5445?protocols=HORNETQ,STOMP - - - tcp://0.0.0.0:1883?protocols=MQTT - - - - - - - - - - - - - - - - - - - - - - - - DLQ - ExpiryQueue - 0 - - -1 - 10 - PAGE - true - true - true - true - - - - DLQ - ExpiryQueue - 0 - - -1 - 10 - PAGE - true - true - true - true - - - - -
- - - -
-
- - - -
- - - - - diff --git a/examples/features/standard/interceptor-client-mqtt/readme.html b/examples/features/standard/interceptor-client-mqtt/readme.html deleted file mode 100644 index e8efad0579..0000000000 --- a/examples/features/standard/interceptor-client-mqtt/readme.html +++ /dev/null @@ -1,71 +0,0 @@ - - - - - ActiveMQ Artemis JMS Interceptor Example - - - - - -

MQTT Interceptor Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- - -

This example shows you how to implement and configure a simple incoming, server-side MQTT interceptor with ActiveMQ Artemis.

- -

ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. All that needs to do is to implement the - Interceptor interface, as defined below:

- 
-     
-         public interface Interceptor
-         {
-            boolean intercept(final MqttMessage mqttMessage, RemotingConnection connection);
-         }
-     
-
-

Once you have your own interceptor class, add it to the broker.xml, as follows:

- 
-     
-        <configuration>
-        ...
-           <remoting-incoming-interceptors>
-              <class-name>org.apache.activemq.artemis.mqtt.example.SimpleMQTTInterceptor</class-name>
-           </remoting-incoming-interceptors>
-        ...
-        </configuration>
-     
-
- -

With interceptor, you can handle various events in message processing. In this example, a simple interceptor, SimpleMQTTInterceptor, is implemented and configured. - When the example is running, the interceptor will modify the payload of a sample MQTT message.

- -

With our interceptor we always return true from the intercept method. If we were - to return false that signifies that no more interceptors are to run. - Throw an exception to abort processing of the packet.

- - - - - - - - diff --git a/examples/features/standard/interceptor-client-mqtt/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/interceptor-client-mqtt/src/main/resources/activemq/server0/broker.xml deleted file mode 100644 index 82e55da461..0000000000 --- a/examples/features/standard/interceptor-client-mqtt/src/main/resources/activemq/server0/broker.xml +++ /dev/null @@ -1,180 +0,0 @@ - - - - - - - - 0.0.0.0 - - true - - - ASYNCIO - - ./data/paging - - - org.apache.activemq.artemis.mqtt.example.SimpleMQTTInterceptor - - - - org.apache.activemq.artemis.mqtt.example.SimpleMQTTInterceptor - - - ./data/bindings - - ./data/journal - - ./data/large-messages - - true - - 2 - - -1 - - - - - - - - - - - - - - - - - - - - - - 5000 - - - 90 - - - 100Mb - - - - tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE - - - - tcp://0.0.0.0:5672?protocols=AMQP - - - tcp://0.0.0.0:61613?protocols=STOMP - - - tcp://0.0.0.0:5445?protocols=HORNETQ,STOMP - - - tcp://0.0.0.0:1883?protocols=MQTT - - - - - - - - - - - - - - - - - - - - - - - - DLQ - ExpiryQueue - 0 - - -1 - 10 - PAGE - true - true - true - true - - - - DLQ - ExpiryQueue - 0 - - -1 - 10 - PAGE - true - true - true - true - - - - -
- - - -
-
- - - -
- - - - - diff --git a/examples/features/standard/interceptor-client/pom.xml b/examples/features/standard/interceptor-client/pom.xml index 3d523591ff..5d233f0d59 100644 --- a/examples/features/standard/interceptor-client/pom.xml +++ b/examples/features/standard/interceptor-client/pom.xml @@ -29,7 +29,7 @@ under the License. interceptor-client jar - ActiveMQ Artemis JMS Interceptor Example + ActiveMQ Artemis JMS Interceptor Client Example ${project.basedir}/../../../.. @@ -104,7 +104,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/interceptor-client/readme.html b/examples/features/standard/interceptor-client/readme.html deleted file mode 100644 index 42b1e18570..0000000000 --- a/examples/features/standard/interceptor-client/readme.html +++ /dev/null @@ -1,72 +0,0 @@ - - - - - ActiveMQ Artemis JMS Interceptor Example - - - - - -

JMS Interceptor Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- - -

This example shows you how to implement and configure a simple incoming, server-side interceptor with ActiveMQ Artemis.

- -

ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. All that needs to do is to implement the - Interceptor interface, as defined below:

- 
-     
-         public interface Interceptor
-         {
-            boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
-         }
-     
-
-

Once you have your own interceptor class, add it to the broker.xml, as follows:

- 
-     
-        <configuration>
-        ...
-           <remoting-incoming-interceptors>
-              <class-name>org.apache.activemq.artemis.jms.example.SimpleInterceptor</class-name>
-           </remoting-incoming-interceptors>
-        ...
-        </configuration>
-     
-
- -

With interceptor, you can handle various events in message processing. In this example, a simple interceptor, SimpleInterceptor, is implemented and configured. - When the example is running, the interceptor will print out each events that are passed in the interceptor. And it will add a string property to the message being - delivered. You can see that after the message is received, there will be a new string property appears in the received message.

- -

With our interceptor we always return true from the intercept method. If we were - to return false that signifies that no more interceptors are to run or the target - is not to be called. Return false to abort processing of the packet.

- - - - - - - - diff --git a/examples/features/standard/interceptor-client/readme.md b/examples/features/standard/interceptor-client/readme.md new file mode 100644 index 0000000000..2f83bce5ae --- /dev/null +++ b/examples/features/standard/interceptor-client/readme.md @@ -0,0 +1,13 @@ +# JMS Interceptor Client Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to implement and configure a simple incoming, client-side interceptor with ActiveMQ Artemis. + +ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. To intercept "core" packets all that needs to be done is to implement the `org.apache.activemq.artemis.api.core.Interceptor` interface. + +Once you have your own interceptor class, add it to client via the `incomingInterceptorList` URL parameter. + +With interceptors, you can handle various events in message processing. In this example, a simple interceptor, SimpleInterceptor, is implemented and configured. When the example is running the interceptor will print out each events that are passed in the interceptor. And it will add a string property to the message being delivered. You can see that after the message is received, there will be a new string property appears in the received message. + +With our interceptor we always return `true` from the `intercept` method. If we were to return `false` that signifies that no more interceptors are to run or the target is not to be called. Return `false` to abort processing of the packet. diff --git a/examples/features/standard/interceptor-client/src/main/java/org/apache/activemq/artemis/jms/example/InterceptorExample.java b/examples/features/standard/interceptor-client/src/main/java/org/apache/activemq/artemis/jms/example/InterceptorExample.java index 1f70c54ada..a84d9dff0b 100644 --- a/examples/features/standard/interceptor-client/src/main/java/org/apache/activemq/artemis/jms/example/InterceptorExample.java +++ b/examples/features/standard/interceptor-client/src/main/java/org/apache/activemq/artemis/jms/example/InterceptorExample.java @@ -27,7 +27,7 @@ import javax.jms.TextMessage; import org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory; /** - * A simple JMS example that shows how to implement and use interceptors with ActiveMQ Artemis. + * A simple JMS example that shows how to implement and use client-side interceptors with ActiveMQ Artemis. */ public class InterceptorExample { diff --git a/examples/features/standard/interceptor-client-mqtt/pom.xml b/examples/features/standard/interceptor-mqtt/pom.xml similarity index 87% rename from examples/features/standard/interceptor-client-mqtt/pom.xml rename to examples/features/standard/interceptor-mqtt/pom.xml index d9f97bf6b4..20053d4eaf 100644 --- a/examples/features/standard/interceptor-client-mqtt/pom.xml +++ b/examples/features/standard/interceptor-mqtt/pom.xml @@ -27,7 +27,7 @@ under the License. 2.5.0-SNAPSHOT - interceptor-client-mqtt + interceptor-mqtt jar ActiveMQ Artemis MQTT Interceptor Example @@ -78,7 +78,7 @@ under the License. ${noServer} true - tcp://localhost:61616 + tcp://localhost:1883 run @@ -114,7 +114,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/interceptor-mqtt/readme.md b/examples/features/standard/interceptor-mqtt/readme.md new file mode 100644 index 0000000000..da62c769ae --- /dev/null +++ b/examples/features/standard/interceptor-mqtt/readme.md @@ -0,0 +1,21 @@ +# MQTT Interceptor Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to implement and configure a simple incoming, server-side MQTT interceptor with ActiveMQ Artemis. + +ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. To intercept MQTT packets all that needs to be done is to implement the `org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor` interface. + +Once you have your own interceptor class add it to the broker.xml as follows: + + + ... + + org.apache.activemq.artemis.mqtt.example.SimpleMQTTInterceptor + + ... + + +With an interceptor you can handle various events in message processing. In this example, a simple interceptor, SimpleMQTTInterceptor, is implemented and configured. When the example is running, the interceptor will modify the payload of a sample MQTT message. + +With our interceptor we always return `true` from the `intercept` method. If we were to return `false` that signifies that no more interceptors are to run. Throw an exception to abort processing of the packet. \ No newline at end of file diff --git a/examples/features/standard/interceptor-client-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/InterceptorExample.java b/examples/features/standard/interceptor-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/InterceptorExample.java similarity index 100% rename from examples/features/standard/interceptor-client-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/InterceptorExample.java rename to examples/features/standard/interceptor-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/InterceptorExample.java diff --git a/examples/features/standard/interceptor-client-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/SimpleMQTTInterceptor.java b/examples/features/standard/interceptor-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/SimpleMQTTInterceptor.java similarity index 89% rename from examples/features/standard/interceptor-client-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/SimpleMQTTInterceptor.java rename to examples/features/standard/interceptor-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/SimpleMQTTInterceptor.java index c705b81865..5297e61d8d 100644 --- a/examples/features/standard/interceptor-client-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/SimpleMQTTInterceptor.java +++ b/examples/features/standard/interceptor-mqtt/src/main/java/org/apache/activemq/artemis/mqtt/example/SimpleMQTTInterceptor.java @@ -18,14 +18,11 @@ package org.apache.activemq.artemis.mqtt.example; import java.nio.charset.Charset; -import io.netty.handler.codec.mqtt.MqttPublishMessage; import io.netty.handler.codec.mqtt.MqttConnectMessage; -import org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor; - - -import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection; - import io.netty.handler.codec.mqtt.MqttMessage; +import io.netty.handler.codec.mqtt.MqttPublishMessage; +import org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor; +import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection; /** @@ -35,9 +32,7 @@ public class SimpleMQTTInterceptor implements MQTTInterceptor { @Override public boolean intercept(final MqttMessage mqttMessage, RemotingConnection connection) { - System.out.println("MQTT Interceptor gets called "); - - System.out.println("A MQTT control packet was intercepted " + mqttMessage.fixedHeader().messageType()); + System.out.println("MQTT control packet was intercepted " + mqttMessage.fixedHeader().messageType()); // If you need to handle an specific packet type: if (mqttMessage instanceof MqttPublishMessage) { @@ -54,7 +49,7 @@ public class SimpleMQTTInterceptor implements MQTTInterceptor { } else { if (mqttMessage instanceof MqttConnectMessage) { MqttConnectMessage connectMessage = (MqttConnectMessage) mqttMessage; - System.out.println("A MQTT CONNECT control packet was intercepted " + connectMessage); + System.out.println("MQTT CONNECT control packet was intercepted " + connectMessage); } } diff --git a/examples/features/standard/interceptor-mqtt/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/interceptor-mqtt/src/main/resources/activemq/server0/broker.xml new file mode 100644 index 0000000000..e04d65a1cf --- /dev/null +++ b/examples/features/standard/interceptor-mqtt/src/main/resources/activemq/server0/broker.xml @@ -0,0 +1,56 @@ + + + + + + ./data/bindings + + ./data/journal + + ./data/largemessages + + ./data/paging + + + org.apache.activemq.artemis.mqtt.example.SimpleMQTTInterceptor + + + + org.apache.activemq.artemis.mqtt.example.SimpleMQTTInterceptor + + + + tcp://0.0.0.0:1883?protocols=CORE,MQTT + + + + + + + + + + + + + + + + diff --git a/examples/features/standard/interceptor/pom.xml b/examples/features/standard/interceptor/pom.xml index 2101ae60e0..310b20cc49 100644 --- a/examples/features/standard/interceptor/pom.xml +++ b/examples/features/standard/interceptor/pom.xml @@ -104,7 +104,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/interceptor/readme.html b/examples/features/standard/interceptor/readme.html deleted file mode 100644 index 42b1e18570..0000000000 --- a/examples/features/standard/interceptor/readme.html +++ /dev/null @@ -1,72 +0,0 @@ - - - - - ActiveMQ Artemis JMS Interceptor Example - - - - - -

JMS Interceptor Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- - -

This example shows you how to implement and configure a simple incoming, server-side interceptor with ActiveMQ Artemis.

- -

ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. All that needs to do is to implement the - Interceptor interface, as defined below:

- 
-     
-         public interface Interceptor
-         {
-            boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException;
-         }
-     
-
-

Once you have your own interceptor class, add it to the broker.xml, as follows:

- 
-     
-        <configuration>
-        ...
-           <remoting-incoming-interceptors>
-              <class-name>org.apache.activemq.artemis.jms.example.SimpleInterceptor</class-name>
-           </remoting-incoming-interceptors>
-        ...
-        </configuration>
-     
-
- -

With interceptor, you can handle various events in message processing. In this example, a simple interceptor, SimpleInterceptor, is implemented and configured. - When the example is running, the interceptor will print out each events that are passed in the interceptor. And it will add a string property to the message being - delivered. You can see that after the message is received, there will be a new string property appears in the received message.

- -

With our interceptor we always return true from the intercept method. If we were - to return false that signifies that no more interceptors are to run or the target - is not to be called. Return false to abort processing of the packet.

- - - - - - - - diff --git a/examples/features/standard/interceptor/readme.md b/examples/features/standard/interceptor/readme.md new file mode 100644 index 0000000000..13f2726066 --- /dev/null +++ b/examples/features/standard/interceptor/readme.md @@ -0,0 +1,21 @@ +# JMS Interceptor Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to implement and configure a simple incoming, server-side interceptor with ActiveMQ Artemis. + +ActiveMQ Artemis allows an application to use an interceptor to hook into the messaging system. To intercept "core" packets all that needs to be done is to implement the `org.apache.activemq.artemis.api.core.Interceptor` interface. + +Once you have your own interceptor class, add it to the broker.xml, as follows: + + + ... + + org.apache.activemq.artemis.jms.example.SimpleInterceptor + + ... + + +With interceptors, you can handle various events in message processing. In this example, a simple interceptor, SimpleInterceptor, is implemented and configured. When the example is running the interceptor will print out each events that are passed in the interceptor. And it will add a string property to the message being delivered. You can see that after the message is received, there will be a new string property appears in the received message. + +With our interceptor we always return `true` from the `intercept` method. If we were to return `false` that signifies that no more interceptors are to run or the target is not to be called. Return `false` to abort processing of the packet. \ No newline at end of file diff --git a/examples/features/standard/interceptor/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/interceptor/src/main/resources/activemq/server0/broker.xml index 11c324d06c..01a70c3256 100644 --- a/examples/features/standard/interceptor/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/interceptor/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -30,7 +28,6 @@ under the License. ./data/paging - org.apache.activemq.artemis.jms.example.SimpleInterceptor @@ -54,7 +51,7 @@ under the License. - +
diff --git a/examples/features/standard/jms-auto-closeable/pom.xml b/examples/features/standard/jms-auto-closeable/pom.xml index 60bc37e9ab..3ea9816167 100644 --- a/examples/features/standard/jms-auto-closeable/pom.xml +++ b/examples/features/standard/jms-auto-closeable/pom.xml @@ -99,7 +99,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/jms-auto-closeable/readme.html b/examples/features/standard/jms-auto-closeable/readme.html deleted file mode 100644 index 80dc410e6f..0000000000 --- a/examples/features/standard/jms-auto-closeable/readme.html +++ /dev/null @@ -1,96 +0,0 @@ - - - - - ActiveMQ Artemis JMS Auto Closable Example - - - - - -

JMS Auto Closable Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example shows you how JMS resources, such as connections, sessions and consumers, in JMS 2 can be automatically closed on error.

-

In this instance we auto close a connection after a subsequent call to a JMS producer send fails

- -

Example step-by-step

- -
    -
  1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
    2. - 
    -           InitialContext initialContext = getContext();
-
    - -
  2. We look-up the JMS queue object from JNDI
    3. - 
    -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
    - -
  3. We look-up the JMS connection factory object from JNDI
    4. - 
    -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
    - -
  4. We create a JMS context but we do it inside the try-with-resources statement like so:
    5. - 
    -           
-            try
-            (
-               JMSContext jmsContext = cf.createContext()
-            )
-           
-
    - -
  5. Inside the following try block we first create the producer
    6. - 
    -           JMSProducer jmsProducer = jmsContext.createProducer();
-
    - -
  6. We then try to send a message. It is this call that throws an exception as the producer doesn't have the privileges - to send a message
    7. - 
    -          jmsProducer.send(queue, "this message will fail security!");
-
    - -
  7. We catch the exception from the send message and can do what we want, however the JMSContext will have been closed - prior to entering the catch block.
    8. - 
    -           System.out.println("expected exception from jmsProducer.send: " + e.getMessage());
-
    - -
  8. And finally, we close the Initial Context, note we no longer have to worry about clearing up the JMSContext.
    9. - - 
    -           finally
-           {
-              if (initialContext != null)
-              {
-                 initialContext.close();
-              }
-           }
-
    - - - -
- - diff --git a/examples/features/standard/jms-auto-closeable/readme.md b/examples/features/standard/jms-auto-closeable/readme.md new file mode 100644 index 0000000000..248fca169a --- /dev/null +++ b/examples/features/standard/jms-auto-closeable/readme.md @@ -0,0 +1,7 @@ +# JMS Auto Closable Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how JMS resources such as connections, sessions and consumers in JMS 2 can be automatically closed on error. + +In this instance we auto close a connection after a subsequent call to a JMS producer send fails. \ No newline at end of file diff --git a/examples/features/standard/jms-bridge/pom.xml b/examples/features/standard/jms-bridge/pom.xml index 320bcad3c9..4422130a18 100644 --- a/examples/features/standard/jms-bridge/pom.xml +++ b/examples/features/standard/jms-bridge/pom.xml @@ -152,7 +152,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/jms-bridge/readme.html b/examples/features/standard/jms-bridge/readme.html deleted file mode 100644 index 182f7fa625..0000000000 --- a/examples/features/standard/jms-bridge/readme.html +++ /dev/null @@ -1,246 +0,0 @@ - - - - - ActiveMQ Artemis JMS Bridge Example - - - - - -

JMS Bridge Example

- - 
To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
- -

This example shows you how to create a JMS Bridge between two ActiveMQ Artemis servers.

- -

The example will use two ActiveMQ Artemis servers:

-
    -
  • Server #0 – the Source server. It will be configured with a JMS Topic bound to JNDI under source/topic -
  • Server #1 – the Target server. It will be configured with a JMS Queue bound to JNDI under target/queue
    -
-

Both ActiveMQ Artemis server will run their own JNDI server used by the JMS Bridge and the JMS Client to lookup JMS - resources (ConnectionFactory and Destination).

-

The JMS Bridge will be started in the example code and be configured to bridge messages from the source destination - (the topic hosted on server #0) and the target destination (the queue hosted on server #1)

-

The client will check the bridge works by:

-
    -
  1. sending a message to the source topic
    2. -
  2. receive a message from the target queue
    3. -
  3. check that both messages correspond to the same content.
    4. -
-

JMS Bridge Configuration

-

The JMS Bridge is a POJO that we configure with both source and target - JNDI configurations. In the actual example we are programmatically creating the Bridge, however the following section - describes how you would do this if you wanted to deploy with an actual ActiveMQ Artemis server via the activemq-beans.xml. - -

Configuring the Bridge with the JBoss Microcontainer

-

- in which we inject JNDI configurations - so that it looks up its source and target JMS resources. - The JMS Bridge is defined a bean and setup by JBoss Microntainer in the same VM than Server #1, the target server.

- -

The JMS Bridge sample configuration can be found in resources/activemq-beans.xml, firstly we define the - Bridge itself:

- 
-         <!-- The JMS Bridge -->
-         <bean name="JMSBridge" class="org.apache.activemq.artemis.jms.bridge.impl.JMSBridgeImpl">
-         ...
-         </bean>
-
-

the JMSBridgeImpl constructor is used to inject all the properties required to run the JMS Bridge.

-

Its first four arguments defines how the bridge will lookup:

-
    -
  1. its source JMS ConnectionFactory
    2. -
  2. its source JMS Destination
    3. -
  3. its target JMS ConnectionFactory
    4. -
  4. its target JMS Destination
    5. -
-

Using other POJOs, the JMS Bridge is configured to retrieve:

-
    -
  • its source JMS ConnectionFactory by looking up /source/ConnectionFactory using - the SourceJNDI configuration
    • -
  • its source JMS Destination by looking up /source/topic using - the SourceJNDI configuration
    • -
  • its target JMS ConnectionFactory by looking up /target/ConnectionFactory using - the TargetJNDI configuration
    • -
  • its target JMS ConnectionFactory by looking up /target/queue using - the TargetJNDI configuration
    • -
-

In turn, SourceJNDI and TargetJNDI are POJOs defining how to connect to JNDI server. - SourceJNDI URL must point to your source server, while LocalJNDI must point to your target server:

- 
-      <bean name="SourceJNDI" class="java.util.Hashtable">
-         ...
-                <entry>
-                   <key>java.naming.provider.url</key>
-                   <!-- **************************************** -->
-                   <!-- Replace with the *source* server address -->
-                   <!-- **************************************** -->
-                   <value>jnp://192.168.0.10:1099</value>
-         ...
-       </bean>
-       <bean name="TargetJNDI" class="java.util.Hashtable">
-         ...
-                <ntry>
-                   <key>java.naming.provider.url</key>
-                   <!-- **************************************** -->
-                   <!-- Replace with the *target* server address -->
-                   <!-- **************************************** -->
-                   <value>jnp://1192.168.0.11:1099</value>
-                </entry>
-         ...
-       </bean>
-
-

Example step-by-step

-

To run the example after having setup both ActiveMQ Artemis servers and the JMS bridge:

-
    -
  1. To run the example simply run mvn verify -Pexample
    2. -
-

Let's look at the Client code (in JMSBridgeExample class):

-
    -
  1. First we need to get an initial context so we can look-up the JMS resources
    2. - 
    -           InitialContext sourceContext = createContext(sourceServer);
-           InitialContext targetContext = createContext(targetServer);
-
    -
  2. We then create a JMS Bridge and start it, Note, for certain quality of service modes such as - ONCE_AND_ONCE_ONLY and AT_LEAST_ONCE a Transaction Manager is required to ensure Messages are delivered - accordingly. A Transaction Manager can be either loaded via implementation of TransactionManagerLocator intefer - and loaded via standard a ServiceLoader or by explicitly setting an instance of a Transaction Manager on the - bridge using setTranscationManager(TransactionManager tm) method. In this example we'll be using the DUPLICATES_OK - quality of service so there is no need for a Transaction Manager. - 
    -            JMSBridge jmsBridge = new JMSBridgeImpl(
-               new JNDIConnectionFactoryFactory(sourceJndiParams, "source/ConnectionFactory"),
-               new JNDIConnectionFactoryFactory(targetJndiParams, "target/ConnectionFactory"),
-               new JNDIDestinationFactory(sourceJndiParams, "source/topic"),
-               new JNDIDestinationFactory(targetJndiParams, "target/queue"),
-               null,
-               null,
-               null,
-               null,
-               null,
-               5000,
-               10,
-               QualityOfServiceMode.DUPLICATES_OK,
-               1,
-               -1,
-               null,
-               null,
-               true);
-            ....
-        jmsBridge.start();
-
    -
  3. We look up the JMS resources from the Source server
    4. - 
    -           ConnectionFactory sourceConnectionFactory = (ConnectionFactory)sourceContext.lookup("source/ConnectionFactory");
-           Topic sourceTopic = (Topic)sourceContext.lookup("source/topic");
-
    - -
  4. We create JMS objects to send a message to the source destination
    5. - 
    -           sourceConnection = sourceConnectionFactory.createConnection();
-           Session sourceSession = sourceConnection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-           MessageProducer sourceProducer = sourceSession.createProducer(sourceTopic);
-
    - -
  5. We send a message to the source destination
    6. - 
    -           TextMessage message = sourceSession.createTextMessage("this is a text message sent at " + System.currentTimeMillis());
-           sourceProducer.send(message);
-
    - -
  6. We close the connection to the source server
    7. - 
    -           sourceConnection.close();
-
    - -

    At this point, the JMS Bridge will consume the message from the source topic and - sends it to the target queue. - The client will check the bridge works by consuming a message from the target queue.

    - -
  7. We look up the JMS resources from the target server
    8. - 
    -           ConnectionFactory targetConnectionFactory = (ConnectionFactory)targetContext.lookup("target/ConnectionFactory");
-           Queue targetQueue = (Queue)targetContext.lookup("target/queue");
-
    - -
  8. We create JMS objects to receive a message from the target destination
    9. - 
    -           targetConnection = targetConnectionFactory.createConnection();
-           Session targetSession = targetConnection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-           MessageConsumer targetConsumer = targetSession.createConsumer(targetQueue);
-
    - -
  9. We start the target connection to start receiving messages - 
    -           targetConnection.start();
-
    - -
  10. We receive the message and print it. Its content is the same than the message - the client sent to the source topic
    11. - 
    -           TextMessage messageReceived = (TextMessage)targetConsumer.receive(5000);
-
    - -
  11. We display the message ID and its "bridged" message ID
    12. - 
    -           System.out.format("Message ID         : %s\n", messageReceived.getJMSMessageID());
-           System.out.format("Bridged Message ID : %s\n", messageReceived.getStringProperty("AMQ_BRIDGE_MSG_ID_LIST"));
-
    - -

    Note that the message received from the target queue is not the same message sent to the source topic - (their message IDs are different) but they have the same content. - -

  12. And finally, we stop the Bridge and always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
    13. - - 
    -           finally
-           {
-              if (jmsBridge != null)
-              {
-                jmsBridge.stop();
-              }
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
    - - - -
- -

More information

- -
    -
  • User Manual's JMS Bridge chapter
    • -
  • The Java EE JMS Bridge example shows how to configure a JMS Bridge - inside JBoss Application Server to bridge destinations from the same server. -

    - - - diff --git a/examples/features/standard/jms-bridge/readme.md b/examples/features/standard/jms-bridge/readme.md new file mode 100644 index 0000000000..8001bcd911 --- /dev/null +++ b/examples/features/standard/jms-bridge/readme.md @@ -0,0 +1,24 @@ +# JMS Bridge Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to create a JMS Bridge between two ActiveMQ Artemis brokers. + +![](jms-bridge.png) + +The example will use two ActiveMQ Artemis brokers: + +* Server #0 – the _Source_ broker. It will be configured with a JMS Topic bound to JNDI under `source/topic` +* Server #1 – the _Target_ broker. It will be configured with a JMS Queue bound to JNDI under `target/queue` + +The JMS Bridge will be started in the example code and be configured to bridge messages from the _source_ destination (the topic hosted on broker #0) and the _target_ destination (the queue hosted on broker #1) + +The client will check the bridge works by: + +1. sending a message to the _source_ topic +2. receive a message from the _target_ queue +3. check that both messages correspond to the same content. + +### JMS Bridge Configuration + +The JMS Bridge is a POJO that we configure with both source and target JNDI configurations. In the actual example we are programmatically creating the Bridge. \ No newline at end of file diff --git a/examples/features/standard/jms-bridge/src/main/java/org/apache/activemq/artemis/jms/example/JMSBridgeExample.java b/examples/features/standard/jms-bridge/src/main/java/org/apache/activemq/artemis/jms/example/JMSBridgeExample.java index 5b25a82e46..f7d22cab30 100644 --- a/examples/features/standard/jms-bridge/src/main/java/org/apache/activemq/artemis/jms/example/JMSBridgeExample.java +++ b/examples/features/standard/jms-bridge/src/main/java/org/apache/activemq/artemis/jms/example/JMSBridgeExample.java @@ -127,7 +127,7 @@ public class JMSBridgeExample { jndiProps.put("connectionFactory.ConnectionFactory", server); jndiProps.put("java.naming.factory.initial", "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory"); jndiProps.put("queue.target/queue", "target"); - jndiProps.put("topic.source/topic", "topic"); + jndiProps.put("topic.source/topic", "source"); return jndiProps; } } diff --git a/examples/features/standard/jms-bridge/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/jms-bridge/src/main/resources/activemq/server0/broker.xml index ed98e9cd1b..94ff7092ec 100644 --- a/examples/features/standard/jms-bridge/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/jms-bridge/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -42,8 +40,8 @@ under the License. - -
    + +
    diff --git a/examples/features/standard/jms-bridge/src/main/resources/activemq/server1/broker.xml b/examples/features/standard/jms-bridge/src/main/resources/activemq/server1/broker.xml index 6ee55d919b..7ed167477e 100644 --- a/examples/features/standard/jms-bridge/src/main/resources/activemq/server1/broker.xml +++ b/examples/features/standard/jms-bridge/src/main/resources/activemq/server1/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -42,7 +40,7 @@ under the License. - +
    diff --git a/examples/features/standard/jms-completion-listener/pom.xml b/examples/features/standard/jms-completion-listener/pom.xml index 4d4848bc6a..16f9167445 100644 --- a/examples/features/standard/jms-completion-listener/pom.xml +++ b/examples/features/standard/jms-completion-listener/pom.xml @@ -103,7 +103,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/jms-completion-listener/readme.html b/examples/features/standard/jms-completion-listener/readme.html deleted file mode 100644 index 36be17a341..0000000000 --- a/examples/features/standard/jms-completion-listener/readme.html +++ /dev/null @@ -1,112 +0,0 @@ - - - - - ActiveMQ Artemis JMS Completion Listener Example - - - - - -

    JMS Completion Listener Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to send a message asynchronously to ActiveMQ Artemis and use a CompletionListener to be notified of - the Broker receiving it

    - -

    Example step-by-step

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look-up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS context
      5. - 
      -           jmsContext = cf.createContext();
-
      - -
    5. We create a JMS Producer.
      6. - 
      -           JMSProducer producer = jmsContext.createProducer();
-
      - -
    6. We set a CompletionListener on the Producer
      7. - 
      -          producer.setAsync(new CompletionListener()
-                {
-                   @Override
-                   public void onCompletion(Message message)
-                   {
-                      System.out.println("message acknowledged by ActiveMQ");
-                      latch.countDown();
-                   }
-
-                   @Override
-                   public void onException(Message message, Exception e)
-                   {
-                      e.printStackTrace();
-                   }
-                });
-
      - -
    7. We send a message
      8. - 
      -           producer.send(queue, "this is a string");
-
      - -
    8. and then wait for the Completion Listener to be called
      9. - 
      -           return latch.await(5, TimeUnit.SECONDS);
-
      - -
    9. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      10. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                 initialContext.close();
-              }
-              if (jmsContext != null)
-              {
-                 jmsContext.close();
-              }
-           }
-
      - - - -
    - - diff --git a/examples/features/standard/jms-completion-listener/readme.md b/examples/features/standard/jms-completion-listener/readme.md new file mode 100644 index 0000000000..a8c7d6d351 --- /dev/null +++ b/examples/features/standard/jms-completion-listener/readme.md @@ -0,0 +1,5 @@ +# JMS Completion Listener Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to send a message asynchronously to ActiveMQ Artemis and use a CompletionListener to be notified of the Broker receiving it. \ No newline at end of file diff --git a/examples/features/standard/jms-context/pom.xml b/examples/features/standard/jms-context/pom.xml index 62581386e7..fa9d8cc386 100644 --- a/examples/features/standard/jms-context/pom.xml +++ b/examples/features/standard/jms-context/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/jms-context/readme.html b/examples/features/standard/jms-context/readme.html deleted file mode 100644 index 34895a2688..0000000000 --- a/examples/features/standard/jms-context/readme.html +++ /dev/null @@ -1,35 +0,0 @@ - - - - - ActiveMQ Artemis JMS Context Example - - - - - -

    JMS Context Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to send and receive a message to a JMS Queue using ActiveMQ Artemis by using a JMS Context

    -

    A JMSContext is part of JMS 2.0 and combines the JMS Connection and Session Objects into a simple Interface

    - - diff --git a/examples/features/standard/jms-context/readme.md b/examples/features/standard/jms-context/readme.md new file mode 100644 index 0000000000..0f03836721 --- /dev/null +++ b/examples/features/standard/jms-context/readme.md @@ -0,0 +1,7 @@ +# JMS Context Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to send and receive a message to a JMS Queue using ActiveMQ Artemis by using a JMSContext. + +A JMSContext is part of JMS 2.0 and combines the JMS Connection and Session Objects into a simple interface. \ No newline at end of file diff --git a/examples/features/standard/jms-shared-consumer/pom.xml b/examples/features/standard/jms-shared-consumer/pom.xml index f3f95b1bb7..864594f81e 100644 --- a/examples/features/standard/jms-shared-consumer/pom.xml +++ b/examples/features/standard/jms-shared-consumer/pom.xml @@ -104,7 +104,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/jms-shared-consumer/readme.html b/examples/features/standard/jms-shared-consumer/readme.html deleted file mode 100644 index b92b3400ba..0000000000 --- a/examples/features/standard/jms-shared-consumer/readme.html +++ /dev/null @@ -1,119 +0,0 @@ - - - - - ActiveMQ Artemis JMS Shared Consumer Example - - - - - -

    JMS Shared Consumer Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how can use shared consumers to share a subscription on a topic. In JMS 1.1 this was not allowed - and so caused a scalability issue. In JMS 2 this restriction has been lifted so you can share the load across different - threads and connections.

    - -

    Example step-by-step

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS topic object from JNDI
      3. - 
      -           Topic topic = (Topic) initialContext.lookup("/topic/exampleTopic");
-
      - -
    3. We look-up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS context
      5. - 
      -           jmsContext = cf.createContext();
-
      - -
    5. We create a JMS Producer.
      6. - 
      -           JMSProducer producer = jmsContext.createProducer();
-
      - -
    6. We create a shared consumer using the subscription name sc1
      7. - 
      -          JMSConsumer jmsConsumer = jmsContext.createSharedConsumer(topic, "sc1");
-
      - -
    7. We then create a second JMS context for a second shared consumer
      8. - 
      -           jmsContext2 = cf.createContext();
-
      - -
    8. we then create the second shared consumer using the same subscription name
      9. - 
      -           JMSConsumer jmsConsumer2 = jmsContext2.createSharedConsumer(topic, "sc1");
-
      - -
    9. we then send 2 messages
      10. - 
      -           
-           producer.send(topic, "this is a String!");
-
-           producer.send(topic, "this is a second String!") ;
-
      - -
    10. we then receive the 2 messages using both shared consumers
      11. - 
      -           
-           String body = jmsConsumer.receiveBody(String.class, 5000);
-
-           body = jmsConsumer2.receiveBody(String.class, 5000);
-
      - -
    11. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      12. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                 initialContext.close();
-              }
-              if (jmsContext != null)
-              {
-                 jmsContext.close();
-              }
-               if (jmsContext2 != null)
-               {
-               jmsContext2.close();
-               }
-           }
-
      - - - -
    - - diff --git a/examples/features/standard/jms-shared-consumer/readme.md b/examples/features/standard/jms-shared-consumer/readme.md new file mode 100644 index 0000000000..090f110ca3 --- /dev/null +++ b/examples/features/standard/jms-shared-consumer/readme.md @@ -0,0 +1,5 @@ +# JMS Shared Consumer Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how can use shared consumers to share a subscription on a topic. In JMS 1.1 this was not allowed and so caused a scalability issue. In JMS 2 this restriction has been lifted so you can share the load across different threads and connections. \ No newline at end of file diff --git a/examples/features/standard/jms-shared-consumer/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/jms-shared-consumer/src/main/resources/activemq/server0/broker.xml index d3352b1e77..91d733a4d0 100644 --- a/examples/features/standard/jms-shared-consumer/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/jms-shared-consumer/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -50,7 +48,7 @@ under the License. - +
    diff --git a/examples/features/standard/jmx-ssl/pom.xml b/examples/features/standard/jmx-ssl/pom.xml index 04e7be97db..cc7f1dc803 100644 --- a/examples/features/standard/jmx-ssl/pom.xml +++ b/examples/features/standard/jmx-ssl/pom.xml @@ -108,7 +108,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/jmx-ssl/readme.html b/examples/features/standard/jmx-ssl/readme.html deleted file mode 100644 index ca4e6dafb8..0000000000 --- a/examples/features/standard/jmx-ssl/readme.html +++ /dev/null @@ -1,176 +0,0 @@ - - - - - ActiveMQ Artemis JMX SSL Management Example - - - - - -

    JMX Management Example

    - - 
    To run the example, simply type mvn verify -Djavax.net.ssl.keyStore=target/server0/etc/activemq.example.keystore -Djavax.net.ssl.keyStorePassword=activemqexample -Djavax.net.ssl.trustStore=target/server0/etc/activemq.example.truststore -Djavax.net.ssl.trustStorePassword=activemqexample from this directory, 
    or add -PnoServer if you want to start and create the server manually.
    - -

    This example shows how to manage ActiveMQ Artemis using JMX using SSL

    - -

    Example configuration

    - -

    ActiveMQ Artemis exposes its managed resources by default on the platform MBeanServer.

    -

    To access this MBeanServer remotely, add the following to the management.xml configuration: - 

    -             
-
    -

    With these properties, ActiveMQ Artemis server will be manageable remotely using standard JMX URL on port 1099.

    -

    - -

    Example step-by-step

    -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get its properties from client-jndi.properties
      2. - 
      -            InitialContext initialContext = getContext(0);
-
      - -
    2. We look up the JMS queue object from JNDI
      3. - 
      -            Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look up the JMS connection factory object from JNDI
      4. - 
      -            ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -            connection = cf.createConnection();
-
      - -
    5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
      6. - 
      -            Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. We create a JMS message producer on the session. This will be used to send the messages.
      7. - 
      -            MessageProducer messageProducer = session.createProducer(topic);
-
      - -
    7. We create a JMS text message that we are going to send.
      8. - 
      -            TextMessage message = session.createTextMessage("This is a text message");
-
      - -
    8. We send message to the queue
      9. - 
      -            messageProducer.send(message);
-
      - -

      Now that we have a message in the queue, we will manage the queue by retrieving the number of messages in the queue - (i.e. 1) and by removing the message which has been sent in step 8.

      - -
    9. We retrieve the ObjectName corresponding to the queue using a helper class ObjectNameBuilder
      10. - 
      -              ObjectName on = ObjectNameBuilder.DEFAULT.getJMSQueueObjectName(queue.getQueueName());
-
      - -
    10. We create a JMX Connector to connect to the server's MBeanServer using the standard JMX service URL
      11. - 
      -            JMXConnector connector = JMXConnectorFactory.connect(new JMXServiceURL(JMX_URL), new HashMap());
-
      - -
    11. We retrieve a MBeanServerConnection from the JMX connector
      12. - 
      -           TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
-
      - -
    12. We create a JMSQueueControl proxy to manage the queue on the server
      13. - 
      -            JMSQueueControl queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
-                                                                                              on,
-                                                                                              JMSQueueControl.class,
-                                                                                              false);
-             
-
      - -
    13. We use this mbean proxy to retrieve the number of messages in the queue using the getMessageCount method
      14. - 
      -            System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");
-
      - -
    14. We will now remove the message sent at step 8 using the removeMessage method with the JMS Message ID of the message
      15. - 
      -            System.out.println("message has been removed: " + queueControl.removeMessage(message.getJMSMessageID()));
-
      - -
    15. We use again the mbean proxy to retrieve the number of messages. This time, it will display 0 messages
      16. - 
      -            System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");
-
      - -
    16. Now we have finish the management operations, we close the JMX connector
      17. - 
      -            connector.close()
-
      - -

      We will now try to consume the message sent to the queue but it won't be there: it has been removed by the management operation

      - -
    17. We create a JMS message consumer on the queue
      18. - 
      -            MessageConsumer messageConsumer = session.createConsumer(queue);
-
      - -
    18. We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started
      19. - 
      -            connection.start();
-
      - -
    19. We try to receive a message from the queue. Since there is none, the call will timeout after 5000ms and messageReceived will be null -
      20. - 
      -            TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
-            System.out.println("Received message: " + messageReceived);
-
      - -
    20. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      21. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - diff --git a/examples/features/standard/jmx-ssl/readme.md b/examples/features/standard/jmx-ssl/readme.md new file mode 100644 index 0000000000..4c4291fdb4 --- /dev/null +++ b/examples/features/standard/jmx-ssl/readme.md @@ -0,0 +1,23 @@ +# JMX Management Example + +To run the example, simply type: + + mvn verify -Djavax.net.ssl.keyStore=target/server0/etc/activemq.example.keystore -Djavax.net.ssl.keyStorePassword=activemqexample -Djavax.net.ssl.trustStore=target/server0/etc/activemq.example.truststore -Djavax.net.ssl.trustStorePassword=activemqexample + +from this directory, or add **-PnoServer** if you want to start and create the broker manually. + +This example shows how to manage ActiveMQ Artemis using [JMX using SSL](http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/) + +## Example configuration + +ActiveMQ Artemis exposes its managed resources by default on the platform MBeanServer. + +To access this MBeanServer remotely, add the following to the management.xml configuration: + + + +With these properties, ActiveMQ Artemis broker will be manageable remotely using standard JMX URL on port `1099`. + +## More information + +* [Java management guide](http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html) \ No newline at end of file diff --git a/examples/features/standard/jmx-ssl/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/jmx-ssl/src/main/resources/activemq/server0/broker.xml index 7576376219..5d17696c84 100644 --- a/examples/features/standard/jmx-ssl/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/jmx-ssl/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -53,7 +51,7 @@ under the License. - +
    diff --git a/examples/features/standard/jmx/pom.xml b/examples/features/standard/jmx/pom.xml index 902fe99a48..746be9abc4 100644 --- a/examples/features/standard/jmx/pom.xml +++ b/examples/features/standard/jmx/pom.xml @@ -108,7 +108,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/jmx/readme.html b/examples/features/standard/jmx/readme.html deleted file mode 100644 index 7106e34302..0000000000 --- a/examples/features/standard/jmx/readme.html +++ /dev/null @@ -1,176 +0,0 @@ - - - - - ActiveMQ Artemis JMX Management Example - - - - - -

    JMX Management Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows how to manage ActiveMQ Artemis using JMX

    - -

    Example configuration

    - -

    ActiveMQ Artemis exposes its managed resources by default on the platform MBeanServer.

    -

    To access this MBeanServer remotely, add the following to the management.xml configuration: - 

    -             
-
    -

    With these properties, ActiveMQ Artemis server will be manageable remotely using standard JMX URL on port 1099.

    -

    - -

    Example step-by-step

    -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get its properties from client-jndi.properties
      2. - 
      -            InitialContext initialContext = getContext(0);
-
      - -
    2. We look up the JMS queue object from JNDI
      3. - 
      -            Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look up the JMS connection factory object from JNDI
      4. - 
      -            ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -            connection = cf.createConnection();
-
      - -
    5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
      6. - 
      -            Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. We create a JMS message producer on the session. This will be used to send the messages.
      7. - 
      -            MessageProducer messageProducer = session.createProducer(topic);
-
      - -
    7. We create a JMS text message that we are going to send.
      8. - 
      -            TextMessage message = session.createTextMessage("This is a text message");
-
      - -
    8. We send message to the queue
      9. - 
      -            messageProducer.send(message);
-
      - -

      Now that we have a message in the queue, we will manage the queue by retrieving the number of messages in the queue - (i.e. 1) and by removing the message which has been sent in step 8.

      - -
    9. We retrieve the ObjectName corresponding to the queue using a helper class ObjectNameBuilder
      10. - 
      -              ObjectName on = ObjectNameBuilder.DEFAULT.getJMSQueueObjectName(queue.getQueueName());
-
      - -
    10. We create a JMX Connector to connect to the server's MBeanServer using the standard JMX service URL
      11. - 
      -            JMXConnector connector = JMXConnectorFactory.connect(new JMXServiceURL(JMX_URL), new HashMap());
-
      - -
    11. We retrieve a MBeanServerConnection from the JMX connector
      12. - 
      -           TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
-
      - -
    12. We create a JMSQueueControl proxy to manage the queue on the server
      13. - 
      -            JMSQueueControl queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
-                                                                                              on,
-                                                                                              JMSQueueControl.class,
-                                                                                              false);
-             
-
      - -
    13. We use this mbean proxy to retrieve the number of messages in the queue using the getMessageCount method
      14. - 
      -            System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");
-
      - -
    14. We will now remove the message sent at step 8 using the removeMessage method with the JMS Message ID of the message
      15. - 
      -            System.out.println("message has been removed: " + queueControl.removeMessage(message.getJMSMessageID()));
-
      - -
    15. We use again the mbean proxy to retrieve the number of messages. This time, it will display 0 messages
      16. - 
      -            System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");
-
      - -
    16. Now we have finish the management operations, we close the JMX connector
      17. - 
      -            connector.close()
-
      - -

      We will now try to consume the message sent to the queue but it won't be there: it has been removed by the management operation

      - -
    17. We create a JMS message consumer on the queue
      18. - 
      -            MessageConsumer messageConsumer = session.createConsumer(queue);
-
      - -
    18. We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started
      19. - 
      -            connection.start();
-
      - -
    19. We try to receive a message from the queue. Since there is none, the call will timeout after 5000ms and messageReceived will be null -
      20. - 
      -            TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
-            System.out.println("Received message: " + messageReceived);
-
      - -
    20. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      21. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - diff --git a/examples/features/standard/jmx/readme.md b/examples/features/standard/jmx/readme.md new file mode 100644 index 0000000000..19a72a1e39 --- /dev/null +++ b/examples/features/standard/jmx/readme.md @@ -0,0 +1,9 @@ +# JMX Management Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how to manage ActiveMQ Artemis using [JMX](http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/) + +## More information + +* [Java management guide](http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html) \ No newline at end of file diff --git a/examples/features/standard/jmx/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/jmx/src/main/resources/activemq/server0/broker.xml index 7576376219..5d17696c84 100644 --- a/examples/features/standard/jmx/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/jmx/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -53,7 +51,7 @@ under the License. - +
    diff --git a/examples/features/standard/large-message/pom.xml b/examples/features/standard/large-message/pom.xml index 020a7b13f7..423e7e3a64 100644 --- a/examples/features/standard/large-message/pom.xml +++ b/examples/features/standard/large-message/pom.xml @@ -82,7 +82,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/large-message/readme.html b/examples/features/standard/large-message/readme.html deleted file mode 100644 index 0dc42cb623..0000000000 --- a/examples/features/standard/large-message/readme.html +++ /dev/null @@ -1,200 +0,0 @@ - - - - - ActiveMQ Artemis Large Message Example - - - - - -

    Large Message Example

    - - 
    To run the example, simply type mvn verify from this directory, This example will start and stop the server since it will look for a failure.
    - - -

    This example shows you how to send and receive very large messages with ActiveMQ Artemis.

    -

    ActiveMQ Artemis supports the sending and receiving of huge messages, much larger than can fit in available RAM - on the client or server. Effectively the only limit to message size is the amount of disk space you have on the server.

    -

    Large messages are persisted on the server so they can survive a server restart. In other words ActiveMQ Artemis doesn't just - do a simple socket stream from the sender to the consumer.

    -

    In order to do this ActiveMQ Artemis provides an extension to JMS where you can use an InputStream or OutputStream as the source and destination for your messages. You can send messages as large as it would fit in your disk.

    -

    You may also choose to read LargeMessages using the regular ByteStream or ByteMessage methods, but using the InputStream and OutputStream will provide you a much better performance

    - -

    Example step-by-step

    -

    In this example we limit both the server and the client to be running in a maximum of 50MB of RAM, - and we send a message with a body of size 256MB.

    -

    ActiveMQ Artemis can support much large message sizes but we - choose these sizes and limit RAM so the example runs more quickly.

    -

    We create a file on disk representing the message body, create - a FileInputStream on that file and set that InputStream as the body of the message before sending.

    -

    The message is sent, then we stop the server, and restart it. This demonstrates the large message will survive a restart of the server.

    -

    Once the server is restarted we receive the message and stream it's body to another file on disk.

    - -
      -
    1. Create an initial context to perform the JNDI lookup.
      2. - 
      -           initialContext = getContext(0);
-
      - -
    2. Perfom a lookup on the queue.
      3. - 
      -           Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. Perform a lookup on the Connection Factory. This ConnectionFactory has a special attribute set on it. activemq-jms.xml) - Messages with more than 10K are considered large.
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
-
      - -
    4. Create the JMS objects for sending the message.
      5. - 
      -           
-        connection = cf.createConnection();
-
-        Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
-        MessageProducer producer = session.createProducer(queue);
-           
-
      - -
    5. Create a huge file - this will form the body of the message we will send.
      6. - 
      -           
-        File fileInput = new File("huge_message_to_send.dat");
-
-        fileInput.createNewFile();
-
-        createFile(fileInput, FILE_SIZE);
-           
-
      - -
    6. Create a BytesMessage
      7. - 
      -          BytesMessage message = session.createBytesMessage();
-
      - -
    7. We set the InputStream on the message. When sending the message will read the InputStream - until it gets EOF. In this case we point the InputStream at a file on disk, and it will suck up the entire - file, however we could use any InputStream not just a FileInputStream.
      8. - 
      
-         FileInputStream fileInputStream = new FileInputStream(fileInput);
-
-         BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream);
-
-         message.setObjectProperty("JMS_AMQ_InputStream", bufferedInput);
-
      - -
    8. Send the Message.
      9. - 
      
-         producer.send(message);
-
      - - -
    9. We send message to the queue. After the send completion the message file will be located at ./build/data/largeMessages
      10. - 
      -           messageProducer.send(message);
-
      - -
    10. - To demonstrate that that we're not simply streaming the message from sending to consumer, we stop - the server and restart it before consuming the message. This demonstrates that the large message gets persisted, like a - normal persistent message, on the server. If you look at ./build/data/largeMessages you will see the largeMessage - stored on disk the server. -
      11. - 
      -           
-        connection.close();
-
-        initialContext.close();
-
-        stopServer(0);
-
-        // Give the server a little time to shutdown properly
-        Thread.sleep(5000);
-
-        startServer(0);
-           
-
      - -
    11. Now the server is restarted we can recreate the JMS Objects, and start the new connection.
      12. - 
      -           
-        initialContext = getContext(0);
-
-        queue = (Queue)initialContext.lookup("/queue/exampleQueue");
-
-        cf = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
-
-        connection = cf.createConnection();
-
-        session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
-        MessageConsumer messageConsumer = session.createConsumer(queue);
-
-        connection.start();
-
-           
-
      - -
    12. Receive the message. When we receive the large message we initially just receive the message with - an empty body.
      13. - 
      BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000);
-
      - -
    13. We set an OutputStream on the message. This causes the message body to be written to the - OutputStream until there are no more bytes to be written. - You don't have to use a FileOutputStream, you can use any OutputStream. - You may choose to use the regular BytesMessage or - StreamMessage interface but this method is much faster for large messages.
      14. - 
      
-         File outputFile = new File("huge_message_received.dat");
-
-         FileOutputStream fileOutputStream = new FileOutputStream(outputFile);
-
-         BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream);
-
-
      - -
    14. This will save the stream and wait until the entire message is written before continuing.
      15. - 
      
-         messageReceived.setObjectProperty("JMS_AMQ_SaveStream", bufferedOutput);
-
      - -
    15. Be sure to close our resources!
      16. - - 
      -           
-           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - - diff --git a/examples/features/standard/large-message/readme.md b/examples/features/standard/large-message/readme.md new file mode 100644 index 0000000000..144881bb71 --- /dev/null +++ b/examples/features/standard/large-message/readme.md @@ -0,0 +1,25 @@ +# Large Message Example + +To run the example, simply type **mvn verify** from this directory, This example will start and stop the broker since it will look for a failure. + +This example shows you how to send and receive very large messages with ActiveMQ Artemis. + +ActiveMQ Artemis supports the sending and receiving of huge messages, much larger than can fit in available RAM on the client or server. Effectively the only limit to message size is the amount of disk space you have on the server. + +Large messages are persisted on the broker so they can survive a broker restart. In other words ActiveMQ Artemis doesn't just do a simple socket stream from the sender to the consumer. + +In order to do this ActiveMQ Artemis provides an extension to JMS where you can use an InputStream or OutputStream as the source or destination for your messages respectively. You can send messages as large as it would fit in your disk. + +You may also choose to read LargeMessages using the regular ByteStream or ByteMessage methods, but using the InputStream or OutputStream will provide you a much better performance. + +## Example step-by-step + +In this example we limit both the broker and the client to be running in a maximum of 50MB of RAM, and we send a message with a body of size 2GiB. + +ActiveMQ Artemis can support much large message sizes but we choose these sizes and limit RAM so the example runs more quickly. + +We create a file on disk representing the message body, create a FileInputStream on that file and set that InputStream as the body of the message before sending. + +The message is sent, then we stop the server, and restart it. This demonstrates the large message will survive a restart of the server. + +Once the broker is restarted we receive the message and stream it's body to another file on disk. \ No newline at end of file diff --git a/examples/features/standard/last-value-queue/pom.xml b/examples/features/standard/last-value-queue/pom.xml index e2e9c0c4c4..85a479110d 100644 --- a/examples/features/standard/last-value-queue/pom.xml +++ b/examples/features/standard/last-value-queue/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/last-value-queue/readme.html b/examples/features/standard/last-value-queue/readme.html deleted file mode 100644 index 1fb58eec1e..0000000000 --- a/examples/features/standard/last-value-queue/readme.html +++ /dev/null @@ -1,162 +0,0 @@ - - - - - ActiveMQ Artemis Last-Value Queue Example - - - - - -

    Last-Value Queue Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to configure and use last-value queues.

    -

    Last-Value queues are special queues which discard any messages when a newer message with the same value for a well-defined Last-Value property is put in the queue. - In other words, a Last-Value queue only retains the last value.

    -

    A typical example for Last-Value queue is for stock prices, where you are only interested by the latest value for a particular stock.

    - -

    The example will send 3 messages with the same Last-Value property to a to a Last-Value queue.
    - We will browse the queue and see that only the last message is in the queue, the first two messages have been discarded.
    - We will then consume from the queue the last message.

    - -

    Example setup

    -

    Last-Value queues are defined in the configuration file broker.xml:

    - 
    -         <address-setting match="jms.queue.lastValueQueue">
-                <last-value-queue>true</last-value-queue>
-         </address-setting>
-
    - -

    Example step-by-step

    -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/lastValueQueue");
-
      - -
    3. We look up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection, a session and a producer for the queue
      5. - 
      -            connection = cf.createConnection();
-            Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-            MessageProducer producer = session.createProducer(queue);
-
      - -
    5. We will create and send a text message with the Last-Value property set to STOCK_NAME
      6. - 
      -           TextMessage message = session.createTextMessage("1st message with Last-Value property set");
-           message.setStringProperty("_AMQ_LVQ_NAME", "STOCK_NAME");
-           producer.send(message);
-           System.out.format("Sent message: %s\n", message.getText());
-
      - -

      The Last-Value key is defined in ActiveMQ's MessageImpl class. Its value is "_AMQ_LVQ_NAME"

      - -
    6. We will create and send a second text message with the Last-Value property set to STOCK_NAME
      7. - 
      -           message = session.createTextMessage("2nd message with Last-Value property set");
-           message.setStringProperty("_AMQ_LVQ_NAME", "STOCK_NAME");
-           producer.send(message);
-           System.out.format("Sent message: %s\n", message.getText());
-
      - -
    7. We will create and send a third text message with the Last-Value property set to STOCK_NAME
      8. - 
      -           message = session.createTextMessage("3rd message with Last-Value property set");
-           message.setStringProperty("_AMQ_LVQ_NAME", "STOCK_NAME");
-           producer.send(message);
-           System.out.format("Sent message: %s\n", message.getText());
-
      - -

      When the 2nd message was sent to the queue, the 1st message was discarded.
      - Similarly, when the 3rd message was sent to the queue, the 2nd message was discarded.
      - Only the 3rd message remains in the queue.

      - -
    8. We will browse the queue. There will be a single message displayed: the 3rd message
      9. - 
      -            QueueBrowser browser = session.createBrowser(queue);
-            Enumeration enumeration = browser.getEnumeration();
-            while (enumeration.hasMoreElements())
-            {
-               TextMessage messageInTheQueue = (TextMessage)enumeration.nextElement();
-               System.out.format("Message in the queue: %s\n", messageInTheQueue.getText());
-            }
-            browser.close();
-            
-
      - -

      We will now consume the message on the queue

      - -
    9. We create a JMS message consumer on the queue
      10. - 
      -            MessageConsumer messageConsumer = session.createConsumer(queue);
-
      - -
    10. We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started
      11. - 
      -           connection.start();
-
      - -
    11. We try to receive a message from the queue. It will be the 3rd message
      12. - 
      -            TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
-            System.out.format("Received message: %s\n", messageReceived.getText());
-
      - -
    12. We will try to receive another message but there is no other on the queue. The receive method will timeout after 5 seconds
      13. - 
      -            messageReceived = (TextMessage)messageConsumer.receive(5000);
-           System.out.format("Received message: %s\n", messageReceived);
-
      - -
    13. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      14. - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - diff --git a/examples/features/standard/last-value-queue/readme.md b/examples/features/standard/last-value-queue/readme.md new file mode 100644 index 0000000000..297d277970 --- /dev/null +++ b/examples/features/standard/last-value-queue/readme.md @@ -0,0 +1,15 @@ +# Last-Value Queue Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure and use last-value queues. + +Last-Value queues are special queues which discard any messages when a newer message with the same value for a well-defined _Last-Value_ property is put in the queue. In other words, a Last-Value queue only retains the last value. + +A typical example for Last-Value queue is for stock prices, where you are only interested by the latest value for a particular stock. + +The example will send 3 messages with the same _Last-Value_ property to a to a Last-Value queue. + +We will browse the queue and see that only the last message is in the queue, the first two messages have been discarded. + +We will then consume from the queue the _last_ message. \ No newline at end of file diff --git a/examples/features/standard/last-value-queue/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/last-value-queue/src/main/resources/activemq/server0/broker.xml index 65de32d013..d7017a0e23 100644 --- a/examples/features/standard/last-value-queue/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/last-value-queue/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -56,7 +54,7 @@ under the License. - +
    diff --git a/examples/features/standard/management-notifications/pom.xml b/examples/features/standard/management-notifications/pom.xml index 06bd8cb393..55dad3d904 100644 --- a/examples/features/standard/management-notifications/pom.xml +++ b/examples/features/standard/management-notifications/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/management-notifications/readme.html b/examples/features/standard/management-notifications/readme.html deleted file mode 100644 index 6ac1efa1ee..0000000000 --- a/examples/features/standard/management-notifications/readme.html +++ /dev/null @@ -1,215 +0,0 @@ - - - - - ActiveMQ Artemis Management Notification Example - - - - - -

    Management Notification Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows how to receive management notifications from ActiveMQ Artemis using JMS Messages.

    -

    ActiveMQ Artemis servers emit management notifications when events of interest occur (consumers are created or closed, - destinations are created or deleted, security authentication fails, etc.).
    - These notifications can be received either by using JMX (see JMX example) or by receiving JMS Messages - from a well-known destination.

    -

    This example will setup a JMS MessageListener to receive management notifications. We will also perform normal JMS operations to see the kind - of notifications they trigger.

    - -

    Example configuration

    - -

    ActiveMQ Artemis can configured to send JMS messages when management notifications are emitted on the server.

    -

    By default, the management name is called activemq.notifications but this can be configured in broker.xml. - For this example, we will set it to jms.topic.notificationsTopic to be able to receive notifications from a JMS Topic.

    - 
    -         <management-notification-address>jms.topic.notificationsTopic</management-notification-address>
-
    - -

    Since we want to lookup the notifications topic using JNDI, we also declare it in activemq-jms.xml - 

    -         <topic name="notificationsTopic">
-            <entry name="/topic/notificationsTopic"/>
-         </topic>
-
    -

    The notification queue requires permission to create/delete temporary queues and consume messages. - This is also configured in broker.xml

    - 
    -         
-         <security-setting match="jms.topic.notificationsTopic">
-            <permission type="consume" roles="guest"/>
-            <permission type="createNonDurableQueue" roles="guest"/>
-            <permission type="deleteNonDurableQueue" roles="guest"/>
-         </security-setting>
-
    - -

    Example step-by-step

    -x
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get its properties from client-jndi.properties
      2. - 
      -            InitialContext initialContext = getContext(0);
-
      - -
    2. We look up the JMS queue object from JNDI
      3. - 
      -            Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look up the JMS connection factory object from JNDI
      4. - 
      -            ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection, a session and a message producer for the example queue
      5. - 
      -            connection = cf.createConnection();
-            Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-            MessageProducer producer = session.createProducer(queue);
-
      - -
    5. We look up the JMS Topic used to receive the notifications from JNDI
      6. - 
      -            Topic notificationsTopic = (Topic) initialContext.lookup("/topic/notificationsTopic");
-
      - -
    6. We create a MessageConsumer for the notification queue and set its MessageListener. When a notification is received, we will simply display all the message properties
      7. - 
      -           MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
-           notificationConsumer.setMessageListener(new MessageListener()
-           {
-              public void onMessage(Message notif)
-              {
-                 System.out.println("------------------------");
-                 System.out.println("Received notification:");
-                 try
-                 {
-                    Enumeration propertyNames = notif.getPropertyNames();
-                    while (propertyNames.hasMoreElements())
-                    {
-                       String propertyName = (String)propertyNames.nextElement();
-                       System.out.format("  %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
-                    }
-                 }
-                 catch (JMSException e)
-                 {
-                 }
-                 System.out.println("------------------------");
-              }
-           });
-
      - -
    7. We start the connection to receive messages
      8. - 
      -            connection.start();
-
      - -

      Now that a message listener is setup to receive management notifications, we will perform regular JMS operations to - see what kind of notifications are triggered

      - -
    8. We create a JMS message consumer on the example queue
      9. - 
      -            MessageConsumer consumer = session.createConsumer(queue);
-
      - -

      This will generate a CONSUMER_CREATED notification: - 

      -            ------------------------
-            Received notification:
-              _AMQ_RoutingName: jms.queue.exampleQueue
-              _AMQ_Address: jms.queue.exampleQueue
-              ...
-              _AMQ_ConsumerCount: 1
-              ...
-              _AMQ_NotifType: CONSUMER_CREATED
-            ------------------------
-
      -

      The notification tells us that a consumer was created for the JMS queue exampleQueue. When the notification - was emitted, this consumer was the only one for the queue

      - -
    9. We close this consumer
      10. - 
      -            consumer.close();
-
      - -

      This will generate a CONSUMER_CLOSED notification: - 

      -            ------------------------
-            Received notification:
-              _AMQ_RoutingName: jms.queue.exampleQueue
-              _AMQ_Address: jms.queue.exampleQueue
-              ...
-              _AMQ_ConsumerCount: 0
-              ...
-              _AMQ_NotifType: CONSUMER_CLOSED
-            ------------------------
-
      -

      The notification tells us that a consumer was closed for the JMS queue exampleQueue. When the notification - was emitted, there were no other consumers on the queue

      - -
    10. As a last example, we will create a connection with invalid user credentials
      11. - 
      -            try
-            {
-               cf.createConnection("not.a.valid.user", "not.a.valid.password");
-            } catch (JMSException e)
-            {
-            }
-
      - -

      This will generate a SECURITY_AUTHENTICATION_VIOLATION notification: - 

      -            ------------------------
-            Received notification:
-              _AMQ_User: not.a.valid.user
-              ...
-              _AMQ_NotifType: SECURITY_AUTHENTICATION_VIOLATION
-            ------------------------
-            
-
      -

      The notification tells us that a user named not.a.valid.user failed to authenticate when creating a connection to ActiveMQ Artemis.

      - -
    11. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      12. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - - diff --git a/examples/features/standard/management-notifications/readme.md b/examples/features/standard/management-notifications/readme.md new file mode 100644 index 0000000000..9cee5e0ceb --- /dev/null +++ b/examples/features/standard/management-notifications/readme.md @@ -0,0 +1,26 @@ +# Management Notification Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how to receive management notifications from ActiveMQ Artemis using JMS Messages. + +ActiveMQ Artemis servers emit management notifications when events of interest occur (consumers are created or closed, destinations are created or deleted, security authentication fails, etc.). +These notifications can be received either by using JMX (see "jmx" example) or by receiving JMS Messages from a well-known destination. + +This example will setup a JMS MessageListener to receive management notifications. We will also perform normal JMS operations to see the kind of notifications they trigger. + +## Example configuration + +ActiveMQ Artemis can configured to send JMS messages when management notifications are emitted on the server. + +By default, the management name is called `activemq.notifications` but this can be configured in [broker.xml](server0/broker.xml). For this example, we will set it to `jms.topic.notificationsTopic` to be able to receive notifications from a JMS Topic. + + jms.topic.notificationsTopic + +The notification queue requires permission to create/delete temporary queues and consume messages. This is also configured in [broker.xml](server0/broker.xml) + + + + + + \ No newline at end of file diff --git a/examples/features/standard/management-notifications/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/management-notifications/src/main/resources/activemq/server0/broker.xml index a42fc9c4b7..c340a729fb 100644 --- a/examples/features/standard/management-notifications/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/management-notifications/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -67,7 +65,7 @@ under the License. - +
    diff --git a/examples/features/standard/management/pom.xml b/examples/features/standard/management/pom.xml index e1d1a64add..94a302ad7e 100644 --- a/examples/features/standard/management/pom.xml +++ b/examples/features/standard/management/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/management/readme.html b/examples/features/standard/management/readme.html deleted file mode 100644 index 30057ba202..0000000000 --- a/examples/features/standard/management/readme.html +++ /dev/null @@ -1,208 +0,0 @@ - - - - - ActiveMQ Artemis Management Example - - - - - -

    Management Example

    -

    This example shows how to manage ActiveMQ Artemis using JMS Messages to invoke management operations on the server.

    -

    To manage ActiveMQ Artemis using JMX, see the JMX example.

    - -

    Example configuration

    - -

    ActiveMQ Artemis can be managed by sending JMS messages with specific properties to its management queue.

    -

    By default, the management name is called activemq.management but this can be configured in broker.xml - 
    -         <management-address>activemq.management</management-address>
-
    - -

    The management queue requires a "special" user permission manage to be able to receive management messages. - This is also configured in broker.xml

    - 
    -         <security-setting match="activemq.management">
-            <permission type="manage" roles="guest" />
-         </security-setting>
-
    - -

    Example step-by-step

    -

    To run the example, simply type mvn verify -Pexample from this directory

    -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get its properties from client-jndi.properties
      2. - 
      -            InitialContext initialContext = getContext(0);
-
      - -
    2. We look up the JMS queue object from JNDI
      3. - 
      -            Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look up the JMS connection factory object from JNDI
      4. - 
      -            ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -            connection = cf.createConnection();
-
      - -
    5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
      6. - 
      -            Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. We create a JMS message producer on the session. This will be used to send the messages.
      7. - 
      -            MessageProducer messageProducer = session.createProducer(topic);
-
      - -
    7. We create a JMS text message that we are going to send.
      8. - 
      -            TextMessage message = session.createTextMessage("This is a text message");
-
      - -
    8. We send message to the queue
      9. - 
      -            messageProducer.send(message);
-
      - -

      Now that we have a message in the queue, we will manage the queue by retrieving the number of messages in the queue - (i.e. 1) and by removing the message which has been sent in step 8.

      - -
    9. We create the JMS management queue. This is a special queue which is not looked up from JNDI but instantiated directly
      10. - 
      -            Queue managementQueue = new ActiveMQQueue("activemq.management", "activemq.management");
-
      - -
    10. We create a QueueRequestor to send messages to the management queue and receive replies (see queue-requestor example)
      11. - 
      -            QueueRequestor requestor = new QueueRequestor(session, managementQueue);
-
      - -
    11. We start the connection to receive replies on the requestor
      12. - 
      -           connection.start()
-
      - -
    12. We create a JMS message which will be used as a management message
      13. - 
      -            Message m = session.createMessage();
-
      - -
    13. a management message has well-defined properties that ActiveMQ Artemis server needs to know to perform management operations.
      - We use a helper class JMSManagementHelper to fill these properties: -
        -
      • The name of the resource to manage jms.queue.exampleQueue - (i.e. jms.queue followed by the name of the queue as defined in activemq-jms.xml)
        • -
      • In our case, the name of the attribute to retrieve MessageCount
        • -
      -
      14. - 
      -            JMSManagementHelper.putAttribute(m, "jms.queue.exampleQueue", "MessageCount");
-
      - -
    14. We send the management message using the requestor and wait for a reply
      15. - 
      -            Message reply = requestor.request(m);
-
      - -
    15. We use a helper class JMSManagementHelper to retrieve the result from the reply message: - 
      -            int messageCount = (Integer)JMSManagementHelper.getResult(reply);
-            System.out.println(queue.getQueueName() + " contains " + messageCount + " messages");
-
      - -
    16. We create another JMS message to use as a management message
      17. - 
      -            m = session.createMessage();
-
      - -
    17. This time, we fill the management message with properties to invoke a management operation on the queue -
        -
      • the name of the resource jms.queue.exampleQueue
        • -
      • the name of the management operation removeMessage
        • -
      • any parameters required to invoke the management operations (in our case, the JMS Message ID of the message sent in step 8)
        • -
      -
      18. - 
      -            JMSManagementHelper.putOperationInvocation(m, "jms.queue.exampleQueue", "removeMessage", message.getJMSMessageID());
-
      - -
    18. Again, we use the requestor to send the management message and wait for a reply
      19. - 
      -            reply = requestor.request(m);
-
      - -
    19. We use the helper class to check that the operation was successfully invoked on the server
      20. - 
      -            boolean success = JMSManagementHelper.hasOperationSucceeded(reply);
-            System.out.println("operation invocation has succeeded: " + success);
-
      - -
    20. We use a helper class JMSManagementHelper to retrieve the result from the reply message: - (in our case, the removeMessage method returns a boolean)
      21. - 
      -            boolean messageRemoved = (Boolean)JMSManagementHelper.getResult(reply);
-            System.out.println("message has been removed: " + messageRemoved);
-
      - -

      We will now consume the message from the queue but there will be none: the message sent at step 8 was removed by the management operation

      - -
    21. We create a JMS message consumer on the queue
      22. - 
      -            MessageConsumer messageConsumer = session.createConsumer(queue);
-
      - -
    22. We try to receive a message from the queue. Since there is none, the call will timeout after 5000ms and messageReceived will be null -
      23. - 
      -            TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
-            System.out.println("Received message: " + messageReceived);
-
      - -
    23. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      24. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - diff --git a/examples/features/standard/management/readme.md b/examples/features/standard/management/readme.md new file mode 100644 index 0000000000..425c22ad3c --- /dev/null +++ b/examples/features/standard/management/readme.md @@ -0,0 +1,19 @@ +# Management Example + +This example shows how to manage ActiveMQ Artemis using JMS Messages to invoke management operations on the server. + +To manage ActiveMQ Artemis using JMX, see the "jmx" example. + +## Example configuration + +ActiveMQ Artemis can be managed by sending JMS messages with specific properties to its _management_ queue. + +By default, the management name is called `activemq.management` but this can be configured in broker.xml like so: + + activemq.management + +The management queue requires a "special" user permission `manage` to be able to receive management messages. This is also configured in broker.xml: + + + + \ No newline at end of file diff --git a/examples/features/standard/management/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/management/src/main/resources/activemq/server0/broker.xml index d8f997e19c..6d041c7ff1 100644 --- a/examples/features/standard/management/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/management/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -65,7 +63,7 @@ under the License. - +
    diff --git a/examples/features/standard/message-counters/pom.xml b/examples/features/standard/message-counters/pom.xml index 30b58e5264..fbd07c434b 100644 --- a/examples/features/standard/message-counters/pom.xml +++ b/examples/features/standard/message-counters/pom.xml @@ -108,7 +108,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/message-counters/readme.html b/examples/features/standard/message-counters/readme.html deleted file mode 100644 index 40e247a7bd..0000000000 --- a/examples/features/standard/message-counters/readme.html +++ /dev/null @@ -1,197 +0,0 @@ - - - - - ActiveMQ Artemis Message Counter Example - - - - - -

    JMS Message Counter Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to use message counters to obtain message information for a JMS queue.

    -

    The example will show how to configure sampling of message counters.
    - We will produce and consume 1 message from a queue. Interleaved with the JMS operation, we will retrieve the queue's message counters - at different times to display the metrics on the queue. -

    -

    Example setup

    -

    Message counter is configured in the server configuration file broker.xml:

    - 
    -         <message-counter-enabled>true</message-counter-enabled>
-         <message-counter-sample-period>2000</message-counter-sample-period>
-         <message-counter-max-day-history>2</message-counter-max-day-history>
-
    -

    By default, Message counter is not enabled (for performance reason). To enable them, set message-counter-enabled to true.
    - Queues are sampled every 10 seconds by default. For this example we will reduce it to 2 seconds by setting message-counter-sample-period to 2000.
    - ActiveMQ Artemis holds in memory the message counters' history for a maximum number of days (10 by default). We can change the number of days the history is kept by setting - the message-counter-max-day-history parameter.

    -

    The sample period and the max day history parameters have a small impact on the performance of ActiveMQ Artemis (the resources taken to sample a queue are not available to the system's - normal use). You should set these parameters accordingly to the use and throughput of your messages.

    - -

    Example step-by-step

    -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection, session and producer for the queue
      5. - 
      -            connection = cf.createQueueConnection();
-            QueueSession session = connection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
-            MessageProducer producer = session.createProducer(queue);
-
      - -
    5. We create and send a JMS text message
      6. - 
      -            TextMessage message = session.createTextMessage("This is a text message");
-            producer.send(message);
-            System.out.println("Sent message: " + message.getText());
-
      - -
    6. We will now sleep a little bit to be sure the queue is sample. Since we have configure the sample period to be 2 seconds, - we will sleep for 3 seconds to be sure that a sample is taken
      7. - 
      -            System.out.println("Sleep a little bit to have the queue sampled...");
-            Thread.sleep(3000);
-
      - -

      We now need to retrieve the message counters. They're available from the JMS Queue management resource. In this example, we - will retrieve them using JMX (see the JMX example for a more complete description). You can also use JMS message to retrieve them (see the Management example to - learn about managing ActiveMQ Artemis using JMS messages).

      - -
    7. We retrieve the JMX MBean used to manage the JMS queue
      8. - 
      -            ObjectName on = ObjectNameBuilder.DEFAULT.getJMSQueueObjectName(queue.getQueueName());
-            JMXConnector connector = JMXConnectorFactory.connect(new JMXServiceURL(JMX_URL), new HashMap());
-            MBeanServerConnection mbsc = connector.getMBeanServerConnection();
-            JMSQueueControl queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
-                                                                                              on,
-                                                                                              JMSQueueControl.class,
-                                                                                              false);
-
      - -
    8. We retrieve the message counter and display them. MessageCounters are retrieved as JSON Strings for portability reason (whether - JMX is used for management or JMS messages). To make it simpler to use them in the code, there is a MessageCounterInfo data structure.
      9. - 
      -            String counters = queueControl.listMessageCounter();
-            MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);>
-
      - -
    9. We display the message counters
      10. - 
      -            displayMessageCounter(messageCounter);
-
      - -

      The message counter contains a variety of metrics on the queue which is sampled (total messages added to the queue, current depth of the queue, deltas since the last sample, timestamp - of the last message added, timestamp of the last sample, etc.)

      - 
      -            
-            private void displayMessageCounter(MessageCounterInfo counter)
-            {
-               System.out.format("%s (sample updated at %s)\n",  counter.getName(), counter.getUdpateTimestamp());
-               System.out.format("   %s message(s) added to the queue (since last sample: %s)\n", counter.getCount(),
-                                                                                                  counter.getCountDelta());
-               System.out.format("   %s message(s) in the queue (since last sample: %s)\n", counter.getDepth(),
-                                                                                            counter.getDepthDelta());
-               System.out.format("   last message added at %s\n\n", counter.getLastAddTimestamp());
-            }
-
      - -
    10. We sleep again to have the queue sampled
      11. - 
      -            System.out.println("Sleep a little bit again...");
-            Thread.sleep(3000);
-
      - -
    11. We list the message counters again
      12. - 
      -            counters = queueControl.listMessageCounter();
-            messageCounter = MessageCounterInfo.fromJSON(counters);
-            displayMessageCounter(messageCounter);
-
      - -

      We will now consume a message from the queue before listing a last time the message counters

      - -
    12. We create a consumer for the queue
      13. - 
      -            MessageConsumer consumer = session.createConsumer(queue);
-
      - -
    13. We start the connection to receive messages on the consumer
      14. - 
      -           connection.start();
-
      - -
    14. We receive a message from the queue
      15. - 
      -           TextMessage messageReceived = (TextMessage)consumer.receive(5000);
-           System.out.format("Received message: %s\n\n", messageReceived.getText());
-
      - -
    15. We sleep one last time to have the queue sampled
      16. - 
      -            System.out.println("Sleep a little bit one last time...");
-            Thread.sleep(3000);
-
      - -
    16. We list the message counters a final time (this time with no message in the queue)
      17. - 
      -            counters = queueControl.listMessageCounter();
-            messageCounter = MessageCounterInfo.fromJSON(counters);
-            displayMessageCounter(messageCounter);
-
      - -

      -
    17. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      18. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -
  • User Manual's Message Counters chapter
    • -
  • MessageCounterInfo is a helper class used - to create a MessageCounterInfo object from the JSON String which represents message counters
    • - - diff --git a/examples/features/standard/message-counters/readme.md b/examples/features/standard/message-counters/readme.md new file mode 100644 index 0000000000..f5ff5a78cc --- /dev/null +++ b/examples/features/standard/message-counters/readme.md @@ -0,0 +1,23 @@ +# JMS Message Counter Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to use message counters to obtain message information for a JMS queue. + +The example will show how to configure sampling of message counters. + +We will produce and consume 1 message from a queue. Interleaved with the JMS operation, we will retrieve the queue's message counters at different times to display the metrics on the queue. + +## Example setup + +Message counter is configured in the broker configuration file broker.xml: + + true + 2000 + 2 + +By default, message counters are not enabled (for performance reason). To enable them, set `message-counter-enabled` to `true`. +Queues are sampled every 10 seconds by default. For this example we will reduce it to 2 seconds by setting `message-counter-sample-period` to `2000`. +ActiveMQ Artemis holds in memory the message counters' history for a maximum number of days (10 by default). We can change the number of days the history is kept by setting the `message-counter-max-day-history` parameter. + +The sample period and the max day history parameters have a small impact on the performance of ActiveMQ Artemis (the resources taken to sample a queue are not available to the system's normal use). You should set these parameters accordingly to the use and throughput of your messages. \ No newline at end of file diff --git a/examples/features/standard/message-counters/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/message-counters/src/main/resources/activemq/server0/broker.xml index cfb826255d..ec9a8b9b92 100644 --- a/examples/features/standard/message-counters/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/message-counters/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -72,7 +70,7 @@ under the License. - +
    diff --git a/examples/features/standard/message-group/pom.xml b/examples/features/standard/message-group/pom.xml index 8ca2809116..46cadb43de 100644 --- a/examples/features/standard/message-group/pom.xml +++ b/examples/features/standard/message-group/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/message-group/readme.html b/examples/features/standard/message-group/readme.html deleted file mode 100644 index 277d2f6a5f..0000000000 --- a/examples/features/standard/message-group/readme.html +++ /dev/null @@ -1,152 +0,0 @@ - - - - - ActiveMQ Artemis Message Group Example - - - - - -

    Message Group Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to configure and use message groups with ActiveMQ Artemis.

    - -

    Message groups are sets of messages that has the following characteristics:

    -
  • Messages in a message group share the same group id, i.e. they have same JMSXGroupID string property values.
    • -
  • Messages in a message group will be all delivered to no more than one of the queue's consumers. The consumer that receives the - first message of a group will receive all the messages that belong to the group.
    • - -

    You can make any message belong to a message group by setting its 'JMSXGroupID' string property to the group id. - In this example we create a message group 'Group-0'. And make such a message group of 10 messages. It also create two consumers on the queue - where the 10 'Group-0' group messages are to be sent. You can see that with message grouping enabled, all the 10 messages will be received by - the first consumer. The second consumer will receive none.

    - -

    Alternatively, ActiveMQ's connection factories can be configured to auto group messages. By setting autogroup to true on the ActiveMQConnectionFactory - (or setting <autogroup>true</autogroup> in activemq-jms.xml's connection factory settings), a random unique id - will be picked to create a message group. Every messages sent by a producer created from this connection factory will automatically - be part of this message group.

    - -

    Example step-by-step

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look-up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -           connection = cf.createConnection();
-
      - -
    5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
      6. - 
      -           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. We create a JMS message producer on the session. This will be used to send the messages.
      7. - 
      -          MessageProducer messageProducer = session.createProducer(topic);
-
      - -
    7. We create two consumers.
      8. - 
      -           
-          MessageConsumer consumer1 = session.createConsumer(queue);
-          consumer1.setMessageListener(new SimpleMessageListener("consumer-1"));
-          MessageConsumer consumer2 = session.createConsumer(queue);
-          consumer2.setMessageListener(new SimpleMessageListener("consumer-2"));
-          
-
      - -
    8. We create and send 10 text messages with group id 'Group-0'
      9. - 
      -           
-         int msgCount = 10;
-         TextMessage[] groupMessages = new TextMessage[msgCount];
-         for (int i = 0; i < msgCount; i++)
-         {
-            groupMessages[i] = session.createTextMessage("Group-0 message " + i);
-            groupMessages[i].setStringProperty("JMSXGroupID", "Group-0");
-            producer.send(groupMessages[i]);
-            System.out.println("Sent message: " + groupMessages[i].getText());
-         }
-           
-
      - -
    9. We start the connection.
      10. - 
      -           connection.start();
-
      - -
    10. We check the group messages are received by only one consumer
      11. - 
      -           
-         String trueReceiver = messageReceiverMap.get(groupMessages[0].getText());
-         for (TextMessage grpMsg : groupMessages)
-         {
-            String receiver = messageReceiverMap.get(grpMsg.getText());
-            if (!trueReceiver.equals(receiver))
-            {
-               System.out.println("Group message [" + grpMsg.getText() + "[ went to wrong receiver: " + receiver);
-               result = false;
-            }
-         }
-           
-
      - -
    11. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      12. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - - diff --git a/examples/features/standard/message-group/readme.md b/examples/features/standard/message-group/readme.md new file mode 100644 index 0000000000..b570bf3c64 --- /dev/null +++ b/examples/features/standard/message-group/readme.md @@ -0,0 +1,14 @@ +# Message Group Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure and use message groups with ActiveMQ Artemis. + +Message groups are sets of messages that has the following characteristics: + +* Messages in a message group share the same group id, i.e. they have same JMSXGroupID string property values. +* Messages in a message group will be all delivered to no more than one of the queue's consumers. The consumer that receives the first message of a group will receive all the messages that belong to the group. + +You can make any message belong to a message group by setting its 'JMSXGroupID' string property to the group id. In this example we create a message group 'Group-0'. And make such a message group of 10 messages. It also create two consumers on the queue where the 10 'Group-0' group messages are to be sent. You can see that with message grouping enabled, all the 10 messages will be received by the first consumer. The second consumer will receive none. + +Alternatively, ActiveMQ's connection factories can be configured to _auto group_ messages. By setting `autoGroup=true` in the client's URL a random unique id will be picked to create a message group. _Every messages_ sent by a producer created from this connection factory will automatically be part of this message group. \ No newline at end of file diff --git a/examples/features/standard/message-group2/pom.xml b/examples/features/standard/message-group2/pom.xml index 5d38995718..c447926de9 100644 --- a/examples/features/standard/message-group2/pom.xml +++ b/examples/features/standard/message-group2/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/message-group2/readme.html b/examples/features/standard/message-group2/readme.html deleted file mode 100644 index 983a4420f2..0000000000 --- a/examples/features/standard/message-group2/readme.html +++ /dev/null @@ -1,161 +0,0 @@ - - - - - ActiveMQ Artemis Message Group Example - - - - - -

    Message Group Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to configure and use message groups via a connection factory with ActiveMQ Artemis.

    - -

    Message groups are sets of messages that has the following characteristics:

    -
  • Messages in a message group share the same group id, i.e. they have same JMSXGroupID string property values.
    • -
  • Messages in a message group will be all delivered to no more than one of the queue's consumers. The consumer that receives the - first message of a group will receive all the messages that belongs to the group.
    • - -

    You can make any message belong to a message group by setting a 'group-id' on the connection factory. All producers created via this connection factory will set that group id on its messages. - In this example we set the group id 'Group-0'on a connection factory and send messages via 2 different producers and check that only 1 consumer receives them.

    - -

    Alternatively, ActiveMQ's connection factories can be configured to auto group messages. By setting autogroup to true on the ActiveMQConnectionFactory - (or setting <autogroup>true</autogroup> in activemq-jms.xml's connection factory settings), a random unique id - will be picked to create a message group. Every messages sent by a producer created from this connection factory will automatically - be part of this message group.

    - -

    Example step-by-step

    -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look-up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -           connection = cf.createConnection();
-
      - -
    5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
      6. - 
      -           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. We create 2 JMS message producers on the session. This will be used to send the messages.
      7. - 
      -          
-              MessageProducer producer1 = session.createProducer(queue);
-
-              MessageProducer producer2 = session.createProducer(queue);
-
      - -
    7. We create two consumers.
      8. - 
      -           
-          MessageConsumer consumer1 = session.createConsumer(queue);
-          consumer1.setMessageListener(new SimpleMessageListener("consumer-1"));
-          MessageConsumer consumer2 = session.createConsumer(queue);
-          consumer2.setMessageListener(new SimpleMessageListener("consumer-2"));
-          
-
      - -
    8. We create and send 10 text messages using each producer
      9. - 
      -           
-         int msgCount = 10;
-         for (int i = 0; i < msgCount; i++)
-         {
-            TextMessage m = session.createTextMessage("producer1 message " + i);
-            producer1.send(m);
-            System.out.println("Sent message: " + m.getText());
-            TextMessage m2 = session.createTextMessage("producer2 message " + i);
-            producer2.send(m2);
-            System.out.println("Sent message: " + m2.getText());
-         }
-           
-
      - -
    9. We start the connection.
      10. - 
      -           connection.start();
-
      - -
    10. We check the group messages are received by only one consumer
      11. - 
      -           
-            String trueReceiver = messageReceiverMap.get("producer1 message " + 0);
-            for (int i = 0; i < msgCount; i++)
-            {
-               String receiver = messageReceiverMap.get("producer1 message " + i);
-               if (!trueReceiver.equals(receiver))
-               {
-                  System.out.println("Group message [producer1 message " + i + "] went to wrong receiver: " + receiver);
-                  result = false;
-               }
-               receiver = messageReceiverMap.get("producer2 message " + i);
-               if (!trueReceiver.equals(receiver))
-               {
-                  System.out.println("Group message [producer2 message " + i + "] went to wrong receiver: " + receiver);
-                  result = false;
-               }
-            }
-
-           
-
      - -
    11. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      12. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - - diff --git a/examples/features/standard/message-group2/readme.md b/examples/features/standard/message-group2/readme.md new file mode 100644 index 0000000000..0a81e200f6 --- /dev/null +++ b/examples/features/standard/message-group2/readme.md @@ -0,0 +1,14 @@ +# Message Group Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure and use message groups via a connection factory with ActiveMQ Artemis. + +Message groups are sets of messages that has the following characteristics: + +* Messages in a message group share the same group id, i.e. they have same JMSXGroupID string property values. +* Messages in a message group will be all delivered to no more than one of the queue's consumers. The consumer that receives the first message of a group will receive all the messages that belongs to the group. + +You can make any message belong to a message group by setting a 'group-id' on the connection factory. All producers created via this connection factory will set that group id on its messages. In this example we set the group id 'Group-0'on a connection factory and send messages via 2 different producers and check that only 1 consumer receives them. + +Alternatively, ActiveMQ's connection factories can be configured to _auto group_ messages. By setting `autoGroup=true` in the client's URL a random unique id will be picked to create a message group. _Every messages_ sent by a producer created from this connection factory will automatically be part of this message group. \ No newline at end of file diff --git a/examples/features/standard/message-priority/pom.xml b/examples/features/standard/message-priority/pom.xml index 4e89d0ce7a..9c07a3b2ec 100644 --- a/examples/features/standard/message-priority/pom.xml +++ b/examples/features/standard/message-priority/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/message-priority/readme.html b/examples/features/standard/message-priority/readme.html deleted file mode 100644 index fc25297307..0000000000 --- a/examples/features/standard/message-priority/readme.html +++ /dev/null @@ -1,159 +0,0 @@ - - - - - ActiveMQ Artemis JMS Message Priority Example - - - - - -

    JMS Message Priority Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows how messages with different priorities are delivered in different orders.

    - -

    The Message Priority property carries the delivery preference of sent messages. It can be set by the message's - standard header field 'JMSPriority' as defined in JMS specification version 1.1. The value is of type - integer, ranging from 0 (the lowest) to 9 (the highest). When messages are being delivered, their priorities - will effect their order of delivery. Messages of higher priorities will likely be delivered before those - of lower priorities. Messages of equal priorities are delivered in the natural order of their arrival at - their destinations. Please consult the JMS 1.1 specification for full details.

    - -

    In this example, three messages are sent to a queue with different priorities. The first message is sent - with default priority (4), the second is sent with a higher priority (5), and the third has the highest - priority (9). At the receiving end, we will show the order of receiving of the three messages. You will - see that the third message, though last sent, will 'jump' forward to be the first one received. The second - is also received ahead of the message first sent, but behind the third message. The first message, regardless - of its being sent first, arrives last.

    - -

    Example step-by-step

    -

    To run the example, simply type mvn verify -Pexample from this directory

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look-up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -           connection = cf.createConnection();
-
      - -
    5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
      6. - 
      -           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. We create a JMS message producer on the session. This will be used to send the messages.
      7. - 
      -          MessageProducer messageProducer = session.createProducer(topic);
-
      - -
    7. We Create a JMS Message Consumer.
      8. - 
      -           
-           MessageConsumer redConsumer = session.createConsumer(queue);
-           redConsumer.setMessageListener(new SimpleMessageListener());
-           
-
      - -
    8. We Create three messages.
      9. - 
      -           
-           TextMessage[] sentMessages = new TextMessage[3];
-           sentMessages[0] = session.createTextMessage("first message");
-           sentMessages[1] = session.createTextMessage("second message");
-           sentMessages[2] = session.createTextMessage("third message");
-           
-
      - -
    9. Send the Messages, each has a different priority.
      10. - 
      -           
-           producer.send(sentMessages[0]);
-           System.out.println("Message sent: " + sentMessages[0].getText() + " with priority: " + sentMessages[0].getJMSPriority());
-           producer.send(sentMessages[1], DeliveryMode.NON_PERSISTENT, 5, 0);
-           System.out.println("Message sent: " + sentMessages[1].getText() + "with priority: " + sentMessages[1].getJMSPriority());
-           producer.send(sentMessages[2], DeliveryMode.NON_PERSISTENT, 9, 0);
-           System.out.println("Message sent: " + sentMessages[2].getText() + "with priority: " + sentMessages[2].getJMSPriority());
-           
-
      - -
    10. We start the connection now.
      11. - 
      -           
-           connection.start();
-           
-
      - -
    11. We wait for message delivery completion
      12. - 
      -           
-           Thread.sleep(5000);
-           
-
      - -
    12. We wait for message delivery completion
      13. - 
      -           
-           for (int i = 0; i < 3; i++)
-           {
-              TextMessage rm = msgReceived.get(i);
-              if (!rm.getText().equals(sentMessages[2-i].getText()))
-              {
-                 System.err.println("Priority is broken!");
-                 result = false;
-              }
-           }
-           
-
      - -
    13. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      14. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - - diff --git a/examples/features/standard/message-priority/readme.md b/examples/features/standard/message-priority/readme.md new file mode 100644 index 0000000000..e48746a57b --- /dev/null +++ b/examples/features/standard/message-priority/readme.md @@ -0,0 +1,9 @@ +# JMS Message Priority Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how messages with different priorities are delivered in different orders. + +The Message Priority property carries the delivery preference of sent messages. It can be set by the message's standard header field 'JMSPriority' as defined in JMS specification version 1.1\. The value is of type integer, ranging from 0 (the lowest) to 9 (the highest). When messages are being delivered, their priorities will effect their order of delivery. Messages of higher priorities will likely be delivered before those of lower priorities. Messages of equal priorities are delivered in the natural order of their arrival at their destinations. Please consult the JMS 1.1 specification for full details. + +In this example, three messages are sent to a queue with different priorities. The first message is sent with default priority (4), the second is sent with a higher priority (5), and the third has the highest priority (9). At the receiving end, we will show the order of receiving of the three messages. You will see that the third message, though last sent, will 'jump' forward to be the first one received. The second is also received ahead of the message first sent, but behind the third message. The first message, regardless of its being sent first, arrives last. \ No newline at end of file diff --git a/examples/features/standard/no-consumer-buffering/pom.xml b/examples/features/standard/no-consumer-buffering/pom.xml index 7a56f51ff4..dc1d5c5a9e 100644 --- a/examples/features/standard/no-consumer-buffering/pom.xml +++ b/examples/features/standard/no-consumer-buffering/pom.xml @@ -102,6 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/no-consumer-buffering/readme.html b/examples/features/standard/no-consumer-buffering/readme.html deleted file mode 100644 index 55a73a2950..0000000000 --- a/examples/features/standard/no-consumer-buffering/readme.html +++ /dev/null @@ -1,205 +0,0 @@ - - - - - ActiveMQ Artemis No Consumer Buffering Example - - - - - -

    No Consumer Buffering Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    By default, ActiveMQ Artemis consumers buffer messages from the server in a client side buffer - before actual delivery actually occurs.

    -

    This improves performance since otherwise every time you called receive() or had processed the last - message in a MessageListener onMessage() method, the ActiveMQ Artemis client would have to go the - server to request the next message involving a network round trip for every message reducing performance.

    -

    Therefore, by default, ActiveMQ Artemis pre-fetches messages into a buffer on each consumer. The total maximum size of - messages in bytes that will be buffered on each consumer is determined by the consumer-window-size - parameter on the connection factory.

    -

    In some cases it is not desirable to buffer any messages on the client side consumer.

    -

    An example would be an order queue which had multiple consumers that processed orders from the queue. - Each order takes a significant time to process, but each one should be processed in a timely fashion.

    -

    If orders were buffered in each consumer, and a new consumer was added that consumer would not be able - to process orders which were already in the client side buffer of another consumer.

    -

    To turn off client side buffering of messages, set consumer-window-size to zero.

    - -

    With ActiveMQ Artemis you can specify a maximum consume rate at which a JMS MessageConsumer will consume messages. - This can be specified when creating or deploying the connection factory. See activemq-jms.xml

    -

    Example step-by-step

    -

    In this example we specify a consumer-window-size of 0 bytes in the activemq-jms.xml - file when deploying the connection factory:

    - 
    -     
-   <connection-factory name="ConnectionFactory">
-      <connector-ref>netty-connector</connector-ref>
-      <entries>
-         <entry name="ConnectionFactory"/>
-      </entries>
-
-      <!-- We set the consumer window size to 0, which means messages are not buffered at all
-      on the client side -->
-      <consumer-window-size>0</consumer-window-size>
-
-   </connection-factory>
-     
-
    -

    We create a consumer on a queue and send 10 messages to it. We then create another consumer on - the same queue.

    -

    We then consume messages from each consumer in a semi-random order. We note that the messages - are consumed in the order they were sent.

    -

    If the messages had been buffered in each consumer they would not be available to be consumed - in an order determined afer delivery.

    - -
      -
    1. Create an initial context to perform the JNDI lookup.
      2. - 
      -           initialContext = getContext(0);
-
      - -
    2. Perfom a lookup on the queue
      3. - 
      -           Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. Perform a lookup on the Connection Factory
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
-
      - -
    4. Create a JMS Connection
      5. - 
      -           connection = cf.createConnection();
-
      - -
    5. Create a JMS Session
      6. - 
      -           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. Create a JMS MessageProducer
      7. - 
      -          MessageProducer producer = session.createProducer(queue);
-
      - -
    7. Create a JMS MessageConsumer
      8. - 
      -           MessageConsumer consumer1 = session.createConsumer(queue);
-
      - -
    8. Start the connection
      9. - - 
      -           
-     connection.start();
-           
-
      - - -
    9. Send 10 messages to the queue
      10. - 
      -           
-     final int numMessages = 10;
-
-     for (int i = 0; i < numMessages; i++)
-     {
-        TextMessage message = session.createTextMessage("This is text message: " + i);
-
-        producer.send(message);
-     }
-           
-
      - -
    10. Create another JMS MessageConsumer on the same queue.
      11. - 
      -           MessageConsumer consumer2 = session.createConsumer(queue);
-
      - -
    11. Consume three messages from consumer2
      12. - - 
      -           
-   for (int i = 0; i < 3; i++)
-   {
-      TextMessage message = (TextMessage)consumer2.receive(2000);
-
-      System.out.println("Consumed message from consumer2: " + message.getText());
-   }
-           
-
      - -
    12. Consume five messages from consumer1
      13. - - 
      -           
-   for (int i = 0; i < 5; i++)
-   {
-      TextMessage message = (TextMessage)consumer1.receive(2000);
-
-      System.out.println("Consumed message from consumer1: " + message.getText());
-   }
-           
-
      - -
    13. Consume two more messages from consumer2
      14. - - 
      -           
-   for (int i = 0; i < 2; i++)
-   {
-      TextMessage message = (TextMessage)consumer1.receive(2000);
-
-      System.out.println("Consumed message from consumer2: " + message.getText());
-   }
-           
-
      - - -
    14. Be sure to close our resources!
      15. - - 
      -           
-           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - -

    More information

    - - - - - diff --git a/examples/features/standard/no-consumer-buffering/readme.md b/examples/features/standard/no-consumer-buffering/readme.md new file mode 100644 index 0000000000..5ae359bb25 --- /dev/null +++ b/examples/features/standard/no-consumer-buffering/readme.md @@ -0,0 +1,29 @@ +# No Consumer Buffering Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +By default, ActiveMQ Artemis consumers buffer messages from the broker in a client side buffer before actual delivery actually occurs. + +This improves performance since otherwise every time you called receive() or had processed the last message in a MessageListener onMessage() method, the ActiveMQ Artemis client would have to go the broker to request the next message involving a network round trip for every message reducing performance. + +Therefore, by default, ActiveMQ Artemis pre-fetches messages into a buffer on each consumer. The total maximum size of messages in bytes that will be buffered on each consumer is determined by the `consumerWindowSize` parameter on the connection URL. + +In some cases it is not desirable to buffer any messages on the client side consumer. + +An example would be an order queue which had multiple consumers that processed orders from the queue. Each order takes a significant time to process, but each one should be processed in a timely fashion. + +If orders were buffered in each consumer, and a new consumer was added that consumer would not be able to process orders which were already in the client side buffer of another consumer. + +To turn off client side buffering of messages, set `consumerWindowSize` to zero. + +With ActiveMQ Artemis you can specify a maximum consume rate at which a JMS MessageConsumer will consume messages. This can be specified when configuring the connection URL. + +## Example step-by-step + +In this example we specify a `consumerWindowSize` of `0` bytes on the connection URL in `jndi.properties`. + +We create a consumer on a queue and send 10 messages to it. We then create another consumer on the same queue. + +We then consume messages from each consumer in a semi-random order. We note that the messages are consumed in the order they were sent. + +If the messages had been buffered in each consumer they would not be available to be consumed in an order determined after delivery. \ No newline at end of file diff --git a/examples/features/standard/paging/pom.xml b/examples/features/standard/paging/pom.xml index 40cdf9115c..aa304fb792 100644 --- a/examples/features/standard/paging/pom.xml +++ b/examples/features/standard/paging/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/paging/readme.html b/examples/features/standard/paging/readme.html deleted file mode 100644 index 7c74320f05..0000000000 --- a/examples/features/standard/paging/readme.html +++ /dev/null @@ -1,187 +0,0 @@ - - - - - ActiveMQ Artemis Paging Example - - - - - -

    Paging Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows how ActiveMQ Artemis would avoid running out of memory resources by paging messages.

    -

    A maxSize can be specified per Destination via the destinations settings configuration file (broker.xml).

    -

    When messages routed to an address exceed the specified maxSize the server will begin to write messages to the file - system, this is called paging. This will continue to occur until messages have been delivered to consumers and subsequently - acknowledged freeing up memory. Messages will then be read from the file system , i.e. depaged, and routed as normal.

    -

    Acknowledgement plays an important factor on paging as messages will stay on the file system until the memory is released - so it is important to make sure that the client acknowledges its messages.

    - - -

    Example step-by-step

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS connection factory object from JNDI
      3. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    3. We look-up the JMS queue object from JNDI. pagingQueue is configured to hold a very limited number of bytes in memory
      4. - 
      -           Queue pageQueue = (Queue) initialContext.lookup("/queue/pagingQueue");
-
      - -
    4. We look-up the JMS queue object from JNDI.
      5. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    5. We create a JMS connection
      6. - 
      -           connection = cf.createConnection();
-
      - -
    6. We create a JMS session. The session is created as non transacted. We will use client acknowledgement on this example.
      7. - 
      -           Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);
-
      - - -
    7. Create a JMS Message Producer for pageQueueAddress
      8. - 
      
-         MessageProducer pageMessageProducer = session.createProducer(pageQueue);
-
      - -
    8. We don't need persistent messages in order to use paging. (This step is optional)
      9. - 
      
-         pageMessageProducer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
-
      - -
    9. Create a Binary Bytes Message with 10K arbitrary bytes
      10. - 
      
-         BytesMessage message = session.createBytesMessage();
-         message.writeBytes(new byte[10 * 1024]);
-
      - - -
    10. Send only 20 messages to the Queue. This will be already enough for pagingQueue. Look at ./paging/config/activemq-queues.xml for the config.
      11. - 
      
-         for (int i = 0; i < 20; i++)
-         {
-            pageMessageProducer.send(message);
-         }
-
      - -
    11. Create a JMS Message Producer
      12. - 
      
-         MessageProducer messageProducer = session.createProducer(queue);
-
      - -
    12. We don't need persistent messages in order to use paging. (This step is optional)
      13. - 
      
-         messageProducer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
-
      - -
    13. Send the message for about 30K, which should be over the memory limit imposed by the server
      14. - 
      
-         for (int i = 0; i < 30000; i++)
-         {
-            messageProducer.send(message);
-         }
-
      - -
    14. if you pause the example here, you will several files under ./build/data/paging
      15. - - 
      
-         // Thread.sleep(30000); // if you want to just our of curiosity, you can sleep here and inspect the created files just for
-
      - - -
    15. Create a JMS Message Consumer
      16. - 
      
-         MessageConsumer messageConsumer = session.createConsumer(queue);
-
      - - -
    16. Start the JMS Connection. This step will activate the subscribers to receive messages.
      17. - 
      
-         connection.start();
-
      - - -
    17. Receive the messages. It's important to ACK for messages as ActiveMQ Artemis will not read messages from paging until messages are ACKed
      18. - - 
      
-         for (int i = 0; i < 30000; i++)
-         {
-            message = (BytesMessage)messageConsumer.receive(1000);
-
-            if (i % 1000 == 0)
-            {
-               System.out.println("Received " + i + " messages");
-
-               message.acknowledge();
-            }
-         }
-
      - -
    18. Receive the messages from the Queue names pageQueue. Create the proper consumer for that.
      19. - 
      
-         messageConsumer.close();
-         messageConsumer = session.createConsumer(pageQueue);
-
-         for (int i = 0; i < 20; i++)
-         {
-            message = (BytesMessage)messageConsumer.receive(1000);
-
-            System.out.println("Received message " + i + " from pageQueue");
-
-            message.acknowledge();
-         }
-
      - -
    19. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      20. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      - -
    - - diff --git a/examples/features/standard/paging/readme.md b/examples/features/standard/paging/readme.md new file mode 100644 index 0000000000..f0697e1ce5 --- /dev/null +++ b/examples/features/standard/paging/readme.md @@ -0,0 +1,11 @@ +# Paging Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how ActiveMQ Artemis would avoid running out of memory resources by paging messages. + +A maximum size can be specified per address via the address settings in the configuration file (broker.xml). + +When messages routed to an address exceed the specified max-size-bytes the broker will begin to write messages to the file system, this is called paging. This will continue to occur until messages have been delivered to consumers and subsequently acknowledged freeing up memory. Messages will then be read from the file system , i.e. depaged, and routed as normal. + +Acknowledgement plays an important factor on paging as messages will stay on the file system until the memory is released so it is important to make sure that the client acknowledges its messages. \ No newline at end of file diff --git a/examples/features/standard/paging/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/paging/src/main/resources/activemq/server0/broker.xml index 11fb8a0ee5..9144c901f2 100644 --- a/examples/features/standard/paging/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/paging/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -80,7 +78,7 @@ under the License. - +
    diff --git a/examples/features/standard/pom.xml b/examples/features/standard/pom.xml index 017a038eb7..6a1a598f9a 100644 --- a/examples/features/standard/pom.xml +++ b/examples/features/standard/pom.xml @@ -57,8 +57,8 @@ under the License. http-transport interceptor interceptor-client - interceptor-client-mqtt - interceptor-client-amqp + interceptor-mqtt + interceptor-amqp instantiate-connection-factory jms-auto-closeable jms-bridge @@ -123,8 +123,8 @@ under the License. http-transport interceptor interceptor-client - interceptor-client-mqtt - interceptor-client-amqp + interceptor-mqtt + interceptor-amqp jms-auto-closeable instantiate-connection-factory jms-bridge diff --git a/examples/features/standard/pre-acknowledge/pom.xml b/examples/features/standard/pre-acknowledge/pom.xml index 5c58c50bae..ff40762c36 100644 --- a/examples/features/standard/pre-acknowledge/pom.xml +++ b/examples/features/standard/pre-acknowledge/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/pre-acknowledge/readme.html b/examples/features/standard/pre-acknowledge/readme.html deleted file mode 100644 index 235c278c6d..0000000000 --- a/examples/features/standard/pre-acknowledge/readme.html +++ /dev/null @@ -1,154 +0,0 @@ - - - - - ActiveMQ Artemis JMS Pre-Acknowledge Example - - - - - -

    JMS Pre-Acknowledge Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    Standard JMS supports three acknowledgement modes: AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, and - DUPS_OK_ACKNOWLEDGE. For a full description on these modes please consult the JMS specification, or any - JMS tutorial.

    -

    All of these standard modes involve sending acknowledgements from the client to the server. However - in some cases, you really don't mind losing messages in event of failure, so it would make sense - to acknowledge the message on the server before delivering it to the client.

    -

    By acknowledging the message before sending to the client, you can avoid extra network traffic and CPU - work done in sending acknowledgements from client to server.

    -

    The down-side of acknowledging on the server before delivery, is that if the system crashes after acknowledging - the message, but before the message has been received by the client, then, on recovery, that message - will be lost. This makes pre-acknowledgement not appropriate for all use cases, but it is very useful for some - use-cases when you can cope with such loss of messages

    -

    An example of a use-case where it might be a good idea to use pre-acknowledge, is for stock price update - messages. With these messages it might be ok to lose a message in event of crash, since the next price - update message will arrive soon, overriding the previous price.

    -

    In order to use pre-acknowledge functionality with ActiveMQ Artemis the session has to be created with - a special, ActiveMQ Artemis specific acknowledgement mode, given by the value of - ActiveMQJMSConstants.PRE_ACKNOWLEDGE. -

    Example step-by-step

    - -
      -
    1. Create an initial context to perform the JNDI lookup.
      2. - 
      -           
-     initialContext = getContext(0);
-     
-
      - -
    2. Perform the look-ups
      3. - 
      -           
-     Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");
-
-     ConnectionFactory cf = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
-           
-
      - -
    3. Create a the JMS objects.
      4. - 
      -           
-     connection = cf.createConnection();
-
-     Session session = connection.createSession(false, ActiveMQSession.PRE_ACKNOWLEDGE);
-
-     MessageProducer producer = session.createProducer(queue);
-
-     MessageConsumer messageConsumer = session.createConsumer(queue);
-           
-
      - -
    4. Create and send a message.
      5. - 
      -           
-     TextMessage message1 = session.createTextMessage("This is a text message 1");
-
-     producer.send(message1);
-
-     System.out.println("Sent message: " + message1.getText());
-           
-
      - -
    5. Print out the message count of the queue. The queue contains one message as expected - delivery has not yet started on the queue.
      6. - 
      -           
-     int count = getMessageCount(connection);
-
-     System.out.println("Queue message count is " + count);
-           
-
      - -
    6. Start the Connection, delivery will now start. Give a little time for delivery to occur.
      7. - 
      -          
-     connection.start();
-
-     Thread.sleep(1000);
-          
-
      - -
    7. Print out the message count of the queue. It should now be zero, since the message has - already been acknowledged even before the consumer has received it.
      8. - 
      -           
-     count = getMessageCount(connection);
-
-     System.out.println("Queue message count is now " + count);
-           
-
      - -
    8. Finally, receive the message.
      9. - 
      -           
-     TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
-
-     System.out.println("Received message: " + messageReceived.getText());
-           
-
      - -
    9. Be sure to close our resources!
      10. - 
      -           
-     if (initialContext != null)
-     {
-        initialContext.close();
-     }
-     if (connection != null)
-     {
-        connection.close();
-     }
-           
-
      -
    - -

    More information

    - - - - - diff --git a/examples/features/standard/pre-acknowledge/readme.md b/examples/features/standard/pre-acknowledge/readme.md new file mode 100644 index 0000000000..014b91dc8c --- /dev/null +++ b/examples/features/standard/pre-acknowledge/readme.md @@ -0,0 +1,15 @@ +# JMS Pre-Acknowledge Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +Standard JMS supports three acknowledgement modes: AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, and DUPS_OK_ACKNOWLEDGE. For a full description on these modes please consult the JMS specification, or any JMS tutorial. + +All of these standard modes involve sending acknowledgements from the client to the server. However in some cases, you really don't mind losing messages in event of failure, so it would make sense to acknowledge the message on the broker **before** delivering it to the client. + +By acknowledging the message before sending to the client, you can avoid extra network traffic and CPU work done in sending acknowledgements from client to server. + +The down-side of acknowledging on the broker before delivery, is that if the system crashes after acknowledging the message, but before the message has been received by the client, then, on recovery, that message will be lost. This makes pre-acknowledgement not appropriate for all use cases, but it is very useful for some use-cases when you can cope with such loss of messages + +An example of a use-case where it might be a good idea to use pre-acknowledge, is for stock price update messages. With these messages it might be ok to lose a message in event of crash, since the next price update message will arrive soon, overriding the previous price. + +In order to use pre-acknowledge functionality with ActiveMQ Artemis the session has to be created with a special, ActiveMQ Artemis specific acknowledgement mode, given by the value of `ActiveMQJMSConstants.PRE_ACKNOWLEDGE`. \ No newline at end of file diff --git a/examples/features/standard/pre-acknowledge/src/main/java/org/apache/activemq/artemis/jms/example/PreacknowledgeExample.java b/examples/features/standard/pre-acknowledge/src/main/java/org/apache/activemq/artemis/jms/example/PreacknowledgeExample.java index d840c32eb2..fdeac96f83 100644 --- a/examples/features/standard/pre-acknowledge/src/main/java/org/apache/activemq/artemis/jms/example/PreacknowledgeExample.java +++ b/examples/features/standard/pre-acknowledge/src/main/java/org/apache/activemq/artemis/jms/example/PreacknowledgeExample.java @@ -38,7 +38,7 @@ import org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory; * This example demonstrates the use of ActiveMQ Artemis "pre-acknowledge" functionality where * messages are acknowledged before they are delivered to the consumer. * - * Please see the readme.html for more details. + * Please see the readme for more details. */ public class PreacknowledgeExample { diff --git a/examples/features/standard/pre-acknowledge/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/pre-acknowledge/src/main/resources/activemq/server0/broker.xml index ee9828f935..50227dd9ff 100644 --- a/examples/features/standard/pre-acknowledge/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/pre-acknowledge/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -52,7 +50,7 @@ under the License. - +
    diff --git a/examples/features/standard/producer-rate-limit/pom.xml b/examples/features/standard/producer-rate-limit/pom.xml index e313a37c3e..4d58a1a418 100644 --- a/examples/features/standard/producer-rate-limit/pom.xml +++ b/examples/features/standard/producer-rate-limit/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/producer-rate-limit/readme.html b/examples/features/standard/producer-rate-limit/readme.html deleted file mode 100644 index 5267db78c0..0000000000 --- a/examples/features/standard/producer-rate-limit/readme.html +++ /dev/null @@ -1,176 +0,0 @@ - - - - - ActiveMQ Artemis JMS Message Producer Rate Limiting - - - - - -

    JMS Message Producer Rate Limiting

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    With ActiveMQ Artemis you can specify a maximum send rate at which a JMS MessageProducer will send messages. - This can be specified when creating or deploying the connection factory. See activemq-jms.xml

    -

    If this value is specified then ActiveMQ Artemis will ensure that messages are never produced at a rate higher than - specified. This is a form of producer throttling.

    -

    Example step-by-step

    -

    In this example we specify a producer-max-rate of 50 messages per second in the activemq-jms.xml - file when deploying the connection factory:

    - 
    -     
-   <connection-factory name="ConnectionFactory">
-      <connector-ref>netty-connector</connector-ref>
-      <entries>
-         <entry name="ConnectionFactory"/>
-      </entries>
-
-      <!-- We limit producers created on this connection factory to produce messages at a maximum rate
-      of 50 messages per sec -->
-      <producer-max-rate>50</producer-max-rate>
-
-   </connection-factory>
-     
-
    -

    We then simply send as many messages as we can in 10 seconds and note how many messages are actually sent.

    -

    We note that the number of messages sent per second never exceeds the specified value of 50 messages per second.

    - -
      -
    1. Create an initial context to perform the JNDI lookup.
      2. - 
      -           initialContext = getContext(0);
-
      - -
    2. Perfom a lookup on the queue
      3. - 
      -           Queue queue = (Queue)initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. Perform a lookup on the Connection Factory
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory)initialContext.lookup("/ConnectionFactory");
-
      - -
    4. Create a JMS Connection
      5. - 
      -           connection = cf.createConnection();
-
      - -
    5. Create a JMS Session
      6. - 
      -           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. Create a JMS Message Producer
      7. - 
      -          MessageProducer producer = session.createProducer(queue);
-
      - -
    7. Send as many messages as we can in 10 seconds
      8. - 
      -           
-        final long duration = 10000;
-
-        int i = 0;
-
-        long start = System.currentTimeMillis();
-
-        while (System.currentTimeMillis() - start <= duration)
-        {
-           TextMessage message = session.createTextMessage("This is text message: " + i++);
-
-           producer.send(message);
-        }
-
-        long end = System.currentTimeMillis();
-
-        double rate = 1000 * (double)i / (end - start);
-
-        System.out.println("We sent " + i + " messages in " + (end - start) + " milliseconds");
-
-        System.out.println("Actual send rate was " + rate + " messages per second");
-           
-
      - -
    8. We note that the sending rate doesn't exceed 50 messages per second. Here's some example output from a real - run
      9. - - 
      -           
-     [java] Will now send as many messages as we can in 10 seconds...
-     [java] We sent 500 messages in 10072 milliseconds
-     [java] Actual send rate was 49.64257347100874 messages per second
-           
-
      - - -
    9. For good measure we consumer the messages we produced.
      10. - 
      -           
-        MessageConsumer messageConsumer = session.createConsumer(queue);
-
-        connection.start();
-
-        System.out.println("Now consuming the messages...");
-
-        i = 0;
-        while (true)
-        {
-           TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000);
-
-           if (messageReceived == null)
-           {
-              break;
-           }
-
-           i++;
-        }
-
-        System.out.println("Received " + i + " messages");
-
-           
-
      - -
    10. Be sure to close our resources!
      11. - - 
      -           
-           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      - - - -
    - - diff --git a/examples/features/standard/producer-rate-limit/readme.md b/examples/features/standard/producer-rate-limit/readme.md new file mode 100644 index 0000000000..b8db366238 --- /dev/null +++ b/examples/features/standard/producer-rate-limit/readme.md @@ -0,0 +1,15 @@ +# JMS Message Producer Rate Limiting + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +With ActiveMQ Artemis you can specify a maximum send rate at which a JMS MessageProducer will send messages. This can be specified when creating or deploying the connection factory. See `activemq-jms.xml` + +If this value is specified then ActiveMQ Artemis will ensure that messages are never produced at a rate higher than specified. This is a form of producer _throttling_. + +## Example step-by-step + +In this example we specify a `producerMaxRate` of `50` messages per second on the connection URL. + +We then simply send as many messages as we can in 10 seconds and note how many messages are actually sent. + +We note that the number of messages sent per second never exceeds the specified value of `50` messages per second. \ No newline at end of file diff --git a/examples/features/standard/queue-requestor/pom.xml b/examples/features/standard/queue-requestor/pom.xml index 9db8f9258b..ecad52d6e9 100644 --- a/examples/features/standard/queue-requestor/pom.xml +++ b/examples/features/standard/queue-requestor/pom.xml @@ -97,7 +97,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/queue-requestor/readme.html b/examples/features/standard/queue-requestor/readme.html deleted file mode 100644 index 68a1c95f23..0000000000 --- a/examples/features/standard/queue-requestor/readme.html +++ /dev/null @@ -1,46 +0,0 @@ - - - - - ActiveMQ Artemis JMS QueueRequestor Example - - - - - -

    JMS QueueRequestor Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to use a QueueRequestor with ActiveMQ Artemis.

    -

    JMS is mainly used to send messages asynchronously so that the producer of a message is not waiting for the result of the message consumption. - However, there are cases where it is necessary to have a synchronous behavior: the code sending a message requires a reply for this message - before continuing its execution.
    - A QueueRequestor facilitates this use case by providing a simple request/reply abstraction on top of JMS.

    -

    The example consists in two classes:

    -
    -
    TextReverserService
    -
    A JMS MessageListener which consumes text messages and sends replies containing the reversed text
    -
    QueueRequestorExample
    -
    A JMS Client which uses a QueueRequestor to send text requests to a queue and receive replies with the reversed text in a synchronous fashion
    -
    - - diff --git a/examples/features/standard/queue-requestor/readme.md b/examples/features/standard/queue-requestor/readme.md new file mode 100644 index 0000000000..efa993b4af --- /dev/null +++ b/examples/features/standard/queue-requestor/readme.md @@ -0,0 +1,14 @@ +# JMS QueueRequestor Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to use a [QueueRequestor](http://java.sun.com/javaee/5/docs/api/javax/jms/QueueRequestor.html) with ActiveMQ Artemis. + +JMS is mainly used to send messages asynchronously so that the producer of a message is not waiting for the result of the message consumption. However, there are cases where it is necessary to have a synchronous behavior: the code sending a message requires a reply for this message before continuing its execution. +A QueueRequestor facilitates this use case by providing a simple request/reply abstraction on top of JMS. + +The example consists in two classes: + +* `TextReverserService`: A JMS MessageListener which consumes text messages and sends replies containing the reversed text. + +* `QueueRequestorExample`: A JMS Client which uses a QueueRequestor to send text requests to a queue and receive replies with the reversed text in a synchronous fashion. \ No newline at end of file diff --git a/examples/features/standard/queue-requestor/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/queue-requestor/src/main/resources/activemq/server0/broker.xml index 73ef48c983..bf9d4c873a 100644 --- a/examples/features/standard/queue-requestor/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/queue-requestor/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -56,7 +54,7 @@ under the License. - +
    diff --git a/examples/features/standard/queue-selector/pom.xml b/examples/features/standard/queue-selector/pom.xml index bede7cb647..d4a7119c3d 100644 --- a/examples/features/standard/queue-selector/pom.xml +++ b/examples/features/standard/queue-selector/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/queue-selector/readme.html b/examples/features/standard/queue-selector/readme.html deleted file mode 100644 index ef63063d94..0000000000 --- a/examples/features/standard/queue-selector/readme.html +++ /dev/null @@ -1,52 +0,0 @@ - - - - - ActiveMQ Artemis JMS Queue Selector Example - - - - - -

    JMS Queue Selector Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to selectively consume messages using message selectors with queue consumers.

    - -

    Message selectors are strings with special syntax that can be used in creating consumers. Message consumers - created with a message selector will only receive messages that match its selector. On message delivery, the JBoss Message - Server evaluates the corresponding message headers of the messages against each selector, if any, and then delivers - the 'matched' messages to its consumer. Please consult the JMS 1.1 specification for full details.

    - -

    In this example, three message consumers are created on a queue. The first consumer is created with selector - 'color=red', it only receives messages that - have a 'color' string property of 'red' value; the second is created with selector 'color=green', it - only receives messages who have a 'color' string property of - 'green' value; and the third without a selector, which means it receives all messages. To illustrate, three messages - with different 'color' property values are created and sent.

    - -

    Selectors can be used with both queue consumers and topic consumers. The difference is that with queue consumers, - a message is only delivered to one consumer on the queue, while topic consumers the message will be delivered to every - matching consumers. In this example, if the third consumer (anyConsumer) were the first consumer created, it will - consume the first message delivered, therefore there is no chance for the next consumer to get the message, even if it - matches the selector.

    - - diff --git a/examples/features/standard/queue-selector/readme.md b/examples/features/standard/queue-selector/readme.md new file mode 100644 index 0000000000..60448a48a3 --- /dev/null +++ b/examples/features/standard/queue-selector/readme.md @@ -0,0 +1,11 @@ +# JMS Queue Selector Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to selectively consume messages using message selectors with queue consumers. + +Message selectors are strings with special syntax that can be used in creating consumers. Message consumers created with a message selector will only receive messages that match its selector. On message delivery, the JBoss Message Server evaluates the corresponding message headers of the messages against each selector, if any, and then delivers the 'matched' messages to its consumer. Please consult the JMS 1.1 specification for full details. + +In this example, three message consumers are created on a queue. The first consumer is created with selector `'color=red'`, it only receives messages that have a 'color' string property of 'red' value; the second is created with selector `'color=green'`, it only receives messages who have a 'color' string property of 'green' value; and the third without a selector, which means it receives all messages. To illustrate, three messages with different 'color' property values are created and sent. + +Selectors can be used with both queue consumers and topic consumers. The difference is that with queue consumers, a message is only delivered to one consumer on the queue, while topic consumers the message will be delivered to every matching consumers. In this example, if the third consumer (anyConsumer) were the first consumer created, it will consume the first message delivered, therefore there is no chance for the next consumer to get the message, even if it matches the selector. \ No newline at end of file diff --git a/examples/features/standard/queue/pom.xml b/examples/features/standard/queue/pom.xml index 7e964c843d..6395b16ce3 100644 --- a/examples/features/standard/queue/pom.xml +++ b/examples/features/standard/queue/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/queue/readme.html b/examples/features/standard/queue/readme.html deleted file mode 100644 index 0cdbd5f3f5..0000000000 --- a/examples/features/standard/queue/readme.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - ActiveMQ Artemis JMS Queue Example - - - - - -

    JMS Queue Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to send and receive a message to a JMS Queue using ActiveMQ Artemis.

    -

    Queues are a standard part of JMS, please consult the JMS 1.1 specification for full details.

    -

    A Queue is used to send messages point to point, from a producer to a consumer. The queue guarantees message ordering between these 2 points.

    -

    Notice this example is using pretty much a default stock configuration

    - - diff --git a/examples/features/standard/queue/readme.md b/examples/features/standard/queue/readme.md new file mode 100644 index 0000000000..bbe6012fa7 --- /dev/null +++ b/examples/features/standard/queue/readme.md @@ -0,0 +1,11 @@ +# JMS Queue Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to send and receive a message to a JMS Queue using ActiveMQ Artemis. + +Queues are a standard part of JMS, please consult the JMS 1.1 specification for full details. + +A Queue is used to send messages point to point, from a producer to a consumer. The queue guarantees message ordering between these 2 points. + +Notice this example is using pretty much a default stock configuration \ No newline at end of file diff --git a/examples/features/standard/reattach-node/pom.xml b/examples/features/standard/reattach-node/pom.xml index 4af95e2d3a..44dbb608f6 100644 --- a/examples/features/standard/reattach-node/pom.xml +++ b/examples/features/standard/reattach-node/pom.xml @@ -104,7 +104,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/reattach-node/readme.html b/examples/features/standard/reattach-node/readme.html deleted file mode 100644 index bc7d0901d0..0000000000 --- a/examples/features/standard/reattach-node/readme.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - ActiveMQ Artemis JMS Automatic Reattach Example - - - - - -

    JMS Reattach Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example demonstrates how ActiveMQ Artemis connections can be configured to be resilient to - temporary network failures.

    -

    In the case of a network failure being detected, either as a result of a failure to read/write to the connection, - or the failure of a pong to arrive back from the server in good time after a ping is sent, instead of - failing the connection immediately and notifying any user ExceptionListener objects, ActiveMQ - can be configured to automatically retry the connection, and reattach to the server when it becomes - available again across the network.

    -

    When the client reattaches to the server it will be able to resume using its sessions and connections - where it left off

    -

    This is different to client reconnect as the sessions, consumers etc still exist on the server. With reconnect - The client recreates its sessions and consumers as needed.

    -

    This example starts a single server, connects to it and performs some JMS operations. We then - simulate failure of the network connection by temporarily stopping the network acceptor on the server. - (This is done by sending management messages, but that is not central to the purpose of the example).

    -

    We then wait a few seconds, then restart the acceptor. The client reattaches and the session resumes - as if nothing happened.

    -

    The JMS Connection Factory is configured to reattach automatically by specifying the various reconnect - related attributes in the activemq-jms.xml file.

    - -

    For more details on how to configure this and for clustering in general - please consult the ActiveMQ Artemis user manual.

    - - diff --git a/examples/features/standard/reattach-node/readme.md b/examples/features/standard/reattach-node/readme.md new file mode 100644 index 0000000000..ef09c34af9 --- /dev/null +++ b/examples/features/standard/reattach-node/readme.md @@ -0,0 +1,19 @@ +# JMS Reattach Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates how ActiveMQ Artemis connections can be configured to be resilient to temporary network failures. + +In the case of a network failure being detected, either as a result of a failure to read/write to the connection, or the failure of a pong to arrive back from the broker in good time after a ping is sent, instead of failing the connection immediately and notifying any user ExceptionListener objects, ActiveMQ can be configured to automatically retry the connection, and reattach to the broker when it becomes available again across the network. + +When the client reattaches to the broker it will be able to resume using its sessions and connections where it left off + +This is different to client reconnect as the sessions, consumers etc still exist on the server. With reconnect The client recreates its sessions and consumers as needed. + +This example starts a single server, connects to it and performs some JMS operations. We then simulate failure of the network connection by temporarily stopping the network acceptor on the server. (This is done by sending management messages, but that is not central to the purpose of the example). + +We then wait a few seconds, then restart the acceptor. The client reattaches and the session resumes as if nothing happened. + +The JMS Connection Factory is configured to reattach automatically by specifying the various reconnect related attributes in the connection URL in `jndi.properties`. + +For more details on how to configure this and for clustering in general please consult the ActiveMQ Artemis user manual. \ No newline at end of file diff --git a/examples/features/standard/reattach-node/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/reattach-node/src/main/resources/activemq/server0/broker.xml index 72946ba89c..0fa75381b9 100644 --- a/examples/features/standard/reattach-node/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/reattach-node/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -70,7 +68,7 @@ under the License. - +
    diff --git a/examples/features/standard/request-reply/pom.xml b/examples/features/standard/request-reply/pom.xml index 9ac2496089..72b54ec655 100644 --- a/examples/features/standard/request-reply/pom.xml +++ b/examples/features/standard/request-reply/pom.xml @@ -106,6 +106,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/request-reply/readme.html b/examples/features/standard/request-reply/readme.html deleted file mode 100644 index 73d278d2a6..0000000000 --- a/examples/features/standard/request-reply/readme.html +++ /dev/null @@ -1,180 +0,0 @@ - - - - - ActiveMQ Artemis JMS Request-Reply Example - - - - - -

    JMS Request-Reply Example

    - -

    This example shows you how to handle a request message and receive a reply. To get a reply message, the requesting client creates a temporary queue. Then it sends out the request message with JMSReplyTo set to the temporary queue. The request message is handled by a SimpleRequestServer, who is listening to the request queue for incoming requests. If a request message has arrived, it extracts the reply queue from the request message by JMSReplyTo header, and sends back a reply message. To let the client know to which request message a reply message is related, the server also set the JMSCorrelationID with the request message's JMSMessageID header to the reply message.

    -

    Of course, in a real world example you would re-use the session, producer, consumer and temporary queue and not create a new one for each message! -Or better still use the correlation id, and just store the requests in a map, then you don't need a temporary queue at all - -

    Request/Reply style messaging is supported through standard JMS message headers JMSReplyTo and JMSCorrelationID. This is often used in request-reply style communications between applications. - Whenever a client sends a message that expects a response, it can use this mechanism to implement. please consult the JMS 1.1 specification for full details.

    - -

    Example step-by-step

    -

    To run the example, simply type mvn verify -Pexample from this directory

    - -
      - -
    1. We start the request server
      2. - 
      -           SimpleRequestServer server = new SimpleRequestServer();
-           server.start();
-
      - -
    2. We need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      3. - 
      -           initialContext = getContext();
-
      - -
    3. We lookup the queue for sending the request message
      4. - 
      -           Queue requestQueue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    4. We lookup for the Connection Factory
      5. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    5. We create a JMS Connection
      6. - 
      -           connection = cf.createConnection();
-
      - -
    6. We start the connection
      7. - 
      -           connection.start();
-
      - -
    7. We create a JMS Session
      8. - 
      -           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    8. We create a JMS Message Producer to send request message
      9. - 
      -           MessageProducer producer = session.createProducer(requestQueue);
-
      - -
    9. We create a temporary queue used to send reply message to and receive reply from
      10. - 
      -           TemporaryQueue replyQueue = session.createTemporaryQueue();
-
      - -
    10. We create a consumer to receive reply message
      11. - 
      -           MessageConsumer replyConsumer = session.createConsumer(replyQueue);
-
      - -
    11. We create a request Text Message
      12. - 
      -           TextMessage requestMsg = session.createTextMessage("A request message");
-
      - -
    12. We set the ReplyTo header so that the request receiver knows where to send the reply.
      13. - 
      -           requestMsg.setJMSReplyTo(replyQueue);
-
      - -
    13. We sent the request message
      14. - 
      -           producer.send(requestMsg);
-
      - -
    14. We put the request message to the map. Later we use it to check out which request message a reply message is for. Here we use the MessageID as the correlation id (JMSCorrelationID). You don't have to use it though. You can use some arbitrary string for example.
      15. - 
      -           requestMap.put(requestMsg.getJMSMessageID(), requestMsg);
-
      - -
    15. We receive the reply message
      16. - 
      -           TextMessage replyMessageReceived = (TextMessage)replyConsumer.receive();
-
      - -
    16. We check out which request message is this reply message sent for. Here we just have one request message for illustrative purpose. In real world there may be many requests and many replies.
      17. - 
      -           TextMessage matchedMessage = requestMap.get(replyMessageReceived.getJMSCorrelationID());
-
      - -
    17. We close the consumer and producer on the replyQueue
      18. - 
      -           replyConsumer.close();
-
      - -
    18. We delete the temporary queue
      19. - 
      -           replyQueue.delete();
-
      - -
    19. We shutdown the request server
      20. - 
      -           server.shutdown();
-
      - -
    20. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      21. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - - Request Messages are handled in SimpleRequestServer.onMessage(), - -
      -
    1. Extract the ReplyTo destination
      2. - 
      -           Destination replyDestination = request.getJMSReplyTo();
-
      - -
    2. Create the reply message
      3. - 
      -           TextMessage replyMessage = session.createTextMessage("A reply message");
-
      - -
    3. Set the CorrelationID
      4. - 
      -           replyMessage.setJMSCorrelationID(request.getJMSCorrelationID());
-
      - -
    4. Send out the reply message
      5. - 
      -           replyProducer.send(replyMessage);
-
      -
    - - - diff --git a/examples/features/standard/request-reply/readme.md b/examples/features/standard/request-reply/readme.md new file mode 100644 index 0000000000..68ee072430 --- /dev/null +++ b/examples/features/standard/request-reply/readme.md @@ -0,0 +1,9 @@ +# JMS Request-Reply Example + +To run the example, simply type **mvn verify -Pexample** from this directory. + +This example shows you how to handle a request message and receive a reply. To get a reply message, the requesting client creates a temporary queue. Then it sends out the request message with JMSReplyTo set to the temporary queue. The request message is handled by a SimpleRequestServer, who is listening to the request queue for incoming requests. If a request message has arrived, it extracts the reply queue from the request message by JMSReplyTo header, and sends back a reply message. To let the client know to which request message a reply message is related, the broker also set the JMSCorrelationID with the request message's JMSMessageID header to the reply message. + +Of course, in a real world example you would re-use the session, producer, consumer and temporary queue and not create a new one for each message! Or better still use the correlation id, and just store the requests in a map, then you don't need a temporary queue at all + +Request/Reply style messaging is supported through standard JMS message headers JMSReplyTo and JMSCorrelationID. This is often used in request-reply style communications between applications. Whenever a client sends a message that expects a response, it can use this mechanism to implement. Please consult the JMS 1.1 specification for full details. \ No newline at end of file diff --git a/examples/features/standard/rest/dup-send/pom.xml b/examples/features/standard/rest/dup-send/pom.xml index 618c58e723..18dc01d605 100644 --- a/examples/features/standard/rest/dup-send/pom.xml +++ b/examples/features/standard/rest/dup-send/pom.xml @@ -27,12 +27,70 @@ under the License. dup-send war - Duplicate Send Demo + Duplicate Send Example ${project.basedir}/../../../../.. + + + org.apache.activemq + artemis-core-client + ${project.version} + + + org.apache.activemq + artemis-server + ${project.version} + + + org.apache.activemq + artemis-jms-client + ${project.version} + + + org.apache.activemq + artemis-jms-server + ${project.version} + + + io.netty + netty-all + + + org.apache.geronimo.specs + geronimo-jms_2.0_spec + + + org.apache.activemq.rest + artemis-rest + ${project.version} + + + org.jboss.resteasy + resteasy-jaxrs + + + org.jboss.resteasy + resteasy-jaxb-provider + + + junit + junit + test + + + + + + + org.apache.maven.plugins + maven-clean-plugin + + + + example @@ -103,53 +161,16 @@ under the License. + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + - - - org.apache.activemq - artemis-core-client - ${project.version} - - - org.apache.activemq - artemis-server - ${project.version} - - - org.apache.activemq - artemis-jms-client - ${project.version} - - - org.apache.activemq - artemis-jms-server - ${project.version} - - - io.netty - netty-all - - - org.apache.geronimo.specs - geronimo-jms_2.0_spec - - - org.apache.activemq.rest - artemis-rest - ${project.version} - - - org.jboss.resteasy - resteasy-jaxrs - - - org.jboss.resteasy - resteasy-jaxb-provider - - - junit - junit - test - - diff --git a/examples/features/standard/rest/dup-send/README.txt b/examples/features/standard/rest/dup-send/readme.md similarity index 72% rename from examples/features/standard/rest/dup-send/README.txt rename to examples/features/standard/rest/dup-send/readme.md index 2ae6d0d0b4..81023a4b9c 100644 --- a/examples/features/standard/rest/dup-send/README.txt +++ b/examples/features/standard/rest/dup-send/readme.md @@ -1,7 +1,4 @@ -System Requirements: -You will need JDK 1.8 and Maven to run this example. This example has been tested with Maven 3.3.3. It may or may not work -with earlier or later versions of Maven. - +# Rest Duplicate Send Example This is an example of using duplicate detection for posted messages. The first file to look at is: @@ -13,17 +10,20 @@ about in the documentation. To run the example you will need 3 shell-script windows (or you'll need to run 2 processes in background) Step 1: -$ mvn jetty:run + + mvn jetty:run This will bring up ActiveMQ Artemis and the ActiveMQ Artemis REST Interface. Step 2: -$ mvn exec:java -Dexec.mainClass="ReceiveOrder" -This will bring up a REST client that is continuously pulling the server through a consume-next (see doco for details). + mvn exec:java -Dexec.mainClass="ReceiveOrder" + +This will bring up a REST client that is continuously pulling the broker through a consume-next (see doco for details). Step 3: -$ mvn exec:java -Dexec.mainClass="PostOrder" + + mvn exec:java -Dexec.mainClass="PostOrder" This class will post 3 orders. The first order will cause the 307 redirection as stated in the docs. A 2nd order will be posted twice through the same consume-next URL. You'll see from the ReceiveOrder process that only 2 messages @@ -34,8 +34,8 @@ Step 4: In Step 4, you will use the create-with-id URL published by the container. To run the example, you must pass in your own order id. For example: -$ mvn exec:java -Dexec.mainClass="PostOrderWithId" -Dexec.args="001" + mvn exec:java -Dexec.mainClass="PostOrderWithId" -Dexec.args="001" If you run this program with the same argument you'll see that only one of the messages passes through the queue -and is consumed by the ReceiveOrder process. Pass a different string to -Dexec.args to post a new message that +and is consumed by the ReceiveOrder process. Pass a different string to `-Dexec.args` to post a new message that isn't caught by the dup-detection facility. diff --git a/examples/features/standard/rest/dup-send/src/main/resources/broker.xml b/examples/features/standard/rest/dup-send/src/main/resources/broker.xml index 577f5b05fa..466a0519f9 100644 --- a/examples/features/standard/rest/dup-send/src/main/resources/broker.xml +++ b/examples/features/standard/rest/dup-send/src/main/resources/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + false false diff --git a/examples/features/standard/rest/javascript-chat/README.txt b/examples/features/standard/rest/javascript-chat/README.txt deleted file mode 100644 index 7e52e1b3aa..0000000000 --- a/examples/features/standard/rest/javascript-chat/README.txt +++ /dev/null @@ -1,16 +0,0 @@ -System Requirements: -You will need JDK 1.8 and Maven to run this example. This example has been tested with Maven 3.3.3. It may or may not work -with earlier or later versions of Maven. - - -This is an example of producing and consuming messages through a topic. The client is Javascript code within your browser. -The example is a very simple chat application between two browser windows. - -Step 1: -$ mvn jetty:run - -This will bring up ActiveMQ Artemis and the ActiveMQ Artemis REST Interface. - -Step 2: -Bring up two browsers and point them to http://localhost:8080. In the textbox type a message you want to send. Click -the "Click to send message" button and you'll see the message show up in both browser windows. \ No newline at end of file diff --git a/examples/features/standard/rest/javascript-chat/pom.xml b/examples/features/standard/rest/javascript-chat/pom.xml index 020bc89fe9..41d49558fa 100644 --- a/examples/features/standard/rest/javascript-chat/pom.xml +++ b/examples/features/standard/rest/javascript-chat/pom.xml @@ -33,6 +33,65 @@ under the License. ${project.basedir}/../../../../.. + + + org.apache.activemq + artemis-core-client + ${project.version} + + + org.apache.activemq + artemis-server + ${project.version} + + + org.apache.activemq + artemis-jms-client + ${project.version} + + + org.apache.activemq + artemis-jms-server + ${project.version} + + + io.netty + netty-all + + + org.apache.geronimo.specs + geronimo-jms_2.0_spec + + + org.apache.activemq.rest + artemis-rest + ${project.version} + + + org.jboss.resteasy + resteasy-jaxrs + + + org.jboss.resteasy + resteasy-jaxb-provider + + + junit + junit + 4.1 + test + + + + + + + org.apache.maven.plugins + maven-clean-plugin + + + + example @@ -116,54 +175,16 @@ under the License. + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + - - - org.apache.activemq - artemis-core-client - ${project.version} - - - org.apache.activemq - artemis-server - ${project.version} - - - org.apache.activemq - artemis-jms-client - ${project.version} - - - org.apache.activemq - artemis-jms-server - ${project.version} - - - io.netty - netty-all - - - org.apache.geronimo.specs - geronimo-jms_2.0_spec - - - org.apache.activemq.rest - artemis-rest - ${project.version} - - - org.jboss.resteasy - resteasy-jaxrs - - - org.jboss.resteasy - resteasy-jaxb-provider - - - junit - junit - 4.1 - test - - diff --git a/examples/features/standard/rest/javascript-chat/readme.md b/examples/features/standard/rest/javascript-chat/readme.md new file mode 100644 index 0000000000..decd8b03e6 --- /dev/null +++ b/examples/features/standard/rest/javascript-chat/readme.md @@ -0,0 +1,15 @@ +# Rest Chat Application Example + +This is an example of producing and consuming messages through a topic. The client is Javascript code within your browser. + +The example is a very simple chat application between two browser windows. + +Step 1: + + mvn jetty:run + +This will bring up ActiveMQ Artemis and the ActiveMQ Artemis REST Interface. + +Step 2: + +Bring up two browsers and point them to `http://localhost:8080`. In the textbox type a message you want to send. Click the "Click to send message" button and you'll see the message show up in both browser windows. \ No newline at end of file diff --git a/examples/features/standard/rest/javascript-chat/src/main/resources/broker.xml b/examples/features/standard/rest/javascript-chat/src/main/resources/broker.xml index 30a5ff323f..7f5c63d54f 100644 --- a/examples/features/standard/rest/javascript-chat/src/main/resources/broker.xml +++ b/examples/features/standard/rest/javascript-chat/src/main/resources/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + false false diff --git a/examples/features/standard/rest/jms-to-rest/pom.xml b/examples/features/standard/rest/jms-to-rest/pom.xml index be634299db..403d02188e 100644 --- a/examples/features/standard/rest/jms-to-rest/pom.xml +++ b/examples/features/standard/rest/jms-to-rest/pom.xml @@ -33,6 +33,64 @@ under the License. ${project.basedir}/../../../../.. + + + org.apache.activemq + artemis-core-client + ${project.version} + + + org.apache.activemq + artemis-server + ${project.version} + + + org.apache.activemq + artemis-jms-client + ${project.version} + + + org.apache.activemq + artemis-jms-server + ${project.version} + + + io.netty + netty-all + + + org.apache.geronimo.specs + geronimo-jms_2.0_spec + + + org.apache.activemq.rest + artemis-rest + ${project.version} + + + org.jboss.resteasy + resteasy-jaxrs + + + org.jboss.resteasy + resteasy-jaxb-provider + + + junit + junit + test + + + + + + + org.apache.maven.plugins + maven-clean-plugin + + + + example @@ -103,53 +161,16 @@ under the License. + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + - - - org.apache.activemq - artemis-core-client - ${project.version} - - - org.apache.activemq - artemis-server - ${project.version} - - - org.apache.activemq - artemis-jms-client - ${project.version} - - - org.apache.activemq - artemis-jms-server - ${project.version} - - - io.netty - netty-all - - - org.apache.geronimo.specs - geronimo-jms_2.0_spec - - - org.apache.activemq.rest - artemis-rest - ${project.version} - - - org.jboss.resteasy - resteasy-jaxrs - - - org.jboss.resteasy - resteasy-jaxb-provider - - - junit - junit - test - - diff --git a/examples/features/standard/rest/jms-to-rest/README.txt b/examples/features/standard/rest/jms-to-rest/readme.md similarity index 67% rename from examples/features/standard/rest/jms-to-rest/README.txt rename to examples/features/standard/rest/jms-to-rest/readme.md index 217bb3c662..16a5169ec0 100644 --- a/examples/features/standard/rest/jms-to-rest/README.txt +++ b/examples/features/standard/rest/jms-to-rest/readme.md @@ -1,7 +1,4 @@ -System Requirements: -You will need JDK 1.8 and Maven to run this example. This example has been tested with Maven 3.3.3. It may or may not work -with earlier or later versions of Maven. - +# Mixed JMS and REST Producers/Consumers Example This is an example of mixing JMS producers and consumers with REST producers and consumers. The REST clients have been written in both Java using RESTEasy's client library and within the Python language. You will need Python 2.6.1 or higher @@ -10,40 +7,43 @@ to be able to run the Python clients. To run the example you will need 5 shell-script windows (or you'll need to run 4 processes in background) Step 1: -$ mvn jetty:run + + mvn jetty:run This will bring up ActiveMQ Artemis and the ActiveMQ Artemis REST Interface. Step 2: -$ mvn exec:java -Dexec.mainClass="RestReceive" -This will bring up a Java REST client that is continuously pulling the server through a consume-next (see doco for details). + mvn exec:java -Dexec.mainClass="RestReceive" + +This will bring up a Java REST client that is continuously pulling the broker through a consume-next (see doco for details). Step 3: -$ mvn exec:java -Dexec.mainClass="JmsReceive" + + mvn exec:java -Dexec.mainClass="JmsReceive" This will bring up a Java JMS consumer that is using the MessageListener interface to consume messages. It will extract a Order instance from the JMS Message it receives. Step 4: -$ python receiveOrder.py + python receiveOrder.py This runs a very simple Python program to consume messages Step 5: Use one of these three commands to post messages to the system. One of the receive clients will consume the message. -$ mvn exec:java -Dexec.mainClass="JmsSend" + mvn exec:java -Dexec.mainClass="JmsSend" A JMS client will create an Order object and send it to the queue. You'll see one of the 4 clients receive the message. -Notice that the REST clients automatically cause the Order object to be transformed on the server and passed as XML +Notice that the REST clients automatically cause the Order object to be transformed on the broker and passed as XML to the REST client. -$ mvn exec:java -Dexec.mainClass="RestSend" + mvn exec:java -Dexec.mainClass="RestSend" -THis is a REST client that uses the Acknowledgement protocol to receive a message from the queue. +This is a REST client that uses the Acknowledgement protocol to receive a message from the queue. -$ python postOrder.py + python postOrder.py This is a Python client that posts one message to the queue RESTfully (of course ;) ) diff --git a/examples/features/standard/rest/jms-to-rest/src/main/resources/broker.xml b/examples/features/standard/rest/jms-to-rest/src/main/resources/broker.xml index 1628bdbcef..2624b8bfef 100644 --- a/examples/features/standard/rest/jms-to-rest/src/main/resources/broker.xml +++ b/examples/features/standard/rest/jms-to-rest/src/main/resources/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + false false diff --git a/examples/features/standard/rest/push/pom.xml b/examples/features/standard/rest/push/pom.xml index 8bc3aba9f8..8b20ce9e84 100644 --- a/examples/features/standard/rest/push/pom.xml +++ b/examples/features/standard/rest/push/pom.xml @@ -33,12 +33,63 @@ under the License. ${project.basedir}/../../../../.. - - - jboss - http://repository.jboss.org/nexus/content/groups/public/ - - + + + org.apache.activemq + artemis-core-client + ${project.version} + + + org.apache.activemq + artemis-server + ${project.version} + + + org.apache.activemq + artemis-jms-client + ${project.version} + + + org.apache.activemq + artemis-jms-server + ${project.version} + + + io.netty + netty-all + + + org.apache.geronimo.specs + geronimo-jms_2.0_spec + + + org.apache.activemq.rest + artemis-rest + ${project.version} + + + org.jboss.resteasy + resteasy-jaxrs + + + org.jboss.resteasy + resteasy-jaxb-provider + + + junit + junit + test + + + + + + + org.apache.maven.plugins + maven-clean-plugin + + + @@ -110,53 +161,16 @@ under the License. + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + - - - org.apache.activemq - artemis-core-client - ${project.version} - - - org.apache.activemq - artemis-server - ${project.version} - - - org.apache.activemq - artemis-jms-client - ${project.version} - - - org.apache.activemq - artemis-jms-server - ${project.version} - - - io.netty - netty-all - - - org.apache.geronimo.specs - geronimo-jms_2.0_spec - - - org.apache.activemq.rest - artemis-rest - ${project.version} - - - org.jboss.resteasy - resteasy-jaxrs - - - org.jboss.resteasy - resteasy-jaxb-provider - - - junit - junit - test - - diff --git a/examples/features/standard/rest/push/README.txt b/examples/features/standard/rest/push/readme.md similarity index 69% rename from examples/features/standard/rest/push/README.txt rename to examples/features/standard/rest/push/readme.md index c5c0f3a0b7..99362fe321 100644 --- a/examples/features/standard/rest/push/README.txt +++ b/examples/features/standard/rest/push/readme.md @@ -1,32 +1,32 @@ -System Requirements: -You will need JDK 1.8 and Maven to run this example. This example has been tested with Maven 3.3.3. It may or may not work -with earlier or later versions of Maven. - +# Rest Push Subscriptions Example This is an example of having the ActiveMQ Artemis REST interface forward a posted message to a registered URL. To run the example you will need 3 shell-script windows (or you'll need to run 2 processes in background) Step 1: -$ mvn jetty:run + + mvn jetty:run This will bring up ActiveMQ Artemis and the ActiveMQ Artemis REST Interface. Two queues will be created. An "order" queue and a "shipping" -queue. The server will forward posted messages to the "shipping" queue through a registered push subscription. +queue. The broker will forward posted messages to the "shipping" queue through a registered push subscription. Step 2: -$ mvn exec:java -Dexec.mainClass="ReceiveShipping" + + mvn exec:java -Dexec.mainClass="ReceiveShipping" This will bring up a JMS client registers a MessageListener consumer to receive Order objects. It will automatically convert a posted HTTP message into an Order object using JAX-RS content handlers. Step 3: -$ mvn exec:java -Dexec.mainClass="PushReg" + + mvn exec:java -Dexec.mainClass="PushReg" This creates a push registration that listens on the "order" queue and forwards messages posted to it to a URL. This URL is the REST resource of the "shipping" queue. Step 4: -$ mvn exec:java -Dexec.mainClass="PostOrder" + mvn exec:java -Dexec.mainClass="PostOrder" This posts an order to the "order" queue. You'll see it eventually consumed by the ReceiveShipping process. diff --git a/examples/features/standard/rest/push/src/main/resources/broker.xml b/examples/features/standard/rest/push/src/main/resources/broker.xml index d58574ebc7..aff50d7ea9 100644 --- a/examples/features/standard/rest/push/src/main/resources/broker.xml +++ b/examples/features/standard/rest/push/src/main/resources/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + false false @@ -28,7 +26,7 @@ under the License. vm://0 tcp://localhost:61616 - +
    diff --git a/examples/features/standard/scheduled-message/pom.xml b/examples/features/standard/scheduled-message/pom.xml index f953c867f8..96ddc1cc2f 100644 --- a/examples/features/standard/scheduled-message/pom.xml +++ b/examples/features/standard/scheduled-message/pom.xml @@ -107,7 +107,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/scheduled-message/readme.html b/examples/features/standard/scheduled-message/readme.html deleted file mode 100644 index 9144f94167..0000000000 --- a/examples/features/standard/scheduled-message/readme.html +++ /dev/null @@ -1,134 +0,0 @@ - - - - - ActiveMQ Artemis Scheduled Message Example - - - - - -

    JMS Scheduled Message Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to send a scheduled message to a JMS Queue using ActiveMQ Artemis.

    -

    A Scheduled Message is a message that will be delivered at a time specified by the sender. To do this, - simply set a HDR_SCHEDULED_DELIVERY_TIME header property. The value of the property should be the time of - delivery in milliseconds.

    - -

    In this example, a message is created with the scheduled delivery time set to 5 seconds after the current time.

    - - -

    Example step-by-step

    -

    To run the example, simply type mvn verify -Pexample from this directory

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look-up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -           connection = cf.createConnection();
-
      - -
    5. We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
      6. - 
      -           Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    6. We create a JMS message producer on the session. This will be used to send the messages.
      7. - 
      -          MessageProducer producer = session.createProducer(queue);
-
      - -
    7. We create a JMS text message that we are going to send.
      8. - 
      -           TextMessage message = session.createTextMessage("This is a scheduled message message which will be delivered in 5 sec.");
-
      - -
    8. We schedule the delivery time to be 5 sec later.
      9. - 
      -           
-            long time = System.currentTimeMillis();
-            time += 5000;
-            message.setLongProperty(MessageImpl.HDR_SCHEDULED_DELIVERY_TIME.toString(), time);
-           
-
      - -
    9. We send message to the queue
      10. - 
      -           messageProducer.send(message);
-
      - -
    10. We create a JMS Message Consumer to receive the message.
      11. - 
      -           MessageConsumer messageConsumer = session.createConsumer(queue);
-
      - -
    11. We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started
      12. - 
      -           connection.start();
-
      - -
    12. We use a blocking receive() to consume the message and see when the message arrives.
      13. - 
      -           TextMessage messageReceived = (TextMessage) messageConsumer.receive();
-
      - -
    13. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      14. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      - -
    - -

    More information

    - - - - - diff --git a/examples/features/standard/scheduled-message/readme.md b/examples/features/standard/scheduled-message/readme.md new file mode 100644 index 0000000000..2841aaedfe --- /dev/null +++ b/examples/features/standard/scheduled-message/readme.md @@ -0,0 +1,9 @@ +# JMS Scheduled Message Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to send a scheduled message to a JMS Queue using ActiveMQ Artemis. + +A Scheduled Message is a message that will be delivered at a time specified by the sender. To do this, simply set a `org.apache.activemq.artemis.api.core.Message.HDR_SCHEDULED_DELIVERY_TIME` header property. The value of the property should be the time of delivery in milliseconds. + +In this example, a message is created with the scheduled delivery time set to 5 seconds after the current time. \ No newline at end of file diff --git a/examples/features/standard/security-ldap/pom.xml b/examples/features/standard/security-ldap/pom.xml index 4970bce910..d2837968ba 100644 --- a/examples/features/standard/security-ldap/pom.xml +++ b/examples/features/standard/security-ldap/pom.xml @@ -144,7 +144,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/security-ldap/readme.html b/examples/features/standard/security-ldap/readme.html deleted file mode 100644 index 430b319104..0000000000 --- a/examples/features/standard/security-ldap/readme.html +++ /dev/null @@ -1,361 +0,0 @@ - - - - - ActiveMQ Artemis JMS Security Example - - - - - -

    JMS Security LDAP Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows how to configure and use security using ActiveMQ Artemis and the Apache DS LDAP server.

    - -

    With security properly configured, ActiveMQ Artemis can restrict client access to its resources, including - connection creation, message sending/receiving, etc. This is done by configuring users and roles as well as permissions in - the configuration files.

    - -

    ActiveMQ Artemis supports wild-card security configuration. This feature makes security configuration very - flexible and enables fine-grained control over permissions in an efficient way.

    - -

    For a full description of how to configure security with ActiveMQ Artemis, please consult the user - manual.

    - -

    This example demonstrates how to configure users/roles in the Apache DS LDAP server, how to configure topics with - proper permissions using wild-card expressions, and how they take effects in a simple program.

    - -

    Users and roles are configured in Apache DS. The SecurityExample class will start an embedded version of Apache - DS and load the contents of example.ldif which contains the users and passwords for this example.

    - - 
    -     
-         dn: dc=activemq,dc=org
-         dc: activemq
-         objectClass: top
-         objectClass: domain
-
-         dn: uid=bill,dc=activemq,dc=org
-         uid: bill
-         userPassword: activemq
-         objectClass: account
-         objectClass: simpleSecurityObject
-         objectClass: top
-
-         dn: uid=andrew,dc=activemq,dc=org
-         uid: andrew
-         userPassword: activemq1
-         objectClass: account
-         objectClass: simpleSecurityObject
-         objectClass: top
-
-         dn: uid=frank,dc=activemq,dc=org
-         uid: frank
-         userPassword: activemq2
-         objectClass: account
-         objectClass: simpleSecurityObject
-         objectClass: top
-
-         dn: uid=sam,dc=activemq,dc=org
-         uid: sam
-         userPassword: activemq3
-         objectClass: account
-         objectClass: simpleSecurityObject
-         objectClass: top
-
-         ###################
-         ## Define roles ##
-         ###################
-
-         dn: cn=user,dc=activemq,dc=org
-         cn: user
-         member: uid=bill,dc=activemq,dc=org
-         member: uid=andrew,dc=activemq,dc=org
-         member: uid=frank,dc=activemq,dc=org
-         member: uid=sam,dc=activemq,dc=org
-         objectClass: groupOfNames
-         objectClass: top
-
-         dn: cn=europe-user,dc=activemq,dc=org
-         cn: europe-user
-         member: uid=andrew,dc=activemq,dc=org
-         objectClass: groupOfNames
-         objectClass: top
-
-         dn: cn=news-user,dc=activemq,dc=org
-         cn: news-user
-         member: uid=frank,dc=activemq,dc=org
-         member: uid=sam,dc=activemq,dc=org
-         objectClass: groupOfNames
-         objectClass: top
-
-         dn: cn=us-user,dc=activemq,dc=org
-         cn: us-user
-         member: uid=frank,dc=activemq,dc=org
-         objectClass: groupOfNames
-         objectClass: top
-     
-
    - -

    - User name and password consists of a valid account that can be used to establish connections to a ActiveMQ Artemis server, while - roles are used in controlling the access privileges against ActiveMQ Artemis topics and queues. You can achieve this control by - configuring proper permissions in broker.xml, like the following -

    - 
    
-      <security-settings>
-         <!-- any user can have full control of generic topics -->
-		   <security-setting match="jms.topic.#">
-		      <permission type="createDurableQueue" roles="user"/>
-		      <permission type="deleteDurableQueue" roles="user"/>
-		      <permission type="createNonDurableQueue" roles="user"/>
-		      <permission type="deleteNonDurableQueue" roles="user"/>
-		      <permission type="send" roles="user"/>
-		      <permission type="consume" roles="user"/>
-		   </security-setting>
-
-		   <security-setting match="jms.topic.news.europe.#">
-		      <permission type="createDurableQueue" roles="user"/>
-		      <permission type="deleteDurableQueue" roles="user"/>
-		      <permission type="createNonDurableQueue" roles="user"/>
-		      <permission type="deleteNonDurableQueue" roles="user"/>
-		      <permission type="send" roles="europe-user"/>
-		      <permission type="consume" roles="news-user"/>
-		   </security-setting>
-
-		   <security-setting match="jms.topic.news.us.#">
-		      <permission type="createDurableQueue" roles="user"/>
-		      <permission type="deleteDurableQueue" roles="user"/>
-		      <permission type="createNonDurableQueue" roles="user"/>
-		      <permission type="deleteNonDurableQueue" roles="user"/>
-		      <permission type="send" roles="us-user"/>
-		      <permission type="consume" roles="news-user"/>
-		   </security-setting>
-     </security-settings>
-
    - -

    Permissions can be defined on any group of queues, by using a wildcard. You can easily specify - wildcards to apply certain permissions to a set of matching queues and topics. In the above configuration - we have created four sets of permissions, each set matches against a special group of targets, indicated by wild-card match attributes.

    - -

    You can provide a very broad permission control as a default and then add more strict control - over specific addresses. By the above we define the following access rules:

    - -
  • Only role 'us-user' can create/delete and pulish messages to topics whose names match wild-card pattern 'news.us.#'.
    • -
  • Only role 'europe-user' can create/delete and publish messages to topics whose names match wild-card pattern 'news.europe.#'.
    • -
  • Only role 'news-user' can subscribe messages to topics whose names match wild-card pattern 'news.us.#' and 'news.europe.#'.
    • -
  • For any other topics that don't match any of the above wild-card patterns, permissions are granted to users of role 'user'.
    • - -

    To illustrate the effect of permissions, three topics are deployed. Topic 'genericTopic' matches 'jms.topic.#' wild-card, topic 'news.europe.europeTopic' matches - jms.topic.news.europe.#' wild-cards, and topic 'news.us.usTopic' matches 'jms.topic.news.us.#'.

    - -

    Example step-by-step

    -

    To run the example, simply type mvn verify from this directory

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           
-           InitialContext initialContext = getContext(0);
-           
-
      - -
    2. We perform lookup on the topics
      3. - 
      -           
-           Topic genericTopic = (Topic) initialContext.lookup("/topic/genericTopic");
-           Topic europeTopic = (Topic) initialContext.lookup("/topic/europeTopic");
-           Topic usTopic = (Topic) initialContext.lookup("/topic/usTopic");
-           
-
      - -
    3. We perform a lookup on the Connection Factory
      4. - 
      -           
-           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-           
-
      - -
    4. We try to create a JMS Connection without user/password. It will fail.
      5. - 
      -           
-           try
-           {
-              cf.createConnection();
-              result = false;
-           }
-           catch (JMSSecurityException e)
-           {
-              System.out.println("Default user cannot get a connection. Details: " + e.getMessage());
-           }
-           
-
      - -
    5. Bill tries to make a connection using wrong password
      6. - 
      -           
-           billConnection = null;
-           try
-           {
-              billConnection = createConnection("bill", "activemq1", cf);
-              result = false;
-           }
-           catch (JMSException e)
-           {
-              System.out.println("User bill failed to connect. Details: " + e.getMessage());
-           }
-           
-
      - -
    6. Bill makes a good connection.
      7. - 
      -          
-           billConnection = createConnection("bill", "activemq", cf);
-           billConnection.start();
-          
-
      - -
    7. Andrew makes a good connection
      8. - 
      -           
-           andrewConnection = createConnection("andrew", "activemq1", cf);
-           andrewConnection.start();
-           
-
      - -
    8. Frank makes a good connection
      9. - 
      -           
-           frankConnection = createConnection("frank", "activemq2", cf);
-           frankConnection.start();
-           
-
      - -
    9. Sam makes a good connection
      10. - 
      -           
-           samConnection = createConnection("sam", "activemq3", cf);
-           samConnection.start();
-           
-
      - -
    10. We check every user can publish/subscribe genericTopics
      11. - 
      -           
-           checkUserSendAndReceive(genericTopic, billConnection, "bill");
-           checkUserSendAndReceive(genericTopic, andrewConnection, "andrew");
-           checkUserSendAndReceive(genericTopic, frankConnection, "frank");
-           checkUserSendAndReceive(genericTopic, samConnection, "sam");
-           
-
      - -
    11. We check permissions on news.europe.europeTopic for bill: can't send and can't receive
      12. - 
      -           
-           checkUserNoSendNoReceive(europeTopic, billConnection, "bill", andrewConnection, frankConnection);
-           
-
      - -
    12. We check permissions on news.europe.europeTopic for andrew: can send but can't receive
      13. - 
      -           
-           checkUserSendNoReceive(europeTopic, andrewConnection, "andrew", frankConnection);
-           
-
      - -
    13. We check permissions on news.europe.europeTopic for frank: can't send but can receive
      14. - 
      -           
-           checkUserReceiveNoSend(europeTopic, frankConnection, "frank", andrewConnection);
-           
-
      - -
    14. We check permissions on news.europe.europeTopic for sam: can't send but can receive
      15. - 
      -           
-           checkUserReceiveNoSend(europeTopic, samConnection, "sam", andrewConnection);
-           
-
      - -
    15. We check permissions on news.us.usTopic for bill: can't send and can't receive
      16. - 
      -           
-           checkUserNoSendNoReceive(usTopic, billConnection, "bill");
-           
-
      - -
    16. We check permissions on news.us.usTopic for andrew: can't send and can't receive
      17. - 
      -           
-           checkUserNoSendNoReceive(usTopic, andrewConnection, "andrew");
-           
-
      - -
    17. We check permissions on news.us.usTopic for frank: can both send and receive
      18. - 
      -           
-           checkUserSendAndReceive(usTopic, frankConnection, "frank");
-           
-
      - -
    18. We check permissions on news.us.usTopic for sam: can't send but can receive
      19. - 
      -           
-           checkUserReceiveNoSend(usTopic, samConnection, "sam", frankConnection);
-           
-
      - -
    19. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      20. - - 
      -           
-           finally
-           {
-              if (billConnection != null)
-              {
-                 billConnection.close();
-              }
-              if (andrewConnection != null)
-              {
-                 andrewConnection.close();
-              }
-              if (frankConnection != null)
-              {
-                 frankConnection.close();
-              }
-              if (samConnection != null)
-              {
-                 samConnection.close();
-              }
-
-              // Also the initialContext
-              if (initialContext != null)
-              {
-                 initialContext.close();
-              }
-           }
-           
-
      -
    - - diff --git a/examples/features/standard/security-ldap/readme.md b/examples/features/standard/security-ldap/readme.md new file mode 100644 index 0000000000..d966ec4852 --- /dev/null +++ b/examples/features/standard/security-ldap/readme.md @@ -0,0 +1,121 @@ +# JMS Security LDAP Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how to configure and use security using ActiveMQ Artemis and the Apache DS LDAP server. + +With security properly configured, ActiveMQ Artemis can restrict client access to its resources, including connection creation, message sending/receiving, etc. This is done by configuring users and roles as well as permissions in the configuration files. + +ActiveMQ Artemis supports wild-card security configuration. This feature makes security configuration very flexible and enables fine-grained control over permissions in an efficient way. + +For a full description of how to configure security with ActiveMQ Artemis, please consult the user manual. + +This example demonstrates how to configure users/roles in the Apache DS LDAP server, how to configure topics with proper permissions using wild-card expressions, and how they take effects in a simple program. + +Users and roles are configured in Apache DS. The SecurityExample class will start an embedded version of Apache DS and load the contents of example.ldif which contains the users and passwords for this example. + + dn: dc=activemq,dc=org + dc: activemq + objectClass: top + objectClass: domain + + dn: uid=bill,dc=activemq,dc=org + uid: bill + userPassword: activemq + objectClass: account + objectClass: simpleSecurityObject + objectClass: top + + dn: uid=andrew,dc=activemq,dc=org + uid: andrew + userPassword: activemq1 + objectClass: account + objectClass: simpleSecurityObject + objectClass: top + + dn: uid=frank,dc=activemq,dc=org + uid: frank + userPassword: activemq2 + objectClass: account + objectClass: simpleSecurityObject + objectClass: top + + dn: uid=sam,dc=activemq,dc=org + uid: sam + userPassword: activemq3 + objectClass: account + objectClass: simpleSecurityObject + objectClass: top + + ################### + ## Define roles ## + ################### + + dn: cn=user,dc=activemq,dc=org + cn: user + member: uid=bill,dc=activemq,dc=org + member: uid=andrew,dc=activemq,dc=org + member: uid=frank,dc=activemq,dc=org + member: uid=sam,dc=activemq,dc=org + objectClass: groupOfNames + objectClass: top + + dn: cn=europe-user,dc=activemq,dc=org + cn: europe-user + member: uid=andrew,dc=activemq,dc=org + objectClass: groupOfNames + objectClass: top + + dn: cn=news-user,dc=activemq,dc=org + cn: news-user + member: uid=frank,dc=activemq,dc=org + member: uid=sam,dc=activemq,dc=org + objectClass: groupOfNames + objectClass: top + + dn: cn=us-user,dc=activemq,dc=org + cn: us-user + member: uid=frank,dc=activemq,dc=org + objectClass: groupOfNames + objectClass: top` + +User name and password consists of a valid account that can be used to establish connections to a ActiveMQ Artemis server, while roles are used in controlling the access privileges against ActiveMQ Artemis topics and queues. You can achieve this control by configuring proper permissions in `broker.xml`, like the following + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Permissions can be defined on any group of queues, by using a wildcard. You can easily specify wildcards to apply certain permissions to a set of matching queues and topics. In the above configuration we have created four sets of permissions, each set matches against a special group of targets, indicated by wild-card match attributes. + +You can provide a very broad permission control as a default and then add more strict control over specific addresses. By the above we define the following access rules: + +* Only role `us-user` can create/delete and pulish messages to topics whose names match wild-card pattern `news.us.#`. +* Only role `europe-user` can create/delete and publish messages to topics whose names match wild-card pattern `news.europe.#`. +* Only role `news-user` can subscribe messages to topics whose names match wild-card pattern `news.us.#` and `news.europe.#`. +* For any other topics that don't match any of the above wild-card patterns, permissions are granted to users of role `user`. + +To illustrate the effect of permissions, three topics are deployed. Topic `genericTopic` matches `#` wild-card, topic `news.europe.europeTopic` matches `news.europe.#` wild-cards, and topic `news.us.usTopic` matches `news.us.#`. diff --git a/examples/features/standard/security-ldap/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/security-ldap/src/main/resources/activemq/server0/broker.xml index 6f230a92cf..c9587ecccb 100644 --- a/examples/features/standard/security-ldap/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/security-ldap/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -70,7 +68,7 @@ under the License. - +
    diff --git a/examples/features/standard/security/pom.xml b/examples/features/standard/security/pom.xml index cd8af452a0..56074afb16 100644 --- a/examples/features/standard/security/pom.xml +++ b/examples/features/standard/security/pom.xml @@ -105,7 +105,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/security/readme.html b/examples/features/standard/security/readme.html deleted file mode 100644 index 749ed794ee..0000000000 --- a/examples/features/standard/security/readme.html +++ /dev/null @@ -1,315 +0,0 @@ - - - - - ActiveMQ Artemis JMS Security Example - - - - - -

    JMS Security Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows how to configure and use security using ActiveMQ Artemis.

    - -

    With security properly configured, ActiveMQ Artemis can restrict client access to its resources, including - connection creation, message sending/receiving, etc. This is done by configuring users and roles as well as permissions in - the configuration files.

    - -

    ActiveMQ Artemis supports wild-card security configuration. This feature makes security configuration very - flexible and enables fine-grained control over permissions in an efficient way.

    - -

    For a full description of how to configure security with ActiveMQ Artemis, please consult the user - manual.

    - -

    This example demonstrates how to configure users/roles, how to configure topics with proper permissions using wild-card - expressions, and how they take effects in a simple program.

    - -

    First we need to configure users with roles. For this example, users and roles are configured in artemis-users.properties - and artemis-roles.properties. The artemis-users.properties file follows the syntax of - <user>=<password>. This example has four users configured as below

    - - 
    -     
-         bill=activemq
-         andrew=activemq1
-         frank=activemq2
-         sam=activemq3
-     
-
    - -

    The artemis-roles.properties file follows the syntax of <role>=<users> where <users> can be - a comma-separated list of users from artemis-users.properties (since more than one user can belong in a - particular role). This example has four roles configured as below

    - - 
    -     
-         user=bill,andrew,frank,sam
-         europe-user=andrew
-         news-user=frank,sam
-         us-user=frank
-     
-
    - -

    - User name and password consists of a valid account that can be used to establish connections to a ActiveMQ Artemis server, while - roles are used in controlling the access privileges against ActiveMQ Artemis topics and queues. You can achieve this control by - configuring proper permissions in broker.xml, like the following -

    - 
    
-      <security-settings>
-         <!-- any user can have full control of generic topics -->
-		   <security-setting match="jms.topic.#">
-		      <permission type="createDurableQueue" roles="user"/>
-		      <permission type="deleteDurableQueue" roles="user"/>
-		      <permission type="createNonDurableQueue" roles="user"/>
-		      <permission type="deleteNonDurableQueue" roles="user"/>
-		      <permission type="send" roles="user"/>
-		      <permission type="consume" roles="user"/>
-		   </security-setting>
-
-		   <security-setting match="jms.topic.news.europe.#">
-		      <permission type="createDurableQueue" roles="user"/>
-		      <permission type="deleteDurableQueue" roles="user"/>
-		      <permission type="createNonDurableQueue" roles="user"/>
-		      <permission type="deleteNonDurableQueue" roles="user"/>
-		      <permission type="send" roles="europe-user"/>
-		      <permission type="consume" roles="news-user"/>
-		   </security-setting>
-
-		   <security-setting match="jms.topic.news.us.#">
-		      <permission type="createDurableQueue" roles="user"/>
-		      <permission type="deleteDurableQueue" roles="user"/>
-		      <permission type="createNonDurableQueue" roles="user"/>
-		      <permission type="deleteNonDurableQueue" roles="user"/>
-		      <permission type="send" roles="us-user"/>
-		      <permission type="consume" roles="news-user"/>
-		   </security-setting>
-     </security-settings>
-
    - -

    Permissions can be defined on any group of queues, by using a wildcard. You can easily specify - wildcards to apply certain permissions to a set of matching queues and topics. In the above configuration - we have created four sets of permissions, each set matches against a special group of targets, indicated by wild-card match attributes.

    - -

    You can provide a very broad permission control as a default and then add more strict control - over specific addresses. By the above we define the following access rules:

    - -
  • Only role 'us-user' can create/delete and pulish messages to topics whose names match wild-card pattern 'news.us.#'.
    • -
  • Only role 'europe-user' can create/delete and publish messages to topics whose names match wild-card pattern 'news.europe.#'.
    • -
  • Only role 'news-user' can subscribe messages to topics whose names match wild-card pattern 'news.us.#' and 'news.europe.#'.
    • -
  • For any other topics that don't match any of the above wild-card patterns, permissions are granted to users of role 'user'.
    • - -

    To illustrate the effect of permissions, three topics are deployed. Topic 'genericTopic' matches 'jms.topic.#' wild-card, topic 'news.europe.europeTopic' matches - jms.topic.news.europe.#' wild-cards, and topic 'news.us.usTopic' matches 'jms.topic.news.us.#'.

    - -

    Example step-by-step

    -

    To run the example, simply type mvn verify from this directory

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           
-           InitialContext initialContext = getContext(0);
-           
-
      - -
    2. We perform lookup on the topics
      3. - 
      -           
-           Topic genericTopic = (Topic) initialContext.lookup("/topic/genericTopic");
-           Topic europeTopic = (Topic) initialContext.lookup("/topic/europeTopic");
-           Topic usTopic = (Topic) initialContext.lookup("/topic/usTopic");
-           
-
      - -
    3. We perform a lookup on the Connection Factory
      4. - 
      -           
-           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-           
-
      - -
    4. We try to create a JMS Connection without user/password. It will fail.
      5. - 
      -           
-           try
-           {
-              cf.createConnection();
-              result = false;
-           }
-           catch (JMSSecurityException e)
-           {
-              System.out.println("Default user cannot get a connection. Details: " + e.getMessage());
-           }
-           
-
      - -
    5. Bill tries to make a connection using wrong password
      6. - 
      -           
-           billConnection = null;
-           try
-           {
-              billConnection = createConnection("bill", "activemq1", cf);
-              result = false;
-           }
-           catch (JMSException e)
-           {
-              System.out.println("User bill failed to connect. Details: " + e.getMessage());
-           }
-           
-
      - -
    6. Bill makes a good connection.
      7. - 
      -          
-           billConnection = createConnection("bill", "activemq", cf);
-           billConnection.start();
-          
-
      - -
    7. Andrew makes a good connection
      8. - 
      -           
-           andrewConnection = createConnection("andrew", "activemq1", cf);
-           andrewConnection.start();
-           
-
      - -
    8. Frank makes a good connection
      9. - 
      -           
-           frankConnection = createConnection("frank", "activemq2", cf);
-           frankConnection.start();
-           
-
      - -
    9. Sam makes a good connection
      10. - 
      -           
-           samConnection = createConnection("sam", "activemq3", cf);
-           samConnection.start();
-           
-
      - -
    10. We check every user can publish/subscribe genericTopics
      11. - 
      -           
-           checkUserSendAndReceive(genericTopic, billConnection, "bill");
-           checkUserSendAndReceive(genericTopic, andrewConnection, "andrew");
-           checkUserSendAndReceive(genericTopic, frankConnection, "frank");
-           checkUserSendAndReceive(genericTopic, samConnection, "sam");
-           
-
      - -
    11. We check permissions on news.europe.europeTopic for bill: can't send and can't receive
      12. - 
      -           
-           checkUserNoSendNoReceive(europeTopic, billConnection, "bill", andrewConnection, frankConnection);
-           
-
      - -
    12. We check permissions on news.europe.europeTopic for andrew: can send but can't receive
      13. - 
      -           
-           checkUserSendNoReceive(europeTopic, andrewConnection, "andrew", frankConnection);
-           
-
      - -
    13. We check permissions on news.europe.europeTopic for frank: can't send but can receive
      14. - 
      -           
-           checkUserReceiveNoSend(europeTopic, frankConnection, "frank", andrewConnection);
-           
-
      - -
    14. We check permissions on news.europe.europeTopic for sam: can't send but can receive
      15. - 
      -           
-           checkUserReceiveNoSend(europeTopic, samConnection, "sam", andrewConnection);
-           
-
      - -
    15. We check permissions on news.us.usTopic for bill: can't send and can't receive
      16. - 
      -           
-           checkUserNoSendNoReceive(usTopic, billConnection, "bill");
-           
-
      - -
    16. We check permissions on news.us.usTopic for andrew: can't send and can't receive
      17. - 
      -           
-           checkUserNoSendNoReceive(usTopic, andrewConnection, "andrew");
-           
-
      - -
    17. We check permissions on news.us.usTopic for frank: can both send and receive
      18. - 
      -           
-           checkUserSendAndReceive(usTopic, frankConnection, "frank");
-           
-
      - -
    18. We check permissions on news.us.usTopic for sam: can't send but can receive
      19. - 
      -           
-           checkUserReceiveNoSend(usTopic, samConnection, "sam", frankConnection);
-           
-
      - -
    19. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      20. - - 
      -           
-           finally
-           {
-              if (billConnection != null)
-              {
-                 billConnection.close();
-              }
-              if (andrewConnection != null)
-              {
-                 andrewConnection.close();
-              }
-              if (frankConnection != null)
-              {
-                 frankConnection.close();
-              }
-              if (samConnection != null)
-              {
-                 samConnection.close();
-              }
-
-              // Also the initialContext
-              if (initialContext != null)
-              {
-                 initialContext.close();
-              }
-           }
-           
-
      -
    - - diff --git a/examples/features/standard/security/readme.md b/examples/features/standard/security/readme.md new file mode 100644 index 0000000000..f78df6a0ce --- /dev/null +++ b/examples/features/standard/security/readme.md @@ -0,0 +1,68 @@ +# JMS Security Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how to configure and use security using ActiveMQ Artemis. + +With security properly configured, ActiveMQ Artemis can restrict client access to its resources, including connection creation, message sending/receiving, etc. This is done by configuring users and roles as well as permissions in the configuration files. + +ActiveMQ Artemis supports wild-card security configuration. This feature makes security configuration very flexible and enables fine-grained control over permissions in an efficient way. + +For a full description of how to configure security with ActiveMQ Artemis, please consult the user manual. + +This example demonstrates how to configure users/roles, how to configure topics with proper permissions using wild-card expressions, and how they take effects in a simple program. + +First we need to configure users with roles. For this example, users and roles are configured in `artemis-users.properties` and `artemis-roles.properties`. The `artemis-users.properties` file follows the syntax of =. This example has four users configured as below + + bill=activemq + andrew=activemq1 + frank=activemq2 + sam=activemq3 + +The `artemis-roles.properties` file follows the syntax of = where can be a comma-separated list of users from `artemis-users.properties` (since more than one user can belong in a particular role). This example has four roles configured as below + + user=bill,andrew,frank,sam + europe-user=andrew + news-user=frank,sam + us-user=frank + +User name and password consists of a valid account that can be used to establish connections to a ActiveMQ Artemis server, while roles are used in controlling the access privileges against ActiveMQ Artemis topics and queues. You can achieve this control by configuring proper permissions in `broker.xml`, like the following + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Permissions can be defined on any group of queues, by using a wildcard. You can easily specify wildcards to apply certain permissions to a set of matching queues and topics. In the above configuration we have created four sets of permissions, each set matches against a special group of targets, indicated by wild-card match attributes. + +You can provide a very broad permission control as a default and then add more strict control over specific addresses. By the above we define the following access rules: + +* Only role `us-user` can create/delete and pulish messages to topics whose names match wild-card pattern `news.us.#`. +* Only role `europe-user` can create/delete and publish messages to topics whose names match wild-card pattern `news.europe.#`. +* Only role `news-user` can subscribe messages to topics whose names match wild-card pattern `news.us.#` and `news.europe.#`. +* For any other topics that don't match any of the above wild-card patterns, permissions are granted to users of role `user`. + +To illustrate the effect of permissions, three topics are deployed. Topic `genericTopic` matches `#` wild-card, topic `news.europe.europeTopic` matches `news.europe.#` wild-cards, and topic `news.us.usTopic` matches `news.us.#`. diff --git a/examples/features/standard/security/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/security/src/main/resources/activemq/server0/broker.xml index 8e2729390c..6c2c505368 100644 --- a/examples/features/standard/security/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/security/src/main/resources/activemq/server0/broker.xml @@ -17,8 +17,7 @@ KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> - - + ./data/messaging/bindings @@ -66,7 +65,7 @@ under the License. - +
    diff --git a/examples/features/standard/send-acknowledgements/pom.xml b/examples/features/standard/send-acknowledgements/pom.xml index 05a8ae5b78..12b52abd61 100644 --- a/examples/features/standard/send-acknowledgements/pom.xml +++ b/examples/features/standard/send-acknowledgements/pom.xml @@ -97,7 +97,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/send-acknowledgements/readme.html b/examples/features/standard/send-acknowledgements/readme.html deleted file mode 100644 index fcc37fcc8c..0000000000 --- a/examples/features/standard/send-acknowledgements/readme.html +++ /dev/null @@ -1,140 +0,0 @@ - - - - - ActiveMQ Artemis Asynchronous Send Acknowledgements Example - - - - - -

    Asynchronous Send Acknowledgements Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    Asynchronous Send Acknowledgements are an advanced feature of ActiveMQ Artemis which allow you to - receive acknowledgements that messages were successfully received at the server in a separate thread to the sending thread

    -

    In this example we create a normal JMS session, then set a SendAcknowledgementHandler on the JMS - session's underlying core session. We send many messages to the server without blocking and asynchronously - receive send acknowledgements via the SendAcknowledgementHandler. - -

    For more information on Asynchronous Send Acknowledgements please see the user manual

    -

    Example step-by-step

    -

    To run the example, simply type mvn verify -Pexample from this directory

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext();
-
      - -
    2. We look-up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We look-up the JMS connection factory object from JNDI
      4. - 
      -           ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
-
      - -
    4. We create a JMS connection
      5. - 
      -           connection = cf.createConnection();
-
      - -
    5. Define a SendAcknowledgementHandler which will receive asynchronous acknowledgements
      6. - 
      -           
-         class MySendAcknowledgementsHandler implements SendAcknowledgementHandler
-         {
-            int count = 0;
-
-            public void sendAcknowledged(final Message message)
-            {
-               System.out.println("Received send acknowledgement for message " + count++);
-            }
-         }
-           
-
      - -
    6. Create a JMS session
      7. - 
      -          Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    7. Set the handler on the underlying core session
      8. - 
      -           
-         ClientSession coreSession = ((ActiveMQSession)session).getCoreSession();
-
-         coreSession.setSendAcknowledgementHandler(new MySendAcknowledgementsHandler());
-
-           
-
      - -
    8. Create a JMS Message Producer
      9. - 
      -           
-         MessageProducer producer = session.createProducer(queue);
-
-         producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
-           
-
      - -
    9. Send 5000 messages, the handler will get called asynchronously some time later after the messages are sent.
      10. - 
      -           
-         final int numMessages = 5000;
-
-         for (int i = 0; i < numMessages; i++)
-         {
-            javax.jms.Message jmsMessage = session.createMessage();
-
-            producer.send(jmsMessage);
-
-            System.out.println("Sent message " + i);
-         }
-           
-
      - - -
    10. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      11. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      - - - -
    - - diff --git a/examples/features/standard/send-acknowledgements/readme.md b/examples/features/standard/send-acknowledgements/readme.md new file mode 100644 index 0000000000..e9dc70231b --- /dev/null +++ b/examples/features/standard/send-acknowledgements/readme.md @@ -0,0 +1,9 @@ +# Asynchronous Send Acknowledgements Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +Asynchronous Send Acknowledgements are an advanced feature of ActiveMQ Artemis which allow you to receive acknowledgements that messages were successfully received at the broker in a separate thread to the sending thread + +In this example we create a normal JMS session, then set a SendAcknowledgementHandler on the JMS session's underlying core session. We send many messages to the broker without blocking and asynchronously receive send acknowledgements via the SendAcknowledgementHandler. + +For more information on Asynchronous Send Acknowledgements please see the user manual \ No newline at end of file diff --git a/examples/features/standard/send-acknowledgements/src/main/java/org/apache/activemq/artemis/jms/example/SendAcknowledgementsExample.java b/examples/features/standard/send-acknowledgements/src/main/java/org/apache/activemq/artemis/jms/example/SendAcknowledgementsExample.java index a3097d2fa8..e816ddc7ff 100644 --- a/examples/features/standard/send-acknowledgements/src/main/java/org/apache/activemq/artemis/jms/example/SendAcknowledgementsExample.java +++ b/examples/features/standard/send-acknowledgements/src/main/java/org/apache/activemq/artemis/jms/example/SendAcknowledgementsExample.java @@ -33,7 +33,7 @@ import org.apache.activemq.artemis.jms.client.ActiveMQSession; * Asynchronous Send Acknowledgements are an advanced feature of ActiveMQ Artemis which allow you to * receive acknowledgements that messages were successfully received at the server in a separate stream * to the stream of messages being sent to the server. - * For more information please see the readme.html file + * For more information please see the readme file */ public class SendAcknowledgementsExample { diff --git a/examples/features/standard/spring-integration/pom.xml b/examples/features/standard/spring-integration/pom.xml index 6373b2b39e..ed1b9977e8 100644 --- a/examples/features/standard/spring-integration/pom.xml +++ b/examples/features/standard/spring-integration/pom.xml @@ -79,7 +79,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/spring-integration/readme.html b/examples/features/standard/spring-integration/readme.html deleted file mode 100644 index a3855d0a7b..0000000000 --- a/examples/features/standard/spring-integration/readme.html +++ /dev/null @@ -1,36 +0,0 @@ - - - - - ActiveMQ Artemis Spring Example - - - - - -

    ActiveMQ Artemis Spring Example

    - -

    This examples shows how to setup and run an embedded JMS server within a Spring ApplicationContext using ActiveMQ Artemis along with ActiveMQ Artemis configuration files.

    - -

    Example step-by-step

    -

    YOU MUST DOWNLOAD THE SPRING LIBRARIES TO RUN THIS EXAMPLE!!! You must also modify the build.xml file to include the spring jars. You'll see the placeholder that is already there.

    -

    To run the example, simply type mvn verify -Pexample from this directory

    - - diff --git a/examples/features/standard/spring-integration/readme.md b/examples/features/standard/spring-integration/readme.md new file mode 100644 index 0000000000..41c2c9e8fa --- /dev/null +++ b/examples/features/standard/spring-integration/readme.md @@ -0,0 +1,5 @@ +# ActiveMQ Artemis Spring Example + +To run the example, simply type **mvn verify -Pexample** from this directory + +This examples shows how to setup and run an embedded broker within a Spring ApplicationContext using ActiveMQ Artemis along with ActiveMQ Artemis configuration files. \ No newline at end of file diff --git a/examples/features/standard/spring-integration/src/main/resources/broker.xml b/examples/features/standard/spring-integration/src/main/resources/broker.xml index 8ad3a4149a..9d703b3ce9 100644 --- a/examples/features/standard/spring-integration/src/main/resources/broker.xml +++ b/examples/features/standard/spring-integration/src/main/resources/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + false @@ -42,7 +40,7 @@ under the License. - +
    diff --git a/examples/features/standard/ssl-enabled-dual-authentication/pom.xml b/examples/features/standard/ssl-enabled-dual-authentication/pom.xml index d1069156b8..998492489e 100644 --- a/examples/features/standard/ssl-enabled-dual-authentication/pom.xml +++ b/examples/features/standard/ssl-enabled-dual-authentication/pom.xml @@ -104,7 +104,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/ssl-enabled-dual-authentication/readme.html b/examples/features/standard/ssl-enabled-dual-authentication/readme.html deleted file mode 100644 index 93d7c72afd..0000000000 --- a/examples/features/standard/ssl-enabled-dual-authentication/readme.html +++ /dev/null @@ -1,75 +0,0 @@ - - - - - ActiveMQ Artemis JMS SSL Example - - - - - -

    JMS SSL Dual Authentication Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to configure 2-way SSL along with 2 different authentications mechanisms so that SSL and non-SSL clients can send and consume messages to/from ActiveMQ Artemis. - The non-SSL authentication mechanism simply uses username and password. The SSL authentication mechanism uses the client's certificate.

    - -

    To configure 2-way SSL you need to configure the acceptor as follows:

    - -

    - 

    -           
-      <!-- Acceptor -->
-
-      <acceptor name="netty-ssl-acceptor">tcp://localhost:5500?sslEnabled=true;needClientAuth=true;keyStorePath=${data.dir}/../etc/server-side-keystore.jks;keyStorePassword=secureexample;trustStorePath=${data.dir}/../etc/server-side-truststore.jks;trustStorePassword=secureexample</acceptor>
-           
-
    -

    - -

    In the server-side URL, the server-side-keystore.jks is the key store file holding the server's certificate. The server-side-truststore.jks is the file holding the certificates which the server trusts. Notice also the "sslEnabled" and "needClientAuth" parameters which enable SSL and require clients to present their own certificate respectively. Here's the URL the client uses to connect over SSL:

    - -

    - 

    -           
-      tcp://localhost:5500?sslEnabled=true&trustStorePath=activemq/server0/client-side-truststore.jks&trustStorePassword=secureexample&keyStorePath=activemq/server0/client-side-keystore.jks&keyStorePassword=secureexample
-           
-
    -

    - -

    In the client-side URL, the client-side-keystore.jks is the key store file holding the client's certificate. The client-side-truststore.jks is the file holding the certificates which the client trusts. The "sslEnabled" parameter is present here as well just as it is on the server.

    - -

    The various keystore files are generated using the following commands:

    - -

    - 

    -           
-keytool -genkey -keystore server-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Server, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA
-keytool -export -keystore server-side-keystore.jks -file server-side-cert.cer -storepass secureexample
-keytool -import -keystore client-side-truststore.jks -file server-side-cert.cer -storepass secureexample -keypass secureexample -noprompt
-keytool -genkey -keystore client-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Client, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA
-keytool -export -keystore client-side-keystore.jks -file client-side-cert.cer -storepass secureexample
-keytool -import -keystore server-side-truststore.jks -file client-side-cert.cer -storepass secureexample -keypass secureexample -noprompt
-           
-
    -

    - - - diff --git a/examples/features/standard/ssl-enabled-dual-authentication/readme.md b/examples/features/standard/ssl-enabled-dual-authentication/readme.md new file mode 100644 index 0000000000..1fbe0dabfc --- /dev/null +++ b/examples/features/standard/ssl-enabled-dual-authentication/readme.md @@ -0,0 +1,26 @@ +# JMS SSL Dual Authentication Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure 2-way SSL along with 2 different authentications mechanisms so that SSL and non-SSL clients can send and consume messages to/from ActiveMQ Artemis. The non-SSL authentication mechanism simply uses username and password. The SSL authentication mechanism uses the client's certificate. + +To configure 2-way SSL you need to configure the acceptor as follows: + + tcp://localhost:5500?sslEnabled=true;needClientAuth=true;keyStorePath=server-side-keystore.jks;keyStorePassword=secureexample;trustStorePath=server-side-truststore.jks;trustStorePassword=secureexample + +In the server-side URL, the `server-side-keystore.jks` is the key store file holding the server's certificate. The `server-side-truststore.jks` is the file holding the certificates which the broker trusts. Notice also the `sslEnabled` and `needClientAuth` parameters which enable SSL and require clients to present their own certificate respectively. + +Here's the URL the client uses to connect over SSL: + + tcp://localhost:5500?sslEnabled=true&trustStorePath=activemq/server0/client-side-truststore.jks&trustStorePassword=secureexample&keyStorePath=activemq/server0/client-side-keystore.jks&keyStorePassword=secureexample + +In the client-side URL, the `client-side-keystore.jks` is the key store file holding the client's certificate. The `client-side-truststore.jks` is the file holding the certificates which the client trusts. The `sslEnabled` parameter is present here as well just as it is on the server. + +The various keystore files are generated using the following commands: + +* `keytool -genkey -keystore server-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Server, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA` +* `keytool -export -keystore server-side-keystore.jks -file server-side-cert.cer -storepass secureexample` +* `keytool -import -keystore client-side-truststore.jks -file server-side-cert.cer -storepass secureexample -keypass secureexample -noprompt` +* `keytool -genkey -keystore client-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Client, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA` +* `keytool -export -keystore client-side-keystore.jks -file client-side-cert.cer -storepass secureexample` +* `keytool -import -keystore server-side-truststore.jks -file client-side-cert.cer -storepass secureexample -keypass secureexample -noprompt` diff --git a/examples/features/standard/ssl-enabled-dual-authentication/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/ssl-enabled-dual-authentication/src/main/resources/activemq/server0/broker.xml index 420fa74304..1bba774894 100644 --- a/examples/features/standard/ssl-enabled-dual-authentication/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/ssl-enabled-dual-authentication/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -33,7 +31,7 @@ under the License. tcp://localhost:61616 - tcp://localhost:5500?sslEnabled=true;needClientAuth=true;keyStorePath=${data.dir}/../etc/server-side-keystore.jks;keyStorePassword=secureexample;trustStorePath=${data.dir}/../etc/server-side-truststore.jks;trustStorePassword=secureexample + tcp://localhost:5500?sslEnabled=true;needClientAuth=true;keyStorePath=server-side-keystore.jks;keyStorePassword=secureexample;trustStorePath=server-side-truststore.jks;trustStorePassword=secureexample @@ -46,7 +44,7 @@ under the License. - +
    diff --git a/examples/features/standard/ssl-enabled/pom.xml b/examples/features/standard/ssl-enabled/pom.xml index 7bcc83a299..bcfe9dd760 100644 --- a/examples/features/standard/ssl-enabled/pom.xml +++ b/examples/features/standard/ssl-enabled/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/ssl-enabled/readme.html b/examples/features/standard/ssl-enabled/readme.html deleted file mode 100644 index bb5e72420e..0000000000 --- a/examples/features/standard/ssl-enabled/readme.html +++ /dev/null @@ -1,56 +0,0 @@ - - - - - ActiveMQ Artemis JMS SSL Example - - - - - -

    JMS SSL Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to configure SSL with ActiveMQ Artemis to send and receive message.

    - -

    Using SSL can make your messaging applications interact with ActiveMQ Artemis securely. An application can - be secured transparently without extra coding effort. To secure your messaging application with SSL, you need to configure connector and acceptor as follows:

    - -

    - 

    -           
-      <!-- Connector -->
-
-      <connector name="netty-ssl-connector">tcp://localhost:5500?sslEnabled=true;keyStorePath=activemq/server0/activemq.example.keystore;keyStorePassword=activemqexample</connector>
-
-      <!-- Acceptor -->
-
-      <acceptor name="netty-ssl-acceptor">tcp://localhost:5500?sslEnabled=true;keyStorePath=activemq/server0/activemq.example.keystore;keyStorePassword=activemqexample</acceptor>
-
-           
-
    -

    - -

    In the configuration, the activemq.example.keystore is the key store file holding the server's certificate. The activemq.example.truststore - is the file holding the certificates which the client trusts (i.e. the server's certificate exported from activemq.example.keystore). They are pre-generated for illustration purpose1.

    - - diff --git a/examples/features/standard/ssl-enabled/readme.md b/examples/features/standard/ssl-enabled/readme.md new file mode 100644 index 0000000000..6038f6da90 --- /dev/null +++ b/examples/features/standard/ssl-enabled/readme.md @@ -0,0 +1,15 @@ +# JMS SSL Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure SSL with ActiveMQ Artemis to send and receive message. + +Using SSL can make your messaging applications interact with ActiveMQ Artemis securely. An application can be secured transparently without extra coding effort. To secure your messaging application with SSL, you need to configure connector and acceptor as follows: + + tcp://localhost:5500?sslEnabled=true;keyStorePath=activemq.example.keystore;keyStorePassword=activemqexample + +In the configuration, the `activemq.example.keystore` is the key store file holding the server's certificate. The `activemq.example.truststore` is the file holding the certificates which the client trusts (i.e. the server's certificate exported from activemq.example.keystore). They are generated via the following commands: + +* `keytool -genkey -keystore activemq.example.keystore -storepass activemqexample -keypass activemqexample -dname "CN=ActiveMQ Artemis Server, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA` +* `keytool -export -keystore activemq.example.keystore -file server-side-cert.cer -storepass activemqexample` +* `keytool -import -keystore activemq.example.truststore -file server-side-cert.cer -storepass activemqexample -keypass activemqexample -noprompt` \ No newline at end of file diff --git a/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.keystore b/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.keystore index 50de6819ee..4ed24133c4 100644 Binary files a/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.keystore and b/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.keystore differ diff --git a/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.truststore b/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.truststore index 129391a948..45ab086071 100644 Binary files a/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.truststore and b/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/activemq.example.truststore differ diff --git a/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/broker.xml index 11f6c3d244..04bcec5976 100644 --- a/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/ssl-enabled/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -32,7 +30,8 @@ under the License. - tcp://localhost:5500?sslEnabled=true;keyStorePath=${data.dir}/../etc/activemq.example.keystore;keyStorePassword=activemqexample + + tcp://localhost:5500?sslEnabled=true;keyStorePath=activemq.example.keystore;keyStorePassword=activemqexample @@ -49,7 +48,7 @@ under the License. - +
    diff --git a/examples/features/standard/static-selector/pom.xml b/examples/features/standard/static-selector/pom.xml index 513ecad48e..9e73c75a0c 100644 --- a/examples/features/standard/static-selector/pom.xml +++ b/examples/features/standard/static-selector/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/static-selector/readme.html b/examples/features/standard/static-selector/readme.html deleted file mode 100644 index 0dca49f78a..0000000000 --- a/examples/features/standard/static-selector/readme.html +++ /dev/null @@ -1,60 +0,0 @@ - - - - - ActiveMQ Artemis Static Message Selector Example - - - - - -

    Static Message Selector Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to configure a ActiveMQ Artemis queue with static message selectors (filters) - (to configure a static selector directly on a JMS queue, please see the - static-selector-jms example).

    - -

    Static message selectors are ActiveMQ's extension to message selectors as defined in JMS spec 1.1. - Rather than specifying the selector in the application code, static message selectors are defined in one of - ActiveMQ's configuration files, broker.xml, as an element called 'filter' inside each queue - definition, like

    - - 
    
-      <queues>
-      	<queue name="jms.queue.selectorQueue">
-      	    <address>jms.queue.selectorQueue</address>
-      	    <filter string="color='red'"/>
-      	</queue>
-      </queues>
-
    - -

    Once configured the queue 'selectorQueue' only delivers messages that are selected against the filter, i.e., - only the messages whose 'color' properties are of 'red' values can be received by its consumers. Those that don't match - the filter will be dropped by the queue and therefore will never be delivered to any of its consumers.

    - -

    In the example code, five messages with different 'color' property values are sent to queue 'selectorQueue'. One consumer - is created to receive messages from the queue. Of the five sent messages, two are of 'red' color properties, one is 'blue', - one is 'green' and one has not the 'color' property at all. The result is that the consumer only gets the two 'red' messages.

    - - - diff --git a/examples/features/standard/static-selector/readme.md b/examples/features/standard/static-selector/readme.md new file mode 100644 index 0000000000..089084030c --- /dev/null +++ b/examples/features/standard/static-selector/readme.md @@ -0,0 +1,11 @@ +# Static Message Selector Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure a ActiveMQ Artemis queue with static message selectors (filters). + +Static message selectors are ActiveMQ's extension to message selectors as defined in JMS spec 1.1. Rather than specifying the selector in the application code, static message selectors are defined in one of ActiveMQ's configuration files, broker.xml, as an element called `filter` inside each queue definition, like + +Once configured the queue `selectorQueue` only delivers messages that are selected against the filter, i.e., only the messages whose `color` properties are of `red` values can be received by its consumers. Those that don't match the filter will be dropped by the queue and therefore will never be delivered to any of its consumers. + +In the example code, five messages with different `color` property values are sent to queue `selectorQueue`. One consumer is created to receive messages from the queue. Of the five sent messages, two are of `red` color properties, one is `blue`, one is `green` and one has not the `color` property at all. The result is that the consumer only gets the two `red` messages. \ No newline at end of file diff --git a/examples/features/standard/static-selector/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/static-selector/src/main/resources/activemq/server0/broker.xml index fa9987927e..b6bda092ae 100644 --- a/examples/features/standard/static-selector/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/static-selector/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings ./data/messaging/journal @@ -49,7 +47,7 @@ under the License. - +
    diff --git a/examples/features/standard/temp-queue/pom.xml b/examples/features/standard/temp-queue/pom.xml index eb89b02455..729f6d7330 100644 --- a/examples/features/standard/temp-queue/pom.xml +++ b/examples/features/standard/temp-queue/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + diff --git a/examples/features/standard/temp-queue/readme.html b/examples/features/standard/temp-queue/readme.html deleted file mode 100644 index 4b4d5c8c25..0000000000 --- a/examples/features/standard/temp-queue/readme.html +++ /dev/null @@ -1,40 +0,0 @@ - - - - - ActiveMQ Artemis JMS Temporary Queue Example - - - - - -

    JMS Temporary Queue Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to use a TemporaryQueue with ActiveMQ Artemis. First a temporary queue is created to send and receive a message and then deleted. - Then another temporary queue is created and used after its connection is closed to illustrate its scope.

    -

    A TemporaryQueue is a JMS queue that exists only within the lifetime of its connection. It is often used in request-reply - type messaging where the reply is sent through a temporary destination. The temporary queue is often created as - a server resource, so after using, the user should call delete() method to release the resources. - Please consult the JMS 1.1 specification for full details.

    - - diff --git a/examples/features/standard/temp-queue/readme.md b/examples/features/standard/temp-queue/readme.md new file mode 100644 index 0000000000..8f06354d78 --- /dev/null +++ b/examples/features/standard/temp-queue/readme.md @@ -0,0 +1,7 @@ +# JMS Temporary Queue Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to use a TemporaryQueue with ActiveMQ Artemis. First a temporary queue is created to send and receive a message and then deleted. Then another temporary queue is created and used after its connection is closed to illustrate its scope. + +A TemporaryQueue is a JMS queue that exists only within the lifetime of its connection. It is often used in request-reply type messaging where the reply is sent through a temporary destination. The temporary queue is often created as a broker resource, so after using, the user should call delete() method to release the resources. Please consult the JMS 1.1 specification for full details. \ No newline at end of file diff --git a/examples/features/standard/temp-queue/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/temp-queue/src/main/resources/activemq/server0/broker.xml index bd62a0ed48..a9877281c9 100644 --- a/examples/features/standard/temp-queue/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/temp-queue/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -54,7 +52,7 @@ under the License. - +
    diff --git a/examples/features/standard/topic-hierarchies/pom.xml b/examples/features/standard/topic-hierarchies/pom.xml index e02a86cb92..61ffb4b786 100644 --- a/examples/features/standard/topic-hierarchies/pom.xml +++ b/examples/features/standard/topic-hierarchies/pom.xml @@ -106,7 +106,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/topic-hierarchies/readme.html b/examples/features/standard/topic-hierarchies/readme.html deleted file mode 100644 index 0aa16ca502..0000000000 --- a/examples/features/standard/topic-hierarchies/readme.html +++ /dev/null @@ -1,42 +0,0 @@ - - - - - ActiveMQ Artemis Topic Hierarchy Example - - - - - -

    Topic Hierarchy Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    ActiveMQ Artemis supports topic hierarchies. With a topic hierarchy you can register a subscriber with a wild-card - and that subscriber will receive any messages routed to an address that match the wildcard.

    -

    ActiveMQ Artemis wild-cards can use the character '#' which means "match any number of words", and - the character '*' which means "match a single word". Words are delimited by the character "."

    -

    For example if I subscribe using the wild-card "news.europe.#", then that would match messages sent to the addresses - "news.europe", "news.europe.sport" and "news.europe.entertainment", but it does not match messages sent to the - address "news.usa.wrestling"

    -

    For more information on the wild-card syntax please consult the user manual.

    - - diff --git a/examples/features/standard/topic-hierarchies/readme.md b/examples/features/standard/topic-hierarchies/readme.md new file mode 100644 index 0000000000..2f70bc719b --- /dev/null +++ b/examples/features/standard/topic-hierarchies/readme.md @@ -0,0 +1,11 @@ +# Topic Hierarchy Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +ActiveMQ Artemis supports topic hierarchies. With a topic hierarchy you can register a subscriber with a wild-card and that subscriber will receive any messages routed to an address that match the wildcard. + +ActiveMQ Artemis wild-cards can use the character `#` which means "match any number of words", and the character `*` which means "match a single word". Words are delimited by the character `.`. + +For example if I subscribe using the wild-card `news.europe.#`, then that would match messages sent to the addresses `news.europe`, `news.europe.sport` and `news.europe.entertainment`, but it does not match messages sent to the address `news.usa.wrestling`. + +For more information on the wild-card syntax please consult the user manual. \ No newline at end of file diff --git a/examples/features/standard/topic-hierarchies/src/main/java/org/apache/activemq/artemis/jms/example/TopicHierarchyExample.java b/examples/features/standard/topic-hierarchies/src/main/java/org/apache/activemq/artemis/jms/example/TopicHierarchyExample.java index 41bda55746..e5fadf3032 100644 --- a/examples/features/standard/topic-hierarchies/src/main/java/org/apache/activemq/artemis/jms/example/TopicHierarchyExample.java +++ b/examples/features/standard/topic-hierarchies/src/main/java/org/apache/activemq/artemis/jms/example/TopicHierarchyExample.java @@ -31,7 +31,7 @@ import org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory; /** * This example demonstrates how a JMS TopicSubscriber can be created to subscribe to a wild-card Topic. * - * For more information please see the readme.html + * For more information please see the readme */ public class TopicHierarchyExample { diff --git a/examples/features/standard/topic-selector-example1/pom.xml b/examples/features/standard/topic-selector-example1/pom.xml index 232b152fc1..4384afa281 100644 --- a/examples/features/standard/topic-selector-example1/pom.xml +++ b/examples/features/standard/topic-selector-example1/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/topic-selector-example1/readme.html b/examples/features/standard/topic-selector-example1/readme.html deleted file mode 100644 index f03f4f561d..0000000000 --- a/examples/features/standard/topic-selector-example1/readme.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - ActiveMQ Artemis JMS Topic Selector Example 1 - - - - - -

    JMS Topic Selector Example 1

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows how messages can be consumed from a topic using Message Selectors.

    -

    Consumers (or Subscribers) will only consume messages routed to a topic that match the provided selector

    -

    Topics and selectors are a standard part of JMS, please consult the JMS 1.1 specification for full details.

    - - - diff --git a/examples/features/standard/topic-selector-example1/readme.md b/examples/features/standard/topic-selector-example1/readme.md new file mode 100644 index 0000000000..b0a5559ca6 --- /dev/null +++ b/examples/features/standard/topic-selector-example1/readme.md @@ -0,0 +1,9 @@ +# JMS Topic Selector Example 1 + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how messages can be consumed from a topic using Message Selectors. + +Consumers (or Subscribers) will only consume messages routed to a topic that match the provided selector + +Topics and selectors are a standard part of JMS, please consult the JMS 1.1 specification for full details. \ No newline at end of file diff --git a/examples/features/standard/topic-selector-example1/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/topic-selector-example1/src/main/resources/activemq/server0/broker.xml index 85c6a0be63..42c38cb2eb 100644 --- a/examples/features/standard/topic-selector-example1/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/topic-selector-example1/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -49,7 +47,7 @@ under the License. - +
    diff --git a/examples/features/standard/topic-selector-example2/pom.xml b/examples/features/standard/topic-selector-example2/pom.xml index f70d59fc66..7a9fccd093 100644 --- a/examples/features/standard/topic-selector-example2/pom.xml +++ b/examples/features/standard/topic-selector-example2/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/topic-selector-example2/readme.html b/examples/features/standard/topic-selector-example2/readme.html deleted file mode 100644 index 608e3d8687..0000000000 --- a/examples/features/standard/topic-selector-example2/readme.html +++ /dev/null @@ -1,47 +0,0 @@ - - - - - ActiveMQ Artemis JMS Topic Selector Example 2 - - - - - -

    JMS Topic Selector Example 2

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to selectively consume messages using message selectors with topic consumers.

    - -

    Message selectors are strings with special syntax that can be used in creating consumers. Message consumers - that are thus created only receive messages that match its selector. On message delivering, the ActiveMQ - Server evaluates the corresponding message headers of the messages against each selector, if any, and then delivers - the 'matched' messages to its consumer. Please consult the JMS 1.1 specification for full details.

    - -

    In this example, three message consumers are created on a topic. The first consumer is created with selector - 'color=red', it only receives messages that - have a 'color' string property of 'red' value; the second is created with selector 'color=green', it - only receives messages who have a 'color' string property of - 'green' value; and the third without a selector, which means it receives all messages. To illustrate, three messages - with different 'color' property values are created and sent.

    - - diff --git a/examples/features/standard/topic-selector-example2/readme.md b/examples/features/standard/topic-selector-example2/readme.md new file mode 100644 index 0000000000..01b7e6a7e1 --- /dev/null +++ b/examples/features/standard/topic-selector-example2/readme.md @@ -0,0 +1,9 @@ +# JMS Topic Selector Example 2 + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to selectively consume messages using message selectors with topic consumers. + +Message selectors are strings with special syntax that can be used in creating consumers. Message consumers that are thus created only receive messages that match its selector. On message delivering, the ActiveMQ Server evaluates the corresponding message headers of the messages against each selector, if any, and then delivers the 'matched' messages to its consumer. Please consult the JMS 1.1 specification for full details. + +In this example, three message consumers are created on a topic. The first consumer is created with selector `'color=red'`, it only receives messages that have a 'color' string property of 'red' value; the second is created with selector `'color=green'`, it only receives messages who have a 'color' string property of 'green' value; and the third without a selector, which means it receives all messages. To illustrate, three messages with different 'color' property values are created and sent. \ No newline at end of file diff --git a/examples/features/standard/topic-selector-example2/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/topic-selector-example2/src/main/resources/activemq/server0/broker.xml index 85c6a0be63..42c38cb2eb 100644 --- a/examples/features/standard/topic-selector-example2/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/topic-selector-example2/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -49,7 +47,7 @@ under the License. - +
    diff --git a/examples/features/standard/topic/pom.xml b/examples/features/standard/topic/pom.xml index 103a8ea40e..d39b7370ae 100644 --- a/examples/features/standard/topic/pom.xml +++ b/examples/features/standard/topic/pom.xml @@ -102,6 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/topic/readme.html b/examples/features/standard/topic/readme.html deleted file mode 100644 index 8bfa903f45..0000000000 --- a/examples/features/standard/topic/readme.html +++ /dev/null @@ -1,36 +0,0 @@ - - - - - ActiveMQ Artemis JMS Topic Example - - - - - -

    JMS Topic Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to send and receive a message to a JMS Topic with ActiveMQ Artemis.

    -

    Topics are a standard part of JMS, please consult the JMS 1.1 specification for full details.

    -

    A Topic is used to send messages using the publish-subscribe model, from a producer to 1 or more consumers.

    - - diff --git a/examples/features/standard/topic/readme.md b/examples/features/standard/topic/readme.md new file mode 100644 index 0000000000..ecdb65f536 --- /dev/null +++ b/examples/features/standard/topic/readme.md @@ -0,0 +1,9 @@ +# JMS Topic Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to send and receive a message to a JMS Topic with ActiveMQ Artemis. + +Topics are a standard part of JMS, please consult the JMS 1.1 specification for full details. + +A Topic is used to send messages using the publish-subscribe model, from a producer to 1 or more consumers. \ No newline at end of file diff --git a/examples/features/standard/topic/src/main/resources/activemq/server0/broker.xml b/examples/features/standard/topic/src/main/resources/activemq/server0/broker.xml index 10d3280973..cc1be04b47 100644 --- a/examples/features/standard/topic/src/main/resources/activemq/server0/broker.xml +++ b/examples/features/standard/topic/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -50,7 +48,7 @@ under the License. - +
    diff --git a/examples/features/standard/transactional/pom.xml b/examples/features/standard/transactional/pom.xml index 22d7415ff5..867c395ee1 100644 --- a/examples/features/standard/transactional/pom.xml +++ b/examples/features/standard/transactional/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/transactional/readme.html b/examples/features/standard/transactional/readme.html deleted file mode 100644 index b171c0a970..0000000000 --- a/examples/features/standard/transactional/readme.html +++ /dev/null @@ -1,40 +0,0 @@ - - - - - ActiveMQ Artemis JMS Transactional Session Example - - - - - -

    JMS Transactional Session Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to use a transacted Session with ActiveMQ Artemis.

    -

    Firstly 2 messages are sent via the transacted sending session before being committed. This ensures that both message - are sent

    -

    Secondly the receiving session receives the messages firstly demonstrating a message being redelivered after the session - being rolled back and then acknowledging receipt of the messages via the commit method.

    - - - diff --git a/examples/features/standard/transactional/readme.md b/examples/features/standard/transactional/readme.md new file mode 100644 index 0000000000..a256f3ff44 --- /dev/null +++ b/examples/features/standard/transactional/readme.md @@ -0,0 +1,9 @@ +# JMS Transactional Session Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to use a transacted Session with ActiveMQ Artemis. + +Firstly 2 messages are sent via the transacted sending session before being committed. This ensures that both message are sent + +Secondly the receiving session receives the messages firstly demonstrating a message being redelivered after the session being rolled back and then acknowledging receipt of the messages via the commit method. \ No newline at end of file diff --git a/examples/features/standard/xa-heuristic/pom.xml b/examples/features/standard/xa-heuristic/pom.xml index 661a693a70..a28a0f5065 100644 --- a/examples/features/standard/xa-heuristic/pom.xml +++ b/examples/features/standard/xa-heuristic/pom.xml @@ -104,7 +104,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/xa-heuristic/readme.html b/examples/features/standard/xa-heuristic/readme.html deleted file mode 100644 index bf44937d37..0000000000 --- a/examples/features/standard/xa-heuristic/readme.html +++ /dev/null @@ -1,48 +0,0 @@ - - - - - ActiveMQ Artemis JMS XA Heuristic Example - - - - - -

    JMS XA Heuristic Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to make an XA heuristic decision through the ActiveMQ Artemis Management Interface.

    - -

    A heuristic decision is a unilateral decision to commit or rollback an XA transaction branch after it has - been prepared.

    - -

    In this example we simulate a transaction manager to control the transactions. First we create an XASession - and enlist it in a transaction through its XAResource. We then send a text message, 'hello' and end/prepare the transaction - on the XAResource, but neither commit nor roll back the transaction. Another transaction is created and - associated with the same XAResource, and a second message, 'world' is sent on behalf of the second transaction. Again we leave - the second transaction in prepare state. - Then we get the MBeanServerConnection object to manipulate the prepared transactions. To illustrate, we roll back the first - transaction but commit the second. This will result in that only the message 'world' is received.

    - -

    This example uses JMX to manipulate transactions in a ActiveMQ Artemis Server. For details on JMX facilities with ActiveMQ Artemis, - please look at the JMX Example.

    - - diff --git a/examples/features/standard/xa-heuristic/readme.md b/examples/features/standard/xa-heuristic/readme.md new file mode 100644 index 0000000000..1b91133d1b --- /dev/null +++ b/examples/features/standard/xa-heuristic/readme.md @@ -0,0 +1,11 @@ +# JMS XA Heuristic Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to make an XA heuristic decision through the ActiveMQ Artemis Management Interface. + +A heuristic decision is a unilateral decision to commit or rollback an XA transaction branch after it has been prepared. + +In this example we simulate a transaction manager to control the transactions. First we create an XASession and enlist it in a transaction through its XAResource. We then send a text message, 'hello' and end/prepare the transaction on the XAResource, but neither commit nor roll back the transaction. Another transaction is created and associated with the same XAResource, and a second message, 'world' is sent on behalf of the second transaction. Again we leave the second transaction in prepare state. Then we get the MBeanServerConnection object to manipulate the prepared transactions. To illustrate, we roll back the first transaction but commit the second. This will result in that only the message 'world' is received. + +This example uses JMX to manipulate transactions in a ActiveMQ Artemis Server. For details on JMX facilities with ActiveMQ Artemis, please look at the JMX Example. \ No newline at end of file diff --git a/examples/features/standard/xa-receive/pom.xml b/examples/features/standard/xa-receive/pom.xml index fedd2f7252..457ff2a4aa 100644 --- a/examples/features/standard/xa-receive/pom.xml +++ b/examples/features/standard/xa-receive/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/xa-receive/readme.html b/examples/features/standard/xa-receive/readme.html deleted file mode 100644 index ab6d7d7922..0000000000 --- a/examples/features/standard/xa-receive/readme.html +++ /dev/null @@ -1,48 +0,0 @@ - - - - - ActiveMQ Artemis JMS XA Receive Example - - - - - -

    JMS XA Receive Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example demonstrates receiving a message within the scope of an XA transaction. When using an XA transaction - the message will only be acknowledged and removed from the queue when the transaction is committed. - If the transaction is not committed the message maybe redelivered after rollback or during XA recovery.

    - -

    ActiveMQ Artemis is JTA aware, meaning you can use ActiveMQ Artemis in an XA transactional environment - and participate in XA transactions. It provides the javax.transaction.xa.XAResource interface for that - purpose. Users can get a XAConnectionFactory to create XAConnections and XASessions.

    - -

    In this example we simulate a transaction manager to control the transactions. First we create an XASession - for receiving and a normal session for sending. Then we start a new xa transaction and enlist the receiving - XASession through its XAResource. We then send two words, 'hello' and 'world', receive them, and let the - transaction roll back. The received messages are cancelled back to the queue. Next we start - a new transaction with the same XAResource enlisted, but this time we commit the transaction after receiving the - messages. Then we check that no more messages are to be received.

    - - diff --git a/examples/features/standard/xa-receive/readme.md b/examples/features/standard/xa-receive/readme.md new file mode 100644 index 0000000000..5c41053857 --- /dev/null +++ b/examples/features/standard/xa-receive/readme.md @@ -0,0 +1,9 @@ +# JMS XA Receive Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates receiving a message within the scope of an XA transaction. When using an XA transaction the message will only be acknowledged and removed from the queue when the transaction is committed. If the transaction is not committed the message maybe redelivered after rollback or during XA recovery. + +ActiveMQ Artemis is JTA aware, meaning you can use ActiveMQ Artemis in an XA transactional environment and participate in XA transactions. It provides the javax.transaction.xa.XAResource interface for that purpose. Users can get a XAConnectionFactory to create XAConnections and XASessions. + +In this example we simulate a transaction manager to control the transactions. First we create an XASession for receiving and a normal session for sending. Then we start a new xa transaction and enlist the receiving XASession through its XAResource. We then send two words, 'hello' and 'world', receive them, and let the transaction roll back. The received messages are cancelled back to the queue. Next we start a new transaction with the same XAResource enlisted, but this time we commit the transaction after receiving the messages. Then we check that no more messages are to be received. \ No newline at end of file diff --git a/examples/features/standard/xa-send/pom.xml b/examples/features/standard/xa-send/pom.xml index fac358c72e..a5a245fc08 100644 --- a/examples/features/standard/xa-send/pom.xml +++ b/examples/features/standard/xa-send/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/standard/xa-send/readme.html b/examples/features/standard/xa-send/readme.html deleted file mode 100644 index fb3db4c305..0000000000 --- a/examples/features/standard/xa-send/readme.html +++ /dev/null @@ -1,215 +0,0 @@ - - - - - ActiveMQ Artemis JMS XA Send Example - - - - - -

    JMS XA Send Example

    -

    This example shows you how message sending behaves in an XA transaction in ActiveMQ Artemis. When a message is sent within - the scope of an XA transaction, it will only reach the queue once the transaction is committed. - If the transaction is rolled back the sent messages will be discarded by the server.

    - -

    ActiveMQ Artemis is JTA aware, meaning you can use ActiveMQ Artemis in a XA transactional environment - and participate in XA transactions. It provides the javax.transaction.xa.XAResource interface for that - purpose. Users can get a XAConnectionFactory to create XAConnections and XASessions.

    - -

    In this example we simulate a transaction manager to control the transactions. First we create an XASession - and enlist it in a transaction through its XAResource. We then send two words, 'hello' and 'world', with - the session, let the transaction roll back. The messages are discarded and never be received. Next we start - a new transaction with the same XAResource, but this time we commit the transaction. Both messages are received.

    - -

    Example step-by-step

    -

    To run the example, simply type mvn verify -Pexample from this directory

    - -
      -
    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
      2. - 
      -           InitialContext initialContext = getContext(0);
-
      - -
    2. We look-up the JMS queue object from JNDI
      3. - 
      -           Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
-
      - -
    3. We perform a lookup on the XA Connection Factory
      4. - 
      -           XAConnectionFactory cf = (XAConnectionFactory) initialContext.lookup("/XAConnectionFactory");
-
      - -
    4. We create a JMS XAConnection
      5. - 
      -           connection = cf.createXAConnection();
-
      - -
    5. We Start the connection
      6. - 
      -           connection.start();
-
      - -
    6. We create a JMS XASession
      7. - 
      -          XASession xaSession = connection.createXASession();
-
      - -
    7. We create a normal session
      8. - 
      -          Session normalSession = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-
      - -
    8. We create a normal Message Consumer
      9. - 
      -           
-           MessageConsumer normalConsumer = normalSession.createConsumer(queue);
-           normalConsumer.setMessageListener(new SimpleMessageListener());
-           
-
      - -
    9. We get the JMS Session
      10. - 
      -          Session session = xaSession.getSession();
-
      - -
    10. We create a message producer
      11. - 
      -          MessageProducer producer = session.createProducer(queue);
-
      - -
    11. We create two Text Messages
      12. - 
      -          
-          TextMessage helloMessage = session.createTextMessage("hello");
-          TextMessage worldMessage = session.createTextMessage("world");
-          
-
      - -
    12. We create a transaction
      13. - 
      -          Xid xid1 = new XidImpl("xa-example1".getBytes(), 1, UUIDGenerator.getInstance().generateStringUUID().getBytes());
-
      - -
    13. We get the JMS XAResource
      14. - 
      -          XAResource xaRes = xaSession.getXAResource();
-
      - -
    14. We begin the Transaction work
      15. - 
      -          xaRes.start(xid1, XAResource.TMNOFLAGS);
-
      - -
    15. We do work, sending two messages.
      16. - 
      -          
-          producer.send(helloMessage);
-          producer.send(worldMessage);
-          
-
      - -
    16. We check the result, it should receive none!
      17. - 
      -          checkNoMessageReceived();
-
      - -
    17. We stop the work
      18. - 
      -          xaRes.end(xid1, XAResource.TMSUCCESS);
-
      - -
    18. We prepare
      19. - 
      -          xaRes.prepare(xid1);
-
      - -
    19. We roll back the transaction
      20. - 
      -          xaRes.rollback(xid1);
-
      - -
    20. We check no messages should be received!
      21. - 
      -          checkNoMessageReceived();
-
      - -
    21. We create another transaction
      22. - 
      -          Xid xid2 = new XidImpl("xa-example2".getBytes(), 1, UUIDGenerator.getInstance().generateStringUUID().getBytes());
-
      - -
    22. We start the transaction
      23. - 
      -          xaRes.start(xid2, XAResource.TMNOFLAGS);
-
      - -
    23. We re-send those messages
      24. - 
      -           
-           producer.send(helloMessage);
-           producer.send(worldMessage);
-           
-
      - -
    24. We stop the work
      25. - 
      -          xaRes.end(xid2, XAResource.TMSUCCESS);
-
      - -
    25. We prepare
      26. - 
      -          xaRes.prepare(xid2);
-
      - -
    26. We check that no messages should be received at this moment
      27. - 
      -          checkNoMessageReceived();
-
      - -
    27. We commit!
      28. - 
      -          xaRes.commit(xid2, false);
-
      - -
    28. We check that all messages are received.
      29. - 
      -          checkAllMessageReceived();
-
      - -
    29. And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects
      30. - - 
      -           finally
-           {
-              if (initialContext != null)
-              {
-                initialContext.close();
-              }
-              if (connection != null)
-              {
-                 connection.close();
-              }
-           }
-
      -
    - - diff --git a/examples/features/standard/xa-send/readme.md b/examples/features/standard/xa-send/readme.md new file mode 100644 index 0000000000..baa35c6742 --- /dev/null +++ b/examples/features/standard/xa-send/readme.md @@ -0,0 +1,9 @@ +# JMS XA Send Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how message sending behaves in an XA transaction in ActiveMQ Artemis. When a message is sent within the scope of an XA transaction, it will only reach the queue once the transaction is committed. If the transaction is rolled back the sent messages will be discarded by the server. + +ActiveMQ Artemis is JTA aware, meaning you can use ActiveMQ Artemis in a XA transactional environment and participate in XA transactions. It provides the `javax.transaction.xa.XAResource` interface for that purpose. Users can get a XAConnectionFactory to create XAConnections and XASessions. + +In this example we simulate a transaction manager to control the transactions. First we create an XASession and enlist it in a transaction through its XAResource. We then send two words, `hello` and `world`, with the session, let the transaction roll back. The messages are discarded and never be received. Next we start a new transaction with the same XAResource, but this time we commit the transaction. Both messages are received. \ No newline at end of file diff --git a/examples/features/sub-modules/artemis-ra-rar/pom.xml b/examples/features/sub-modules/artemis-ra-rar/pom.xml index 6466710fbd..6c18ca9730 100644 --- a/examples/features/sub-modules/artemis-ra-rar/pom.xml +++ b/examples/features/sub-modules/artemis-ra-rar/pom.xml @@ -95,7 +95,23 @@ under the License. src/main/resources/ra.xml     + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/pom.xml b/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/pom.xml index 1bbccfbe28..e9809b6a0a 100644 --- a/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/pom.xml +++ b/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/pom.xml @@ -89,7 +89,23 @@ under the License. maven-war-plugin 3.1.0 + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/README.md b/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/readme.md similarity index 98% rename from examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/README.md rename to examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/readme.md index 775138004c..6674bbcd68 100644 --- a/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/README.md +++ b/examples/features/sub-modules/inter-broker-bridge/artemis-jms-bridge/readme.md @@ -123,7 +123,7 @@ http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/came ``` -6) Edit `$ARTEMIS_INSTANCE/etc/bootstrap.xml` so that the embedded web server runs on a different port that the 5.x broker (e.g. 8162): +6) Edit `$ARTEMIS_INSTANCE/etc/bootstrap.xml` so that the embedded web broker runs on a different port that the 5.x broker (e.g. 8162): ```xml diff --git a/examples/perf/jmeter/README.md b/examples/perf/jmeter/README.md deleted file mode 100644 index b1b2c6a699..0000000000 --- a/examples/perf/jmeter/README.md +++ /dev/null @@ -1,45 +0,0 @@ -####Running the ActiveMQ Artemis JMeter Performance Testing Examples - -######Create and run a sample broker for performance testing: - -```sh -artemis create my-broker --queues exampleQueue --topics exampleTopic - -my-broker/bin/artemis run -``` -######Download and Install JMeter's latest release: http://jmeter.apache.org/download_jmeter.cgi - -######Copy artemis-jms-client dependencies under $JMETER_HOME/lib folder: - -- artemis-jms-client.jar -- artemis-core-client.jar -- jgroups.jar -- artemis-commons.jar -- jboss-logmanager.jar -- jboss-logging.jar -- commons-beanutils.jar -- commons-logging.jar (already present under JMeter's lib folder - may not be needed) -- commons-collections.jar (already present under JMeter's lib folder - may not be needed) -- artemis-selector.jar -- artemis-journal.jar -- artemis-native.jar -- netty-all.jar -- javax.inject.jar -- geronimo-jms_2.0_spec.jar - -######Create a jndi.properties file with the connectionFactory Server Information: - -``` -connectionFactory.ConnectionFactory=tcp://localhost:61616 -``` - -######Pack jndi.properties file into a jar file and put it under $JMETER_HOME/lib folder: - -```sh -jar -cf artemis-jndi.jar jndi.properties -``` - -######Open jMeter and run the available Test Plan examples: - -- 1.jms_p2p_test.jmx -- 2.pub_sub_test.jmx diff --git a/examples/perf/jmeter/readme.md b/examples/perf/jmeter/readme.md new file mode 100644 index 0000000000..4c6b3dca9f --- /dev/null +++ b/examples/perf/jmeter/readme.md @@ -0,0 +1,33 @@ +#Running the ActiveMQ Artemis JMeter Performance Testing Examples + +##Create and run a sample broker for performance testing: + +```sh +artemis create my-broker --queues exampleQueue --topics exampleTopic + +my-broker/bin/artemis run +``` +##Download and Install JMeter's latest release: + +http://jmeter.apache.org/download_jmeter.cgi + +##Copy artemis-jms-client dependencies under $JMETER_HOME/lib folder: + +- artemis-jms-client-all.jar + +######Create a jndi.properties file with the connectionFactory: + +``` +connectionFactory.ConnectionFactory=tcp://localhost:61616 +``` + +######Pack jndi.properties file into a jar file and put it under $JMETER_HOME/lib folder: + +```sh +jar -cf artemis-jndi.jar jndi.properties +``` + +######Open jMeter and run the available Test Plan examples: + +- 1.jms_p2p_test.jmx +- 2.pub_sub_test.jmx diff --git a/examples/pom.xml b/examples/pom.xml index 35026a5c0e..224ea78cb2 100644 --- a/examples/pom.xml +++ b/examples/pom.xml @@ -49,6 +49,28 @@ under the License. + + + + + org.apache.maven.plugins + maven-clean-plugin + 3.0.0 + + + + ${basedir} + + readme.html + + + + + + + + + apache.snapshots @@ -82,6 +104,31 @@ under the License. true true + + + + + com.vladsch.flexmark + markdown-page-generator-plugin + 0.27.0 + + + package + + generate + + + + + ${activemq.basedir}/examples/common/header.html + ${activemq.basedir}/examples/common/footer.html + ${basedir} + ${basedir} + + + + + diff --git a/examples/protocols/amqp/proton-clustered-cpp/pom.xml b/examples/protocols/amqp/proton-clustered-cpp/pom.xml index 9fab41e007..db2fbf92d1 100644 --- a/examples/protocols/amqp/proton-clustered-cpp/pom.xml +++ b/examples/protocols/amqp/proton-clustered-cpp/pom.xml @@ -151,7 +151,6 @@ under the License.     - @@ -161,7 +160,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/amqp/proton-clustered-cpp/readme.html b/examples/protocols/amqp/proton-clustered-cpp/readme.html deleted file mode 100644 index 6a5ea8b743..0000000000 --- a/examples/protocols/amqp/proton-clustered-cpp/readme.html +++ /dev/null @@ -1,61 +0,0 @@ - - - - - ActiveMQ Artemis QPID cpp example - - - - - -

    AMQP CPP example

    - -

    ActiveMQ Artemis is a multi protocol broker. It will inspect the initial handshake of clients to determine what protocol to use.

    -

    All you need to do is to connect a client into activemq's configured port and you should be able connect.

    -

    To run this example simply run the command mvn verify -Pexample, execute the compile.sh script and start the executable called ./hello

    -
    -    # first make sure you have the dependencies you need to compile and run the client
-    # You will have to adapt this step according to your platform. Consult the qpid docs for more information.
-    # There is a list of packages you can install as well.
-    [proton-cpp]$ sudo yum install qpid-cpp-client-devel
-
-    # on a first window
-    [proton-cpp]$ mvn verify -Pexample
-
-    # on a second window
-    # That goes without saying but you will of course need g++ (the C++ compiler) installed
-    [proton-cpp]$ ./compile.sh
-    [proton-cpp]$ ./hello
-
    - - -

    You don't need to do anything special to configure the ActiveMQ Artemis server to accept AMQP clients.

    -

    Just for the sake of documentation though we are setting the port of ActiveMQ Artemis on this example as 5672 which is the port qpid have by default.

    -

    This is totally optional and you don't need to follow this convention. You can use any port you chose including ActiveMQ's 61616 default port

    - 
    -     
-         <acceptor name="proton-acceptor">tcp://localhost:5672</acceptor>
-     
-
    -

    Example step-by-step

    -

    We are using qpid cpp client on this example. There are several libraries you may chose from for AMQP. We have ellect one that we consider simple enough for users.

    - - - diff --git a/examples/protocols/amqp/proton-clustered-cpp/readme.md b/examples/protocols/amqp/proton-clustered-cpp/readme.md new file mode 100644 index 0000000000..8e87fed440 --- /dev/null +++ b/examples/protocols/amqp/proton-clustered-cpp/readme.md @@ -0,0 +1,32 @@ +# AMQP CPP example + +ActiveMQ Artemis is a multi protocol broker. It will inspect the initial handshake of clients to determine what protocol to use. + +All you need to do is to connect a client into activemq's configured port and you should be able connect. + +To run this example simply run the command **mvn verify -Pexample**, execute the compile.sh script and start the executable called ./hello + + # first make sure you have the dependencies you need to compile and run the client + # You will have to adapt this step according to your platform. Consult the [qpid docs](http://qpid.apache.org/releases/qpid-0.30/programming/book/) for more information. + # There is a list of [packages](http://qpid.apache.org/packages.html) you can install as well. + [proton-cpp]$ sudo yum install qpid-cpp-client-devel + + # on a first window + [proton-cpp]$ mvn verify -Pexample + + # on a second window + # That goes without saying but you will of course need g++ (the C++ compiler) installed + [proton-cpp]$ ./compile.sh + [proton-cpp]$ ./hello + +You don't need to do anything special to configure the ActiveMQ Artemis broker to accept AMQP clients. + +Just for the sake of documentation though we are setting the port of ActiveMQ Artemis on this example as 5672 which is the port qpid have by default. + +This is totally optional and you don't need to follow this convention. You can use any port you chose including ActiveMQ's 61616 default port + + tcp://localhost:5672 + +## Example step-by-step + +We are using qpid cpp client on this example. There are several libraries you may chose from for AMQP. We have ellect one that we consider simple enough for users. \ No newline at end of file diff --git a/examples/protocols/amqp/proton-clustered-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java b/examples/protocols/amqp/proton-clustered-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java index 961a56b5f8..d8de7514bf 100644 --- a/examples/protocols/amqp/proton-clustered-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java +++ b/examples/protocols/amqp/proton-clustered-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java @@ -31,7 +31,7 @@ import org.apache.qpid.jms.JmsConnectionFactory; * This example demonstrates the use of ActiveMQ Artemis "pre-acknowledge" functionality where * messages are acknowledged before they are delivered to the consumer. *

    - * Please see the readme.html for more details. + * Please see the readme for more details. */ public class ProtonCPPExample { diff --git a/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server0/broker.xml b/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server0/broker.xml index 240d25670d..bcfc677450 100644 --- a/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server0/broker.xml +++ b/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server0/broker.xml @@ -17,10 +17,7 @@ KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> - - - + ./data/bindings diff --git a/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server1/broker.xml b/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server1/broker.xml index 115f28c388..bad1eb8287 100644 --- a/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server1/broker.xml +++ b/examples/protocols/amqp/proton-clustered-cpp/src/main/resources/activemq/server1/broker.xml @@ -17,10 +17,7 @@ KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> - - - + ./data/bindings diff --git a/examples/protocols/amqp/proton-cpp/pom.xml b/examples/protocols/amqp/proton-cpp/pom.xml index d2f0aefc4b..2bfffbddba 100644 --- a/examples/protocols/amqp/proton-cpp/pom.xml +++ b/examples/protocols/amqp/proton-cpp/pom.xml @@ -111,7 +111,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/amqp/proton-cpp/readme.html b/examples/protocols/amqp/proton-cpp/readme.html deleted file mode 100644 index ba9e6357b7..0000000000 --- a/examples/protocols/amqp/proton-cpp/readme.html +++ /dev/null @@ -1,120 +0,0 @@ - - - - - ActiveMQ Artemis QPID cpp example - - - - - -

    AMQP CPP example

    - -

    ActiveMQ Artemis is a multi protocol broker. It will inspect the initial handshake of clients to determine what protocol to use.

    -

    All you need to do is to connect a client into activemq's configured port and you should be able connect.

    -

    To run this example simply run the command mvn verify -Pexample, execute the compile.sh script and start the executable called ./hello

    -
    -    # first make sure you have the dependencies you need to compile and run the client
-    # You will have to adapt this step according to your platform. Consult the qpid docs for more information.
-    # There is a list of packages you can install as well.
-    [proton-cpp]$ sudo yum install qpid-cpp-client-devel
-
-    # on a first window
-    [proton-cpp]$ mvn verify -Pexample
-
-    # on a second window
-    # That goes without saying but you will of course need g++ (the C++ compiler) installed
-    [proton-cpp]$ ./compile.sh
-    [proton-cpp]$ ./hello
-
    - - -

    You don't need to do anything special to configure the ActiveMQ Artemis server to accept AMQP clients.

    -

    Just for the sake of documentation though we are setting the port of ActiveMQ Artemis on this example as 5672 which is the port qpid have by default.

    -

    This is totally optional and you don't need to follow this convention. You can use any port you chose including ActiveMQ's 61616 default port

    - 
    -     
-         <acceptor name="proton-acceptor">tcp://localhost:5672</acceptor>
-     
-
    -

    Example step-by-step

    -

    We are using qpid cpp client on this example. There are several libraries you may chose from for AMQP. We have ellect one that we consider simple enough for users.

    - -

    This example is based on qpid's hello world example.

    -
      -
    1. qpid-cpp-client-devel installed.
      2. -

      Assuming you are on Linux Fedora, you will need to run this following command

      - 
      -        yum install qpid-cpp-client-devel
-
      -

      Consult the qpid documentation, and the required packages for information on other platoforms.

      -
    2. Make the proper C++ imports
      3. - -
    3. Create an amqp qpid 1.0 connection.
      4. - 
      -           
-        std::string broker = argc > 1 ? argv[1] : "localhost:61616";
-        std::string address = argc > 2 ? argv[2] : "jms.queue.exampleQueue";
-        std::string connectionOptions = argc > 3 ? argv[3] : "{protocol:amqp1.0}"; // Look at the docs for more options
-
-        Connection connection(broker, connectionOptions);
-        connection.open();
-           
-
      - -
    4. Create a session
      5. - 
      -       Session session = connection.createSession();
-
      - -
    5. Create a sender
      6. - 
      -       Sender sender = session.createSender(address);
-
      - -
    6. send a simple message
      7. - 
      -       sender.send(Message("Hello world!"));
-
      - -
    7. create a receiver
      8. - 
      -       Receiver receiver = session.createReceiver(address);
-
      - -
    8. receive the simple message
      9. - 
      -      Message message = receiver.fetch(Duration::SECOND * 1);
-      
-
      - -
    9. acknowledge the message
      10. - 
      -      session.acknowledge();
-
      - -
    10. close the connection
      11. - 
      -      connection.close();
-
      -
    - - - diff --git a/examples/protocols/amqp/proton-cpp/readme.md b/examples/protocols/amqp/proton-cpp/readme.md new file mode 100644 index 0000000000..2acf171b62 --- /dev/null +++ b/examples/protocols/amqp/proton-cpp/readme.md @@ -0,0 +1,80 @@ +# AMQP CPP example + +ActiveMQ Artemis is a multi protocol broker. It will inspect the initial handshake of clients to determine what protocol to use. + +All you need to do is to connect a client into ActiveMQ's configured port and you should be able connect. + +To run this example simply run the command **mvn verify -Pexample**, execute the compile.sh script and start the executable called ./hello + + # first make sure you have the dependencies you need to compile and run the client + # You will have to adapt this step according to your platform. Consult the [qpid docs](http://qpid.apache.org/releases/qpid-0.30/programming/book/) for more information. + # There is a list of [packages](http://qpid.apache.org/packages.html) you can install as well. + [proton-cpp]$ sudo yum install qpid-cpp-client-devel + + # on a first window + [proton-cpp]$ mvn verify -Pexample + + # on a second window + # That goes without saying but you will of course need g++ (the C++ compiler) installed + [proton-cpp]$ ./compile.sh + [proton-cpp]$ ./hello + +You don't need to do anything special to configure the ActiveMQ Artemis broker to accept AMQP clients. + +Just for the sake of documentation though we are setting the port of ActiveMQ Artemis on this example as 5672 which is the port qpid have by default. + +This is totally optional and you don't need to follow this convention. You can use any port you chose including ActiveMQ's 61616 default port: + + tcp://localhost:5672 + +## Example step-by-step + +We are using qpid cpp client on this example. There are several libraries you may chose from for AMQP. We have ellect one that we consider simple enough for users. + +This example is based on [qpid's hello world example](http://qpid.apache.org/releases/qpid-0.30/messaging-api/cpp/examples/hello_world.cpp.html). + +1. qpid-cpp-client-devel installed. + +Assuming you are on Linux Fedora, you will need to run this following command + + yum install qpid-cpp-client-devel + +Consult the [qpid documentation](http://qpid.apache.org/releases/qpid-0.30/programming/book/), and [the required](http://qpid.apache.org/packages.html) packages for information on other platoforms. + +5. Make the proper C++ imports +6. Create an amqp qpid 1.0 connection. + + std::string broker = argc > 1 ? argv[1] : "localhost:61616"; + std::string address = argc > 2 ? argv[2] : "jms.queue.exampleQueue"; + std::string connectionOptions = argc > 3 ? argv[3] : "{protocol:amqp1.0}"; // Look at the [docs](http://qpid.apache.org/releases/qpid-0.30/programming/book/connections.html#connection-options) for more options + + Connection connection(broker, connectionOptions); + connection.open(); + +8. Create a session + + Session session = connection.createSession(); + +10. Create a sender + + Sender sender = session.createSender(address); + +12. send a simple message + + sender.send(Message("Hello world!")); + +14. create a receiver + + Receiver receiver = session.createReceiver(address); + +16. receive the simple message + + Message message = receiver.fetch(Duration::SECOND * 1); + +18. acknowledge the message + + session.acknowledge(); + +20. close the connection + + connection.close(); \ No newline at end of file diff --git a/examples/protocols/amqp/proton-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java b/examples/protocols/amqp/proton-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java index 961a56b5f8..d8de7514bf 100644 --- a/examples/protocols/amqp/proton-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java +++ b/examples/protocols/amqp/proton-cpp/src/main/java/org/apache/activemq/artemis/jms/example/ProtonCPPExample.java @@ -31,7 +31,7 @@ import org.apache.qpid.jms.JmsConnectionFactory; * This example demonstrates the use of ActiveMQ Artemis "pre-acknowledge" functionality where * messages are acknowledged before they are delivered to the consumer. *

    - * Please see the readme.html for more details. + * Please see the readme for more details. */ public class ProtonCPPExample { diff --git a/examples/protocols/amqp/proton-ruby/pom.xml b/examples/protocols/amqp/proton-ruby/pom.xml index 676355f179..9b2efbf851 100644 --- a/examples/protocols/amqp/proton-ruby/pom.xml +++ b/examples/protocols/amqp/proton-ruby/pom.xml @@ -60,7 +60,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/amqp/proton-ruby/readme.html b/examples/protocols/amqp/proton-ruby/readme.html deleted file mode 100644 index f7f83fb878..0000000000 --- a/examples/protocols/amqp/proton-ruby/readme.html +++ /dev/null @@ -1,51 +0,0 @@ - - - - - ActiveMQ Artemis Proton Ruby Example - - - - - -

    Proton Ruby Example

    - -

    ActiveMQ Artemis can be configured to accept requests from any AMQP client that supports the 1.0 version of the protocol. - This example shows a simply proton ruby client that sends and receives messages

    -

    To run the example you will need the following packages installed, alsa-lib.i686 libXv.i686 libXScrnSaver.i686 qt.i686 qt-x11.i686 qtwebkit-2.2.2-2.fc18.i686, gcc, ruby

    -

    On fedora you can install these via the yum install alsa-lib.i686 libXv.i686 libXScrnSaver.i686 qt.i686 qt-x11.i686 qtwebkit-2.2.2-2.fc18.i686, gcc, ruby - command

    -

    you will also need the qpid-proton libraries installed, again yum install qpid-proton

    -

    lastly you wull have to create the gems gem install qpid_proton

    - -

    To configure ActiveMQ Artemis to accept AMQP client connections you need to add an Acceptor like so:

    - 
    -     
-     <acceptor name="proton-acceptor">tcp://localhost:5672?protocols=AMQP</acceptor>
-     
-
    -

    Example step-by-step

    -

    Firstly create the server by running the command mvn verify

    -

    Start the server manually under ./target/server1/bin by calling ./artemis run

    -

    Then in a separate window you can run the send ruby script by running the command ruby src/main/scripts/send.rb

    -

    You can then receive the message via the receive ruby script by running ruby src/main/scripts/receive.rb

    - - - diff --git a/examples/protocols/amqp/proton-ruby/readme.md b/examples/protocols/amqp/proton-ruby/readme.md new file mode 100644 index 0000000000..8e01056293 --- /dev/null +++ b/examples/protocols/amqp/proton-ruby/readme.md @@ -0,0 +1,25 @@ +# Proton Ruby Example + +ActiveMQ Artemis can be configured to accept requests from any AMQP client that supports the 1.0 version of the protocol. This example shows a simply proton ruby client that sends and receives messages. + +To run the example you will need the following packages installed, alsa-lib.i686 libXv.i686 libXScrnSaver.i686 qt.i686 qt-x11.i686 qtwebkit-2.2.2-2.fc18.i686, gcc, ruby. + +On fedora you can install these via the `yum install alsa-lib.i686 libXv.i686 libXScrnSaver.i686 qt.i686 qt-x11.i686 qtwebkit-2.2.2-2.fc18.i686, gcc, ruby` command. + +you will also need the qpid-proton libraries installed, again `yum install qpid-proton`. + +lastly you wull have to create the gems `gem install qpid_proton`. + +To configure ActiveMQ Artemis to accept AMQP client connections you need to add an Acceptor like so: + + tcp://localhost:5672?protocols=AMQP + +## Example step-by-step + +Firstly create the broker by running the command **mvn verify**. + +Start the broker manually under ./target/server1/bin by calling `./artemis run`. + +Then in a separate window you can run the send ruby script by running the command `ruby src/main/scripts/send.rb`. + +You can then receive the message via the receive ruby script by running `ruby src/main/scripts/receive.rb`. \ No newline at end of file diff --git a/examples/protocols/amqp/proton-ruby/src/main/resources/activemq/server0/broker.xml b/examples/protocols/amqp/proton-ruby/src/main/resources/activemq/server0/broker.xml index 50f0a6731e..c759bc5394 100644 --- a/examples/protocols/amqp/proton-ruby/src/main/resources/activemq/server0/broker.xml +++ b/examples/protocols/amqp/proton-ruby/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ${data.dir}/server0/data/messaging/bindings @@ -50,7 +48,7 @@ under the License. - +
    diff --git a/examples/protocols/amqp/queue/pom.xml b/examples/protocols/amqp/queue/pom.xml index b897f4be3e..58895294bf 100644 --- a/examples/protocols/amqp/queue/pom.xml +++ b/examples/protocols/amqp/queue/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/amqp/queue/readme.html b/examples/protocols/amqp/queue/readme.html deleted file mode 100644 index 4eb1f0c76b..0000000000 --- a/examples/protocols/amqp/queue/readme.html +++ /dev/null @@ -1,46 +0,0 @@ - - - - - ActiveMQ Artemis QPID java example - - - - - -

    Proton qpid java example

    - -
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -<

    ActiveMQ Artemis is a multi protocol broker. It will inspect the initial handshake of clients to determine what protocol to use.

    -

    All you need to do is to connect a client into activemq's configured port and you should be able connect.

    -

    To run this example simply run the command mvn verify -Pexample, execute the compile.sh script and start the executable called ./hello

    - -

    You don't need to do anything special to configure the ActiveMQ Artemis server to accept AMQP clients.

    -

    Just for the sake of documentation though we are setting the port of ActiveMQ Artemis on this example as 5672 which is the port qpid have by default.

    -

    This is totally optional and you don't need to follow this convention. You can use any port you chose including ActiveMQ's 61616 default port

    - 
    -     
-         <acceptor name="proton-acceptor">tcp://localhost:5672</acceptor>
-     
-
    - - diff --git a/examples/protocols/amqp/queue/readme.md b/examples/protocols/amqp/queue/readme.md new file mode 100644 index 0000000000..9b34e7e208 --- /dev/null +++ b/examples/protocols/amqp/queue/readme.md @@ -0,0 +1,17 @@ +# Proton qpid java example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +ActiveMQ Artemis is a multi protocol broker. It will inspect the initial handshake of clients to determine what protocol to use. + +All you need to do is to connect a client into activemq's configured port and you should be able connect. + +To run this example simply run the command **mvn verify -Pexample**, execute the `compile.sh` script and start the executable called `./hello`. + +You don't need to do anything special to configure the ActiveMQ Artemis broker to accept AMQP clients. + +Just for the sake of documentation though we are setting the port of ActiveMQ Artemis on this example as 5672 which is the port qpid have by default. + +This is totally optional and you don't need to follow this convention. You can use any port you chose including ActiveMQ's 61616 default port + + tcp://localhost:5672 \ No newline at end of file diff --git a/examples/protocols/mqtt/basic-pubsub/pom.xml b/examples/protocols/mqtt/basic-pubsub/pom.xml index 05252fbd09..73671b4cb2 100644 --- a/examples/protocols/mqtt/basic-pubsub/pom.xml +++ b/examples/protocols/mqtt/basic-pubsub/pom.xml @@ -99,7 +99,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/mqtt/basic-pubsub/readme.html b/examples/protocols/mqtt/basic-pubsub/readme.html deleted file mode 100644 index ca7dbff14b..0000000000 --- a/examples/protocols/mqtt/basic-pubsub/readme.html +++ /dev/null @@ -1,136 +0,0 @@ - - - - - ActiveMQ Artemis MQTT Example - - - - - -

    MQTT Example

    - -

    This is a basic MQTT example that demonstrates how to setup and connect to an Apache Artemis broker and - send and receive messages using the MQTT protocol.

    - -

    Setting up the server

    - -

    This example will use the default out of the box configuration of Artemis you don't need to change anything to run - this example. Artemis ships with all protocols enabled on port 61616 and also MQTT on port 1883. To enable MQTT - on a different port you can add the following XML snippet to the 'acceptors' section of your broker.xml - configuration file (changing the port from 1883 to what ever you require).

    - - - 
    -         
-         <acceptor name="hornetq">tcp://0.0.0.0:1883?protocols=MQTT"></acceptor>
-
    - - For more information on configuring protocol transports see the "Configuring Transports" section of the user - manual, specifically the section called "Single Port Support". - -

    MQTT Clients

    - -

    There are a number of MQTT client implementations for various languages. The Paho project: - http://www.eclipse.org/paho/ offers a number of clients for languages such as C, Python, JavaScript and .Net and - is also a great resource for all things MQTT. - - This example is actually based on the Fuse MQTT java client and was chosen as it is Apache 2.0 licensed and - available to download from maven central. The specific client used in the example is not of importance and is - used simply to demonstrate the features of MQTT as provided by Apache Artemis.

    - -

    If you'd like to use the client demonstrated in this example, simple add the following dependency to your - pom.xml

    - - 
    -        <dependency>
-            <groupId>org.fusesource.mqtt-client</groupId>
-            <artifactId>mqtt-client</artifactId>
-            <version>1.10</version>
-        </dependency>
-
    - -

    Example Step by Step

    - - -
  • 1. Connect to Artemis
    • - -

    We start by creating a connection to the Apache Artemis broker. In this example we specify to use TCP - protocol on localhost. By default Apache Artemis will start all protocols on port 61616, so we connect - to that port.

    - - 
    -             MQTT mqtt = new MQTT();
-             mqtt.setHost("tcp://localhost:61616");
-             BlockingConnection connection = mqtt.blockingConnection();
-             connection.connect();
-
    - -
  • 2. Create subscriptions
    • - -

    Subscriptions in MQTT are realised by subscribing to a particular Topic. Each Topic has an address - and a quality of service level (QoS level). Subscriptions also support wildcards. In the code below we - subscribe to a Topic with address "mqtt/example/publish", a wildcard address "test/#" which will - match anything starting with "test/" and also a wildcard "foo/+/bar", where + matches a single level of the hierarchy (foo/something/bar)

    - - 
    -             Topic[] topics = { new Topic("mqtt/example/publish", QoS.AT_LEAST_ONCE), new Topic("test/#", QoS.EXACTLY_ONCE), new Topic("foo/+/bar", QoS.AT_LEAST_ONCE) };
-             connection.subscribe(topics);
-
    - -
  • 3. Sending messages
    • - -

    There is no type system in MQTT, messages simply consist of a number of bytes. Below we send three messages with - UTF8 encoded strings (as a byte array). Notice the second message is sent to "test/test" which should match - the first wildcard subscription we defined previously. The third message is sent to "foo/1/bar", which matches the second wildcard subscription.

    - - 
    -             String payload1 = "This is message 1";
-             String payload2 = "This is message 2";
-             String payload3 = "This is message 3";
-
-             connection.publish("mqtt/example/publish", payload1.getBytes(), QoS.AT_LEAST_ONCE, false);
-             connection.publish("mqtt/test", payload2.getBytes(), QoS.AT_MOST_ONCE, false);
-             connection.publish("foo/1/bar", payload3.getBytes(), QoS.AT_MOST_ONCE, false);
-
    - -
  • 4. Receiving messages
    • - -

    Since we have subscribed to a number of topics and sent messages to them, the client should now receive - 2 messages. We are not using callbacks here on message receive so we specifically call receive to get - the messages. Once we receive the message we convert the payload consisting of bytes back to a UTF8 - encoded string and print the result.

    - - 
    -             Message message1 = connection.receive(5, TimeUnit.SECONDS);
-             Message message2 = connection.receive(5, TimeUnit.SECONDS);
-             Message message3 = connection.receive(5, TimeUnit.SECONDS);
-
-             System.out.println(new String(message1.getPayload()));
-             System.out.println(new String(message2.getPayload()));
-             System.out.println(new String(message3.getPayload()));
-
    -     - -

    Result

    - This example has shown you how to set up the basics of MQTT including how to connect to the Artemis broker and - how to send and receive messages including subscriptions using wildcard addresses. - - diff --git a/examples/protocols/mqtt/basic-pubsub/readme.md b/examples/protocols/mqtt/basic-pubsub/readme.md new file mode 100644 index 0000000000..b7ea993004 --- /dev/null +++ b/examples/protocols/mqtt/basic-pubsub/readme.md @@ -0,0 +1,69 @@ +# MQTT Example + +This is a basic MQTT example that demonstrates how to setup and connect to an Apache Artemis broker and send and receive messages using the MQTT protocol. + +## Setting up the Broker + +This example will use the default out of the box configuration of Artemis you don't need to change anything to run this example. Artemis ships with all protocols enabled on port 61616 and also MQTT on port 1883. To enable MQTT on a different port you can add the following XML snippet to the `acceptors` section of your broker.xml configuration file (changing the port from 1883 to what ever you require). + + tcp://0.0.0.0:1883?protocols=MQTT"> + +For more information on configuring protocol transports see the "Configuring Transports" section of the user manual, specifically the section called "Single Port Support". + +## MQTT Clients + +There are a number of MQTT client implementations for various languages. The Paho project: http://www.eclipse.org/paho/ offers a number of clients for languages such as C, Python, JavaScript and .Net and is also a great resource for all things MQTT. This example is actually based on the Fuse MQTT java client and was chosen as it is Apache 2.0 licensed and available to download from maven central. The specific client used in the example is not of importance and is used simply to demonstrate the features of MQTT as provided by Apache Artemis. + +If you'd like to use the client demonstrated in this example, simple add the following dependency to your pom.xml + + + org.fusesource.mqtt-client + mqtt-client + 1.10 + + +## Example Step by Step + +* Connect to Artemis + +We start by creating a connection to the Apache Artemis broker. In this example we specify to use TCP protocol on localhost. By default Apache Artemis will start all protocols on port 61616, so we connect to that port. + + MQTT mqtt = new MQTT(); + mqtt.setHost("tcp://localhost:61616"); + BlockingConnection connection = mqtt.blockingConnection(); + connection.connect(); + +* Create subscriptions + +Subscriptions in MQTT are realised by subscribing to a particular Topic. Each Topic has an address and a quality of service level (QoS level). Subscriptions also support wildcards. In the code below we subscribe to a Topic with address "mqtt/example/publish", a wildcard address "test/#" which will match anything starting with "test/" and also a wildcard "foo/+/bar", where + matches a single level of the hierarchy (foo/something/bar) + + Topic[] topics = { new Topic("mqtt/example/publish", QoS.AT_LEAST_ONCE), new Topic("test/#", QoS.EXACTLY_ONCE), new Topic("foo/+/bar", QoS.AT_LEAST_ONCE) }; + connection.subscribe(topics); + +* Sending messages + +There is no type system in MQTT, messages simply consist of a number of bytes. Below we send three messages with UTF8 encoded strings (as a byte array). Notice the second message is sent to "test/test" which should match the first wildcard subscription we defined previously. The third message is sent to "foo/1/bar", which matches the second wildcard subscription. + + String payload1 = "This is message 1"; + String payload2 = "This is message 2"; + String payload3 = "This is message 3"; + + connection.publish("mqtt/example/publish", payload1.getBytes(), QoS.AT_LEAST_ONCE, false); + connection.publish("mqtt/test", payload2.getBytes(), QoS.AT_MOST_ONCE, false); + connection.publish("foo/1/bar", payload3.getBytes(), QoS.AT_MOST_ONCE, false); + +* Receiving messages + +Since we have subscribed to a number of topics and sent messages to them, the client should now receive 2 messages. We are not using callbacks here on message receive so we specifically call receive to get the messages. Once we receive the message we convert the payload consisting of bytes back to a UTF8 encoded string and print the result. + + Message message1 = connection.receive(5, TimeUnit.SECONDS); + Message message2 = connection.receive(5, TimeUnit.SECONDS); + Message message3 = connection.receive(5, TimeUnit.SECONDS); + + System.out.println(new String(message1.getPayload())); + System.out.println(new String(message2.getPayload())); + System.out.println(new String(message3.getPayload())); + +## Result + +This example has shown you how to set up the basics of MQTT including how to connect to the Artemis broker and how to send and receive messages including subscriptions using wildcard addresses. \ No newline at end of file diff --git a/examples/protocols/mqtt/clustered-queue-mqtt/pom.xml b/examples/protocols/mqtt/clustered-queue-mqtt/pom.xml index 6deacc0cda..374d703931 100644 --- a/examples/protocols/mqtt/clustered-queue-mqtt/pom.xml +++ b/examples/protocols/mqtt/clustered-queue-mqtt/pom.xml @@ -155,7 +155,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/mqtt/clustered-queue-mqtt/readme.html b/examples/protocols/mqtt/clustered-queue-mqtt/readme.html deleted file mode 100644 index a39fc4c6b4..0000000000 --- a/examples/protocols/mqtt/clustered-queue-mqtt/readme.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - ActiveMQ Artemis JMS Load Balanced Clustered Queue Example - - - - - -

    JMS Load Balanced Clustered Queue Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example demonstrates a JMS queue deployed on two different nodes. The two nodes are configured to form a cluster.

    -

    We then create a consumer on the queue on each node, and we create a producer on only one of the nodes.

    -

    We then send some messages via the producer, and we verify that both consumers receive the sent messages - in a round-robin fashion.

    -

    In other words, ActiveMQ Artemis load balances the sent messages across all consumers on the cluster

    -

    This example uses JNDI to lookup the JMS Queue and ConnectionFactory objects. If you prefer not to use - JNDI, these could be instantiated directly.

    -

    Here's the relevant snippet from the server configuration, which tells the server to form a cluster between the two nodes - and to load balance the messages between the nodes.

    - 
    -     <cluster-connection name="my-cluster">
-        <connector-ref>netty-connector</connector-ref>
-        <retry-interval>500</retry-interval>
-        <use-duplicate-detection>true</use-duplicate-detection>
-        <message-load-balancing>STRICT</message-load-balancing>
-        <max-hops>1</max-hops>
-        <discovery-group-ref discovery-group-name="my-discovery-group"/>
-     </cluster-connection>
-     
-
    -

    For more information on ActiveMQ Artemis load balancing, and clustering in general, please see the clustering - section of the user manual.

    - - diff --git a/examples/protocols/mqtt/clustered-queue-mqtt/readme.md b/examples/protocols/mqtt/clustered-queue-mqtt/readme.md new file mode 100644 index 0000000000..eb714f9bb3 --- /dev/null +++ b/examples/protocols/mqtt/clustered-queue-mqtt/readme.md @@ -0,0 +1,11 @@ +# MQTT Clustered Subscription Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example demonstrates a queue deployed on two different nodes. The two nodes are configured to form a cluster. + +We then create an MQTT subscriber on the queue on each node, and we create a producer on only one of the nodes. + +We then send some messages via the producer, and we verify that **both** subscribers receive the sent messages. + +For more information on ActiveMQ Artemis clustering please see the clustering section of the user manual. \ No newline at end of file diff --git a/examples/protocols/mqtt/clustered-queue-mqtt/src/main/java/org/apache/activemq/artemis/jms/example/ClusteredQueueMQTTExample.java b/examples/protocols/mqtt/clustered-queue-mqtt/src/main/java/org/apache/activemq/artemis/jms/example/ClusteredQueueMQTTExample.java index 0f60ac31ad..51845accba 100644 --- a/examples/protocols/mqtt/clustered-queue-mqtt/src/main/java/org/apache/activemq/artemis/jms/example/ClusteredQueueMQTTExample.java +++ b/examples/protocols/mqtt/clustered-queue-mqtt/src/main/java/org/apache/activemq/artemis/jms/example/ClusteredQueueMQTTExample.java @@ -24,8 +24,7 @@ import org.fusesource.mqtt.client.QoS; import org.fusesource.mqtt.client.Topic; /** - * A simple example that demonstrates server side load-balancing of messages between the queue instances on different - * nodes of the cluster. + * A simple example that demonstrates an MQTT subscription on different nodes of the cluster. */ public class ClusteredQueueMQTTExample { diff --git a/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server0/broker.xml b/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server0/broker.xml index bc4365967d..c64362739c 100644 --- a/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server0/broker.xml +++ b/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server0/broker.xml @@ -17,7 +17,7 @@ KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> - + false @@ -60,7 +60,6 @@ under the License. - netty-connector 5 true diff --git a/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server1/broker.xml b/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server1/broker.xml index 6b386daffb..9ffcc73de4 100644 --- a/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server1/broker.xml +++ b/examples/protocols/mqtt/clustered-queue-mqtt/src/main/resources/activemq/server1/broker.xml @@ -17,7 +17,7 @@ KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> - + false @@ -60,7 +60,6 @@ under the License. - netty-connector 5 true diff --git a/examples/protocols/openwire/chat/pom.xml b/examples/protocols/openwire/chat/pom.xml index 382ebd0308..34b0b5ad4e 100644 --- a/examples/protocols/openwire/chat/pom.xml +++ b/examples/protocols/openwire/chat/pom.xml @@ -56,6 +56,16 @@ under the License. slf4j-nop + + + + + org.apache.maven.plugins + maven-clean-plugin + + + + server @@ -194,6 +204,17 @@ under the License. + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + diff --git a/examples/protocols/openwire/chat/readme.html b/examples/protocols/openwire/chat/readme.html deleted file mode 100644 index 9cd72a4a55..0000000000 --- a/examples/protocols/openwire/chat/readme.html +++ /dev/null @@ -1,53 +0,0 @@ - - - - - ActiveMQ Artemis Openwire Chat Example - - - - - -

    Openwire Chat Example

    - -

    This example will require multiple windows to be executed

    - - 
    Window 1: mvn -Pserver verify
    - 
    Window 2: mvn -Pchat1 verify
    - 
    Window 3: mvn -Pchat2 verify
    - 
    Window 4: mvn -Pchat3 verify
    - - -

    You should be able to interact with the chat application:

    - - 
    -Chat application:
-=================
-The application user Chatter2 connects to the broker at tcp://localhost:61616.
-The application will publish messages to the jms.samples.chat topic.
-The application also subscribes to that topic to consume any messages published there.
-
-Type some text, and then press Enter to publish it as a TextMesssage from Chatter2.
-
-Hello guys
-Chatter2: Hello guys
-
    - - diff --git a/examples/protocols/openwire/chat/readme.md b/examples/protocols/openwire/chat/readme.md new file mode 100644 index 0000000000..42bf00e96a --- /dev/null +++ b/examples/protocols/openwire/chat/readme.md @@ -0,0 +1,33 @@ +# Openwire Chat Example + +This example will require multiple windows to be executed + +Window 1: + + mvn -Pserver verify + +Window 2: + + mvn -Pchat1 verify + +Window 3: + + mvn -Pchat2 verify + +Window 4: + + mvn -Pchat3 verify + +You should be able to interact with the chat application: + +## Chat application: +The application user Chatter2 connects to the broker at `tcp://localhost:61616`. + +The application will publish messages to the `chat` address. + +The application also subscribes to that topic to consume any messages published there. + +Type some text, and then press Enter to publish it as a TextMesssage from Chatter2. + + Hello guys + Chatter2: Hello guys \ No newline at end of file diff --git a/examples/protocols/openwire/message-listener/pom.xml b/examples/protocols/openwire/message-listener/pom.xml index 7e695f8459..db947f4a09 100644 --- a/examples/protocols/openwire/message-listener/pom.xml +++ b/examples/protocols/openwire/message-listener/pom.xml @@ -108,7 +108,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/openwire/message-listener/readme.html b/examples/protocols/openwire/message-listener/readme.html deleted file mode 100644 index e46e834169..0000000000 --- a/examples/protocols/openwire/message-listener/readme.html +++ /dev/null @@ -1,35 +0,0 @@ - - - - - ActiveMQ Artemis JMS Queue Example - - - - - -

    JMS Queue Message Listener for openwire

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows how to use a MessageListener with the openwire client

    - - - diff --git a/examples/protocols/openwire/message-listener/readme.md b/examples/protocols/openwire/message-listener/readme.md new file mode 100644 index 0000000000..04c43d34f8 --- /dev/null +++ b/examples/protocols/openwire/message-listener/readme.md @@ -0,0 +1,5 @@ +# JMS Queue Message Listener for OpenWire + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows how to use a MessageListener with the OpenWire client \ No newline at end of file diff --git a/examples/protocols/openwire/message-recovery/pom.xml b/examples/protocols/openwire/message-recovery/pom.xml index 000343af85..62bf8e4d86 100644 --- a/examples/protocols/openwire/message-recovery/pom.xml +++ b/examples/protocols/openwire/message-recovery/pom.xml @@ -94,7 +94,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/openwire/message-recovery/readme.md b/examples/protocols/openwire/message-recovery/readme.md new file mode 100644 index 0000000000..a276fa20ab --- /dev/null +++ b/examples/protocols/openwire/message-recovery/readme.md @@ -0,0 +1,5 @@ +# JMS Queue Message Listener for OpenWire + +This example will start and stop the broker within the example. + +This example shows how to use send messages to a queue, and having these messages recovered from the journal. \ No newline at end of file diff --git a/examples/protocols/openwire/queue/pom.xml b/examples/protocols/openwire/queue/pom.xml index 896bb4c36e..facd57424e 100644 --- a/examples/protocols/openwire/queue/pom.xml +++ b/examples/protocols/openwire/queue/pom.xml @@ -111,7 +111,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/openwire/queue/readme.html b/examples/protocols/openwire/queue/readme.html deleted file mode 100644 index 948977f293..0000000000 --- a/examples/protocols/openwire/queue/readme.html +++ /dev/null @@ -1,39 +0,0 @@ - - - - - ActiveMQ Artemis JMS Queue Example - - - - - -

    JMS Queue Example for open wire

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to send and receive a message to a JMS Queue using ActiveMQ Artemis.

    -

    This example does exactly the same as the queue example under broker-features/standard, however using the openwire client.

    -

    Queues are a standard part of JMS, please consult the JMS 1.1 specification for full details.

    -

    A Queue is used to send messages point to point, from a producer to a consumer. The queue guarantees message ordering between these 2 points.

    -

    Notice this example is using pretty much a default stock configuration

    - - diff --git a/examples/protocols/openwire/queue/readme.md b/examples/protocols/openwire/queue/readme.md new file mode 100644 index 0000000000..4d77c34c36 --- /dev/null +++ b/examples/protocols/openwire/queue/readme.md @@ -0,0 +1,13 @@ +# JMS Queue Example for OpenWire + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to send and receive a message to a JMS Queue using ActiveMQ Artemis. + +This example does exactly the same as the "queue" example however using the OpenWire client. + +Queues are a standard part of JMS, please consult the JMS 1.1 specification for full details. + +A Queue is used to send messages point to point, from a producer to a consumer. The queue guarantees message ordering between these 2 points. + +Notice this example is using pretty much a default stock configuration \ No newline at end of file diff --git a/examples/protocols/stomp/pom.xml b/examples/protocols/stomp/pom.xml index 4c51a82544..e404d2dd0a 100644 --- a/examples/protocols/stomp/pom.xml +++ b/examples/protocols/stomp/pom.xml @@ -44,6 +44,7 @@ under the License. release stomp + stomp-dual-authentication stomp-websockets stomp-embedded-interceptor stomp1.1 @@ -55,6 +56,7 @@ under the License. examples stomp + stomp-dual-authentication stomp-embedded-interceptor stomp-jms diff --git a/examples/protocols/stomp/stomp-dual-authentication/pom.xml b/examples/protocols/stomp/stomp-dual-authentication/pom.xml index 70ae9ffc3b..b9f3883c9c 100644 --- a/examples/protocols/stomp/stomp-dual-authentication/pom.xml +++ b/examples/protocols/stomp/stomp-dual-authentication/pom.xml @@ -24,12 +24,12 @@ under the License. org.apache.activemq.examples.stomp stomp-examples - 1.4.0-SNAPSHOT + 2.5.0-SNAPSHOT stomp-dual-authentication jar - ActiveMQ Artemis JMS Stomp Dual Authentication Example + ActiveMQ Artemis Stomp Dual Authentication Example ${project.basedir}/../../../.. @@ -110,7 +110,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/stomp/stomp-dual-authentication/readme.html b/examples/protocols/stomp/stomp-dual-authentication/readme.html deleted file mode 100644 index 5ed4a2fcdf..0000000000 --- a/examples/protocols/stomp/stomp-dual-authentication/readme.html +++ /dev/null @@ -1,51 +0,0 @@ - - - - - ActiveMQ Artemis Stomp Example - - - - - -

    Stomp Dual Authentication Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to configure 2-way SSL along with 2 different authentications mechanisms so that SSL and non-SSL clients can send and consume messages to/from ActiveMQ Artemis. - The non-SSL authentication mechanism simply uses username and password. The SSL authentication mechanism uses the client's certificate. The Stomp client uses SSL socket directly to send - a message. Then a JMS client will use a non-SSL connection to consume it.

    - -

    The various keystore files are generated using the following commands:

    - -

    - 

    -           
-keytool -genkey -keystore server-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Server, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA
-keytool -export -keystore server-side-keystore.jks -file server-side-cert.cer -storepass secureexample
-keytool -import -keystore client-side-truststore.jks -file server-side-cert.cer -storepass secureexample -keypass secureexample -noprompt
-keytool -genkey -keystore client-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Client, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA
-keytool -export -keystore client-side-keystore.jks -file client-side-cert.cer -storepass secureexample
-keytool -import -keystore server-side-truststore.jks -file client-side-cert.cer -storepass secureexample -keypass secureexample -noprompt
-           
-
    -

    - - diff --git a/examples/protocols/stomp/stomp-dual-authentication/readme.md b/examples/protocols/stomp/stomp-dual-authentication/readme.md new file mode 100644 index 0000000000..0da536a373 --- /dev/null +++ b/examples/protocols/stomp/stomp-dual-authentication/readme.md @@ -0,0 +1,14 @@ +# Stomp Dual Authentication Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure 2-way SSL along with 2 different authentications mechanisms so that SSL and non-SSL clients can send and consume messages to/from ActiveMQ Artemis. The non-SSL authentication mechanism simply uses username and password. The SSL authentication mechanism uses the client's certificate. The Stomp client uses SSL socket directly to send a message. Then a JMS client will use a non-SSL connection to consume it. + +The various keystore files are generated using the following commands: + +* `keytool -genkey -keystore server-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Server, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA` +* `keytool -export -keystore server-side-keystore.jks -file server-side-cert.cer -storepass secureexample` +* `keytool -import -keystore client-side-truststore.jks -file server-side-cert.cer -storepass secureexample -keypass secureexample -noprompt` +* `keytool -genkey -keystore client-side-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=ActiveMQ Artemis Client, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA` +* `keytool -export -keystore client-side-keystore.jks -file client-side-cert.cer -storepass secureexample` +* `keytool -import -keystore server-side-truststore.jks -file client-side-cert.cer -storepass secureexample -keypass secureexample -noprompt` \ No newline at end of file diff --git a/examples/protocols/stomp/stomp-dual-authentication/src/main/resources/activemq/server0/broker.xml b/examples/protocols/stomp/stomp-dual-authentication/src/main/resources/activemq/server0/broker.xml index 6b84763a77..cf0bb4c139 100644 --- a/examples/protocols/stomp/stomp-dual-authentication/src/main/resources/activemq/server0/broker.xml +++ b/examples/protocols/stomp/stomp-dual-authentication/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/messaging/bindings @@ -46,7 +44,7 @@ under the License. - +
    diff --git a/examples/protocols/stomp/stomp-embedded-interceptor/pom.xml b/examples/protocols/stomp/stomp-embedded-interceptor/pom.xml index 024bb60d1e..f3919ebc82 100644 --- a/examples/protocols/stomp/stomp-embedded-interceptor/pom.xml +++ b/examples/protocols/stomp/stomp-embedded-interceptor/pom.xml @@ -124,7 +124,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/stomp/stomp-embedded-interceptor/readme.html b/examples/protocols/stomp/stomp-embedded-interceptor/readme.html deleted file mode 100644 index 46cd264a83..0000000000 --- a/examples/protocols/stomp/stomp-embedded-interceptor/readme.html +++ /dev/null @@ -1,37 +0,0 @@ - - - - - ActiveMQ Artemis Stomp 1.1 Example - - - - - -

    Stomp 1.2 Example

    - - 
    To run the example, simply type mvn verify -Pexample from this directory.
    - -

    This example shows you how to configure ActiveMQ Artemis to intercept received Stomp messages.

    -

    The example will start a ActiveMQ Artemis server configured with Stomp and JMS.

    -

    The client will open a socket to initiate a Stomp 1.2 connection and then send one Stomp message (using TCP directly). - The interceptor will print each message received.

    - - diff --git a/examples/protocols/stomp/stomp-embedded-interceptor/readme.md b/examples/protocols/stomp/stomp-embedded-interceptor/readme.md new file mode 100644 index 0000000000..ade1b8e465 --- /dev/null +++ b/examples/protocols/stomp/stomp-embedded-interceptor/readme.md @@ -0,0 +1,7 @@ +# Stomp Embedded Interceptor Example + +To run the example, simply type **mvn verify -Pexample** from this directory. + +This example shows you how to configure ActiveMQ Artemis to intercept received Stomp messages. + +The client will open a socket to initiate a Stomp 1.2 connection and then send one Stomp message (using TCP directly). The interceptor will print each message received. \ No newline at end of file diff --git a/examples/protocols/stomp/stomp-embedded-interceptor/src/main/resources/activemq/server0/broker.xml b/examples/protocols/stomp/stomp-embedded-interceptor/src/main/resources/activemq/server0/broker.xml index 2b83a4a3d4..a4d8e6183b 100644 --- a/examples/protocols/stomp/stomp-embedded-interceptor/src/main/resources/activemq/server0/broker.xml +++ b/examples/protocols/stomp/stomp-embedded-interceptor/src/main/resources/activemq/server0/broker.xml @@ -16,10 +16,8 @@ software distributed under the License is distributed on an KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---> - - - +--> + ./data/bindings @@ -58,7 +56,7 @@ under the License. - +
    diff --git a/examples/protocols/stomp/stomp-jms/pom.xml b/examples/protocols/stomp/stomp-jms/pom.xml index 7faae2713e..a1541e9462 100644 --- a/examples/protocols/stomp/stomp-jms/pom.xml +++ b/examples/protocols/stomp/stomp-jms/pom.xml @@ -107,7 +107,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/stomp/stomp-jms/readme.html b/examples/protocols/stomp/stomp-jms/readme.html deleted file mode 100644 index efee00d9dd..0000000000 --- a/examples/protocols/stomp/stomp-jms/readme.html +++ /dev/null @@ -1,37 +0,0 @@ - - - - - ActiveMQ Artemis Stomp 1.1 Example - - - - - -

    Stomp 1.2 Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages using Stomp 1.2 protocol.

    -

    The example will start a ActiveMQ Artemis server configured with Stomp and JMS.

    -

    On this example we are using stomp-jms.

    - - diff --git a/examples/protocols/stomp/stomp-jms/readme.md b/examples/protocols/stomp/stomp-jms/readme.md new file mode 100644 index 0000000000..378f0b5654 --- /dev/null +++ b/examples/protocols/stomp/stomp-jms/readme.md @@ -0,0 +1,5 @@ +# Stomp 1.2 Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages using Stomp 1.2 protocol via the JMS API using the [stomp-jms](https://github.com/fusesource/stompjms) client. \ No newline at end of file diff --git a/examples/protocols/stomp/stomp-websockets/pom.xml b/examples/protocols/stomp/stomp-websockets/pom.xml index b437024420..2047eb4926 100644 --- a/examples/protocols/stomp/stomp-websockets/pom.xml +++ b/examples/protocols/stomp/stomp-websockets/pom.xml @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/stomp/stomp-websockets/readme.html b/examples/protocols/stomp/stomp-websockets/readme.html deleted file mode 100644 index 98a34ad297..0000000000 --- a/examples/protocols/stomp/stomp-websockets/readme.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - ActiveMQ Artemis Stomp WebSockets Example - - - - - -

    Stomp WebSockets Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - -

    This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages from modern web browser using Web Sockets.

    - -

    The example will start a ActiveMQ Artemis server configured with Stomp over Web Sockets and JMS. Web browsers clients and - Java application will exchange message using a JMS Topic.

    - 
    -<acceptor name="stomp-websocket">tcp://localhost:61614</acceptor>
    - -

    Example step-by-step

    - -

    To run the example, simply type mvn verify -Pexample from this directory

    - -

    To subscribe to the topic from your web browser, open the Chat Example or the JBoss AeroGear STOMP notifier Chat Example from another tab. - The chat example is preconfigured to connect to the ActiveMQ Artemis server with the URL ws://localhost:61613 and subscribe to the JMS Topic (through its core address - jms.topic.chat). -

    -

    You can open as many Web clients as you want and they will all exchange messages through the topic

    -

    If you run again the Java application (with ./build.sh), the web clients will also receive its message

    - -

    Documentation

    -

    A JavaScript library is used on the browser side to be able to use Stomp Over Web Sockets (please see its documentation - for a complete description).

    -

    The JBoss AeroGear STOMP notifier Chat Example is using the AeroGear Notifier which is a collection of adapters that provide a unified or similar API for interacting with different messaging services and protocols. The STOMP adapter is used for communicating with STOMP over WebSockets. See more at: JBoss aerogear-js

    - - diff --git a/examples/protocols/stomp/stomp-websockets/readme.md b/examples/protocols/stomp/stomp-websockets/readme.md new file mode 100644 index 0000000000..bb261225d8 --- /dev/null +++ b/examples/protocols/stomp/stomp-websockets/readme.md @@ -0,0 +1,17 @@ +# Stomp WebSockets Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages from modern web browser using Web Sockets. + +The example will start a ActiveMQ Artemis broker configured with Stomp over Web Sockets and JMS. Web browsers clients and Java application will exchange message using a JMS Topic. + +## Example step-by-step + +To subscribe to the topic from your web browser, open the [Chat Example](chat/index.html) from another tab. The chat example is preconfigured to connect to the ActiveMQ Artemis broker with the URL `ws://localhost:61613` and subscribe to the JMS Topic (through its core address `chat`). + +You can open as many Web clients as you want and they will all exchange messages through the topic + +## Documentation + +A JavaScript library is used on the browser side to be able to use Stomp Over Web Sockets (please see its [documentation](http://jmesnil.net/stomp-websocket/doc/) for a complete description). \ No newline at end of file diff --git a/examples/protocols/stomp/stomp/pom.xml b/examples/protocols/stomp/stomp/pom.xml index aa016fad38..1344cccfcf 100644 --- a/examples/protocols/stomp/stomp/pom.xml +++ b/examples/protocols/stomp/stomp/pom.xml @@ -29,7 +29,7 @@ under the License. stomp jar - ActiveMQ Artemis JMS Stomp Example + ActiveMQ Artemis Stomp 1.0 Example ${project.basedir}/../../../.. @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/stomp/stomp/readme.html b/examples/protocols/stomp/stomp/readme.html deleted file mode 100644 index 33182d0f83..0000000000 --- a/examples/protocols/stomp/stomp/readme.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - ActiveMQ Artemis Stomp Example - - - - - -

    Stomp Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages.

    -

    The example will start a ActiveMQ Artemis server configured with Stomp and JMS.

    -

    The client will open a socket to send one Stomp message (using TCP directly). - The client will then consume a message from a JMS Queue and check it is the message sent with Stomp.

    - - diff --git a/examples/protocols/stomp/stomp/readme.md b/examples/protocols/stomp/stomp/readme.md new file mode 100644 index 0000000000..18ced1eb83 --- /dev/null +++ b/examples/protocols/stomp/stomp/readme.md @@ -0,0 +1,7 @@ +# Stomp Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages. + +The client will open a socket to send one Stomp message (using TCP directly). The client will then consume a message from a queue and check it is the message sent with Stomp. \ No newline at end of file diff --git a/examples/protocols/stomp/stomp1.1/pom.xml b/examples/protocols/stomp/stomp1.1/pom.xml index 01f2e83489..0fa4d3308c 100644 --- a/examples/protocols/stomp/stomp1.1/pom.xml +++ b/examples/protocols/stomp/stomp1.1/pom.xml @@ -29,7 +29,7 @@ under the License. stomp1.1 jar - ActiveMQ Artemis JMS Stomp Example + ActiveMQ Artemis Stomp 1.1 Example ${project.basedir}/../../../.. @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/stomp/stomp1.1/readme.html b/examples/protocols/stomp/stomp1.1/readme.html deleted file mode 100644 index 308dcbed52..0000000000 --- a/examples/protocols/stomp/stomp1.1/readme.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - ActiveMQ Artemis Stomp 1.1 Example - - - - - -

    Stomp 1.1 Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages using Stomp 1.1 protocol.

    -

    The example will start a ActiveMQ Artemis server configured with Stomp and JMS.

    -

    The client will open a socket to initiate a Stomp 1.1 connection and then send one Stomp message (using TCP directly). - The client will then consume a message from a JMS Queue and check it is the message sent with Stomp.

    - - diff --git a/examples/protocols/stomp/stomp1.1/readme.md b/examples/protocols/stomp/stomp1.1/readme.md new file mode 100644 index 0000000000..37d23af374 --- /dev/null +++ b/examples/protocols/stomp/stomp1.1/readme.md @@ -0,0 +1,7 @@ +# Stomp 1.1 Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages using Stomp 1.1 protocol. + +The client will open a socket to initiate a Stomp 1.1 connection and then send one Stomp message (using TCP directly). The client will then consume a message from a queue and check it is the message sent with Stomp. \ No newline at end of file diff --git a/examples/protocols/stomp/stomp1.2/pom.xml b/examples/protocols/stomp/stomp1.2/pom.xml index 3f7321db09..de6cbf817d 100644 --- a/examples/protocols/stomp/stomp1.2/pom.xml +++ b/examples/protocols/stomp/stomp1.2/pom.xml @@ -29,7 +29,7 @@ under the License. stomp1.2 jar - ActiveMQ Artemis JMS Stomp 1.2 Example + ActiveMQ Artemis Stomp 1.2 Example ${project.basedir}/../../../.. @@ -102,7 +102,23 @@ under the License. + + org.apache.maven.plugins + maven-clean-plugin + - - + + + release + + + + com.vladsch.flexmark + markdown-page-generator-plugin + + + + + + \ No newline at end of file diff --git a/examples/protocols/stomp/stomp1.2/readme.html b/examples/protocols/stomp/stomp1.2/readme.html deleted file mode 100644 index 2164c0ec77..0000000000 --- a/examples/protocols/stomp/stomp1.2/readme.html +++ /dev/null @@ -1,38 +0,0 @@ - - - - - ActiveMQ Artemis Stomp 1.1 Example - - - - - -

    Stomp 1.2 Example

    - - 
    To run the example, simply type mvn verify from this directory, 
    or mvn -PnoServer verify if you want to start and create the server manually.
    - - -

    This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages using Stomp 1.2 protocol.

    -

    The example will start a ActiveMQ Artemis server configured with Stomp and JMS.

    -

    The client will open a socket to initiate a Stomp 1.2 connection and then send one Stomp message (using TCP directly). - The client will then consume a message from a JMS Queue and check it is the message sent with Stomp.

    - - diff --git a/examples/protocols/stomp/stomp1.2/readme.md b/examples/protocols/stomp/stomp1.2/readme.md new file mode 100644 index 0000000000..36c2801c8e --- /dev/null +++ b/examples/protocols/stomp/stomp1.2/readme.md @@ -0,0 +1,7 @@ +# Stomp 1.2 Example + +To run the example, simply type **mvn verify** from this directory, or **mvn -PnoServer verify** if you want to start and create the broker manually. + +This example shows you how to configure ActiveMQ Artemis to send and receive Stomp messages using Stomp 1.2 protocol. + +The client will open a socket to initiate a Stomp 1.2 connection and then send one Stomp message (using TCP directly). The client will then consume a message from a queue and check it is the message sent with Stomp. \ No newline at end of file diff --git a/pom.xml b/pom.xml index 9fd45f3983..885b97049e 100644 --- a/pom.xml +++ b/pom.xml @@ -1565,6 +1565,7 @@ ${activemq.basedir}/ratReport.txt ${skipLicenseCheck} + **/footer.html **/*.txt **/*.md etc/ide-settings/**