SupportConsoleDevelopersStart a trialContact

Chapter 4. Getting Started

This chapter introduces you to AMQ Broker by showing you how to do the following basic but important tasks:

  1. Create a broker instance.
  2. Start and Stop the broker instance.
  3. Run the examples included with the installation of AMQ Broker.

4.1. Creating a Broker Instance

A broker instance is a directory containing all the configuration and runtime data, such as logs and data files. The runtime data is associated with a unique broker process.

Creating a Broker Instance on Linux

Procedure

  1. Create a directory location for the broker instance, for example /var/opt/amq-broker, and assign the user you created during installation as its owner. 

    $ sudo mkdir /var/opt/amq-broker
$ sudo chown -R amq-broker:amq-broker /var/opt/amq-broker

  2. Move to the new directory and use the artemis create command to create a broker. For example, to create the broker instance mybroker under the /var/opt/amq-broker directory, run the following commands. Note that in the example below the user that was created during installation is the one to run the create command. 

    $ su - amq-broker
$ cd /var/opt/amq-broker
$ INSTALL_DIR/bin/artemis create mybroker

Creating a Broker Instance on Windows

Procedure

  1. Using Windows Explorer create a new folder to serve as the location for the broker instance.

  2. Open a Windows command prompt from the location you just created and use the artemis.cmd create command to create a broker. For example, to create the broker instance mybroker, run the following command. 

    > INSTALL_DIR\bin\artemis.cmd create mybroker

Responding to Questions Asked During the Creation Process

The create command will ask a series of questions in order to configure the broker instance. It will prompt for mandatory property value only. For the full list of properties available when creating an instance, run the artemis help create command.

The following example shows the command-line interactive process when creating a broker instance. 

Creating ActiveMQ Artemis instance at: /var/opt/amq-broker/mybroker

--user: is mandatory with this configuration:
Please provide the default username:
<username>

--password: is mandatory with this configuration:
Please provide the default password:
<password>

--role: is mandatory with this configuration:
Please provide the default role:
amq

--allow-anonymous | --require-login: is mandatory with this configuration:
Allow anonymous access? (Y/N):
Y

Auto tuning journal ...
done! Your system can make 19.23 writes per millisecond, your journal-buffer-timeout will be 52000

You can now start the broker by executing:

"/var/opt/amq-broker/mybroker/bin/artemis" run

Or you can run the broker in the background using:

"/var/opt/amq-broker/mybroker/bin/artemis-service" start

Broker Instance Directory Contents

The process creates a top level directory and a number of subdirectories containing configuration and runtime data. In the examples above, the top level directory is named mybroker. The documentation refers to the top level location as the BROKER_INSTANCE_DIR. The table below details its structure and contents.

Table 4.1. Contents of a broker instance directory
If you want to find…​Look here…​

Scripts that launch and manage the instance

BROKER_INSTANCE_DIR/bin

Configuration files

BROKER_INSTANCE_DIR/etc

Storage for persistent messages

BROKER_INSTANCE_DIR/data

Log files

BROKER_INSTANCE_DIR/log

Temporary files

BROKER_INSTANCE_DIR/tmp

4.2. Starting a Broker Instance

Once the broker is created, use the artemis script in the BROKER_INSTANCE_DIR/bin directory to start it. For instance, to start a broker created at /var/opt/amq-broker/mybroker, use the following command as the user you created during installation. In the example below, the user amq-broker starts the broker. 

$ su - amq-broker
$ /var/opt/amq-broker/mybroker/bin/artemis run

The artemis command has other other options available. Provide the help parameter to learn more. 

$ /var/opt/amq-broker/mybroker/bin/artemis help

Once started, the broker will produce output similar to the following. 

 ____          _   _   _       _        _         __  __  ___  _____
