Chapter 5. Running the AMQ Broker examples

AMQ Broker ships with many example programs that demonstrate basic and advanced features of the product. You can run these examples to become familiar with the capabilities of AMQ Broker.

To run the AMQ Broker examples, you must first set up your machine by installing and configuring Apache Maven and the AMQ Maven repository. Then, you use Maven to run the AMQ Broker example programs.

5.1. Setting up your machine to run the AMQ Broker examples

Before you can run the included AMQ Broker example programs, you must first download and install Maven and the AMQ Maven repository, and configure the Maven settings file.

5.1.1. Downloading and installing Maven

Maven is required to run the AMQ Broker examples.

Procedure

  1. Go to the Apache Maven Download page and download the latest distribution for your operating system.
  2. Install Maven for your operating system.

    For more information, see Installing Apache Maven.

Additional resources

5.1.2. Downloading and installing the AMQ Maven repository

After Maven is installed on your machine, you download and install the AMQ Maven repository. This repository is available on the Red Hat Customer Portal.

  1. In a web browser, navigate to https://access.redhat.com/downloads/ and log in.

    The Product Downloads page is displayed.

  2. In the Integration and Automation section, click the Red Hat AMQ Broker link.

    The Software Downloads page is displayed.

  3. Select the desired AMQ Broker version from the Version drop-down menu.
  4. On the Releases tab, click the Download link for the AMQ Broker Maven Repository.

    The AMQ Maven repository file is downloaded as a zip file.

  5. On your machine, unzip the AMQ repository file into a directory of your choosing.

    A new directory is created on your machine, which contains the Maven repository in a subdirectory named maven-repository/.

5.1.3. Configuring the Maven settings file

After downloading and installing the AMQ Maven repository, you must add the repository to the Maven settings file.

Procedure

  1. Open the Maven settings.xml file.

    The settings.xml file is typically located in the ${user.home}/.m2/ directory.

    • For Linux, this is ~/.m2/
    • For Windows, this is \Documents and Settings\.m2\ or \Users\.m2\

    If you do not find a settings.xml file in ${user.home}/.m2/, there is a default version located in the conf/ directory of your Maven installation. Copy the default settings.xml file into the ${user.home}/.m2/ directory.

  2. In the <profiles> element, add a profile for the AMQ Maven repository.

    <!-- Configure the JBoss AMQ Maven repository -->
    <profile>
      <id>jboss-amq-maven-repository</id>
      <repositories>
        <repository>
          <id>jboss-amq-maven-repository</id>
          <url>file://<JBoss-AMQ-repository-path></url>  1
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>jboss-amq-maven-repository</id>
          <url>file://<JBoss-AMQ-repository-path></url>  2
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
    1 2
    Replace <JBoss-AMQ-repository-path> with the location of the Maven repository that you installed. Typically, this location ends with /maven-repository. For example:
    <url>file:///path/to/repo/amq-broker-7.2.0-maven-repository/maven-repository</url>
  3. In the <activeProfiles> element, set the AMQ Maven repository to be active:

    <activeProfiles>
      <activeProfile>jboss-amq-maven-repository</activeProfile>
    ...
    </activeProfiles>
  4. If you copied the default settings.xml from your Maven installation, uncomment the <active-profiles> section if it was commented out by default.
  5. Save and close settings.xml.
  6. Remove the cached ${user.home}/.m2/repository/ directory.

    If your Maven repository contains outdated artifacts, you may encounter one of the following Maven error messages when you build or deploy your project:

    • Missing artifact <artifact-name>
    • [ERROR] Failed to execute goal on project <project-name>; Could not resolve dependencies for <project-name>

5.2. AMQ Broker example programs

AMQ Broker ships with more than 90 example programs that demonstrate how to use AMQ Broker features and the supported messaging protocols.

The example programs are located in <install_dir>/examples, and include the following:

  • Features

    Broker-specific features such as:

    • Clustered - examples showing load balancing and distribution capabilities
    • HA - examples showing failover and reconnection capabilities
    • Perf - examples allowing you to run a few performance tests on the server
    • Standard - examples demonstrating various broker features
    • Sub-modules - examples of integrated external modules
  • Protocols

    Examples for each of the supported messaging protocols:

    • AMQP
    • MQTT
    • OpenWire
    • STOMP

Additional resources

  • For a description of each example program, see Examples in the Apache Artemis documentation.

5.3. Running an AMQ Broker example program

AMQ Broker ships with many example programs that demonstrate basic and advanced features of the product. You use Maven to run these programs.

Prerequisites

Procedure

  1. Navigate to the directory of the example you want to run.

    The example programs are located in <install_dir>/examples. For example:

    $ cd <install_dir>/examples/features/standard/queue
  2. Use the mvn clean verify command to run the example program.

    Maven starts the broker and runs the example program. The first time you run the example program, Maven downloads any missing dependencies, which may take a while to run.

    In this case, the queue example program is run, which creates a producer, sends a test message, and then creates a consumer that receives the message:

    $ mvn clean verify
    [INFO] Scanning for projects...
    [INFO]
    [INFO] -------------< org.apache.activemq.examples.broker:queue >--------------
    [INFO] Building ActiveMQ Artemis JMS Queue Example 2.6.1.amq-720004-redhat-1
    [INFO] --------------------------------[ jar ]---------------------------------
    ...
    server-out:2018-12-05 16:37:57,023 INFO  [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 2.6.1.amq-720004-redhat-1 [0.0.0.0, nodeID=06f529d3-f8d6-11e8-9bea-0800271b03bd]
    [INFO] Server started
    [INFO]
    [INFO] --- artemis-maven-plugin:2.6.1.amq-720004-redhat-1:runClient (runClient) @ queue ---
    Sent message: This is a text message
    Received message: This is a text message
    [INFO]
    [INFO] --- artemis-maven-plugin:2.6.1.amq-720004-redhat-1:cli (stop) @ queue ---
    server-out:2018-12-05 16:37:59,519 INFO  [org.apache.activemq.artemis.core.server] AMQ221002: Apache ActiveMQ Artemis Message Broker version 2.6.1.amq-720004-redhat-1 [06f529d3-f8d6-11e8-9bea-0800271b03bd] stopped, uptime 3.734 seconds
    server-out:Server stopped!
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  48.681 s
    [INFO] Finished at: 2018-12-05T16:37:59-05:00
    [INFO] ------------------------------------------------------------------------
    Note

    Some of the example programs use UDP clustering, and may not work in your environment by default. To run these examples successfully, redirect traffic directed to 224.0.0.0 to the loopback interface:

    $ sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev lo