Chapter 4. Getting Started
This chapter introduces you to AMQ Broker by showing you how to do the following basic but important tasks:
- Create a broker instance.
- Start and Stop the broker instance.
- 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
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
Move to the new directory and use the
artemis create
command to create a broker. For example, to create the broker instancemybroker
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 thecreate
command.$ su - amq-broker $ cd /var/opt/amq-broker $ INSTALL_DIR/bin/artemis create mybroker
Creating a Broker Instance on Windows
Procedure
- Using Windows Explorer create a new folder to serve as the location for the broker instance.
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 instancemybroker
, 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.
If you want to find… | Look here… |
---|---|
Scripts that launch and manage the instance |
|
Configuration files |
|
Storage for persistent messages |
|
Log files |
|
Temporary files |
|
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.
Install the broker as a service with the following command:
BROKER_INSTANCE_DIR\bin\artemis-service.exe install
Start the service using the following command.
BROKER_INSTANCE_DIR\bin\artemis-service.exe start
Issue a stop command to stop the service.
BROKER_INSTANCE_DIR\bin\artemis-service.exe stop
(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
- Go to Apache Maven Project - Download Maven and download the latest distribution for your operating system.
- 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
- Open a browser and log in to the Red Hat Customer Portal at https://access.redhat.com.
- Click Downloads.
- Find Red Hat JBoss AMQ in the Product Downloads list.
- Select Download Latest Broker from the drop-down list located on the same row to go to the Software Downloads page for AMQ Broker.
- From the Software Downloads page, select the correct AMQ Broker version from the Version drop-down menu.
- Click the Download link for the Maven Repository to download a .zip file containing the repository.
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/
.
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.
Remove the cached repository/
subdirectory located under the .m2/
directory before attempting to use a new Maven repository.
Configuring the Maven Settings File
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\
-
For Linux or Mac, this is
-
(Optional) If you do not find a
settings.xml
file in${user.home}/.m2/
, there is a default version located in theconf/
directory of your Maven installation. Copy the defaultsettings.xml
file into the${user.home}/.m2/
directory. Copy the following XML into the
<profiles>
element of thesettings.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>
-
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
. Copy the following XML into the
<activeProfiles>
element of thesettings.xml
file.<activeProfile>jboss-amq-maven-repository</activeProfile>
-
(Optional) If you copied the default
settings.xml
from your Maven installation, uncomment the<active-profiles>
section if it was commented out by default.
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] ------------------------------------------------------------------------