|  _ \ ___  __| | | | | | __ _| |_     / \       |  \/  |/ _ \|___  |
| |_) / _ \/ _` | | |_| |/ _` | __|   / _ \ _____| |\/| | | | |  / /
|  _ <  __/ (_| | |  _  | (_| | |_   / ___ \_____| |  | | |_| | / /
|_| \_\___|\__,_| |_| |_|\__,_|\__| /_/   \_\    |_|  |_|\__\_\/_/

Red Hat AMQ7 7.0.0-redhat-1


14:46:15,468 INFO  [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server
14:46:15,479 INFO  [org.apache.activemq.artemis.core.server] AMQ221000: live Message Broker is starting with configuration Broker Configuration (clustered=false,journalDirectory=./data/journal,bindingsDirectory=./data/bindings,largeMessagesDirectory=./data/large-messages,pagingDirectory=./data/paging)
14:46:15,497 INFO  [org.apache.activemq.artemis.core.server] AMQ221012: Using AIO Journal
14:46:15,525 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-server]. Adding protocol support for: CORE
14:46:15,527 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-amqp-protocol]. Adding protocol support for: AMQP
14:46:15,527 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-hornetq-protocol]. Adding protocol support for: HORNETQ
14:46:15,528 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-mqtt-protocol]. Adding protocol support for: MQTT
14:46:15,529 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-openwire-protocol]. Adding protocol support for: OPENWIRE
14:46:15,530 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-stomp-protocol]. Adding protocol support for: STOMP
14:46:15,825 INFO  [org.apache.activemq.artemis.core.server] AMQ221052: trying to deploy topic jms.topic.myTopic
14:46:15,828 INFO  [org.apache.activemq.artemis.core.server] AMQ221003: Trying to deploy queue jms.queue.DLQ
14:46:15,833 INFO  [org.apache.activemq.artemis.core.server] AMQ221003: Trying to deploy queue jms.queue.ExpiryQueue
14:46:16,062 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:61616 for protocols [CORE,MQTT,AMQP,HORNETQ,STOMP,OPENWIRE]
14:46:16,065 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:5445 for protocols [HORNETQ,STOMP]
14:46:16,069 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:5672 for protocols [AMQP]
14:46:16,071 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:1883 for protocols [MQTT]
14:46:16,073 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:61613 for protocols [STOMP]
14:46:16,073 INFO  [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live
14:46:16,073 INFO  [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 1.2.0.amq-700006 [amq, nodeID=71ecbb84-176e-11e6-be67-54ee7531eccb]
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
INFO  | main | Initialized artemis-plugin plugin
14:46:17,116 INFO  [org.apache.activemq.artemis] AMQ241001: HTTP Server started at http://localhost:8161
14:46:17,116 INFO  [org.apache.activemq.artemis] AMQ241002: Artemis Jolokia REST API available at http://localhost:8161/jolokia

4.3. Starting a Broker as a Windows Service

If the broker is installed on Windows, you can choose to run it as a service.

Procedure

The steps below require that you open a command prompt to enter the commands.

  1. Install the broker as a service with the following command: 

    BROKER_INSTANCE_DIR\bin\artemis-service.exe install

  2. Start the service using the following command. 

    BROKER_INSTANCE_DIR\bin\artemis-service.exe start

  3. Issue a stop command to stop the service. 

    BROKER_INSTANCE_DIR\bin\artemis-service.exe stop

  4. (Optional) Uninstall the service when needed. 

    BROKER_INSTANCE_DIR\bin\artemis-service.exe uninstall

4.4. Running the Included Examples

AMQ Broker ships with many example programs that highlight various basic and advanced features of the product. They can be found under INSTALL_DIR/examples.

The examples require a supported release of the Java Development Kit (JDK) and Maven version 3.2 or greater to build and execute. Consult Supported Configurations for details about JDK support. The next section shows you how to install and configure Maven, enabling you to run the examples.

Downloading Maven and the AMQ Repository

Running the examples requires that both Maven and the Red Hat JBoss AMQ Broker Maven repository are installed locally. The steps below show you how to download, install, and configure both. For more information about Maven refer to the appendix.

Downloading and Installing Maven

  1. Go to Apache Maven Project - Download Maven and download the latest distribution for your operating system.
  2. See the Maven documentation for information on how to download and install Apache Maven for your operating system.

Downloading and Installing the AMQ Maven Repository

  1. Open a browser and log in to the Red Hat Customer Portal at https://access.redhat.com.
  2. Click Downloads.
  3. Find Red Hat JBoss AMQ in the Product Downloads list.
  4. Select Download Latest Broker from the drop-down list located on the same row to go to the Software Downloads page for AMQ Broker.
  5. From the Software Downloads page, select the correct AMQ Broker version from the Version drop-down menu.
  6. Click the Download link for the Maven Repository to download a .zip file containing the repository.

  7. Unzip the file on the local file system into a directory of your choosing.

    This creates a new directory, which contains the Maven repository in a subdirectory named maven-repository/.

Important

If you want to continue to use an older local repository, you must configure it separately in the Maven settings.xml configuration file. Each local repository must be configured within its own <repository> element.

Important

Remove the cached repository/ subdirectory located under the .m2/ directory before attempting to use a new Maven repository.

Configuring the Maven Settings File

  1. Locate the Maven settings.xml file for your operating system. It is usually located in the ${user.home}/.m2/ directory.

    • For Linux or Mac, this is ~/.m2/
    • For Windows, this is \Documents and Settings\.m2\ or \Users\.m2\
  2. (Optional) 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.

  3. Copy the following XML into the <profiles> element of the settings.xml file. 

    <!-- 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>
      <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>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>
</profile>
  4. Replace JBOSS_AMQ_REPOSITORY_PATH within the url element with the location of the maven repository on the local file system. If you followed the installation steps above, the location should end with /maven-repository.

  5. Copy the following XML into the <activeProfiles> element of the settings.xml file. 

    <activeProfile>jboss-amq-maven-repository</activeProfile>
  6. (Optional) If you copied the default settings.xml from your Maven installation, uncomment the <active-profiles> section if it was commented out by default.
Important

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

To resolve the issue, delete the cached version of your local repository to force a download of the latest Maven artifacts. The cached repository is located here: ${user.home}/.m2/repository/

Several of the examples use UDP clustering, which may not work in your environment when you first attempt to run them. On Linux, you can issue a command to provide the appropriate environment. The command below redirects any traffic directed to 224.0.0.0 to the loopback interface, allowing examples that use UDP clustering to run successfully. 

sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev lo

On Mac OS X, the command is slightly different. 

sudo route add 224.0.0.0 127.0.0.1 -netmask 240.0.0.0

Running the queue Example to Test Your Installation

To run any example, change directories to the desired example and type mvn clean verify. You can also use the profile -P examples to run multiple examples under any example directory tree. For details on each example, please read the readme.html file in each example directory. An excellent example to use as a "sanity test" of your broker installation is the queue example. The example creates a producer to send a message to the broker and a consumer that receives the same message.

Procedure

  • To build and run the example, navigate to the INSTALL_DIR/examples/features/standard/queue directory. 

    $ cd INSTALL_DIR/examples/features/standard/queue

  • Run the mvn clean verify command. 

    $ mvn clean verify

Maven will start the broker and run the example. Once completed the output should look something like the below example. Note that the example may take a long time to complete the first time since Maven will download any missing dependencies required to run the example. 

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building ActiveMQ Artemis JMS Queue Example 1.2.0.amq-700
[INFO] ------------------------------------------------------------------------
 ...
server-out:11:30:45,534 INFO  [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 1.2.0.amq-700 [0.0.0.0, nodeID=e748cdbd-232c-11e6-b145-54ee7531eccb]
[INFO] Server started
[INFO]
[INFO] --- artemis-maven-plugin:1.2.0.amq-700:runClient (runClient) @ queue ---
Sent message: This is a text message
server-out:11:30:46,545 INFO  [org.apache.activemq.artemis.core.server] AMQ221003: Trying to deploy queue jms.queue.exampleQueue
Received message: This is a text message
[INFO]
[INFO] --- artemis-maven-plugin:1.2.0.amq-700:cli (stop) @ queue ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6.368 s
[INFO] Finished at: 2016-05-26T11:30:47+01:00
[INFO] Final Memory: 44M/553M
[INFO] ------------------------------------------------------------------------
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.