Red Hat SummitCe contenu n'est pas disponible dans la langue sélectionnée.
Chapter 4. Getting Started
This chapter introduces you to AMQ Broker by showing you how to perform the following basic but important tasks:
- Create a broker instance.
- Start a broker instance.
- Stop a 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
$ sudo mkdir /var/opt/amq-broker $ sudo chown -R amq-broker:amq-broker /var/opt/amq-brokerCopy to Clipboard Copied! Toggle word wrap Toggle overflow Move to the new directory and use the
artemis createcommand to create a broker. For example, to create the broker instancemybrokerunder the/var/opt/amq-brokerdirectory, run the following commands. Note that in the following example the user that was created during installation is the one to run thecreatecommand:su - amq-broker cd /var/opt/amq-broker INSTALL_DIR/bin/artemis create mybroker
$ su - amq-broker $ cd /var/opt/amq-broker $ INSTALL_DIR/bin/artemis create mybrokerCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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 createcommand to create a broker. For example, to create the broker instancemybroker, run the following command:> INSTALL_DIR\bin\artemis.cmd create mybroker
> INSTALL_DIR\bin\artemis.cmd create mybrokerCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Responding to Questions Asked During the Creation Process
The create command will ask a series of questions 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.
Broker Instance Directory Contents
The process creates a top level directory and several subdirectories containing configuration and runtime data. In the preceding examples, 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
After 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 following example, the user amq-broker starts the broker:
su - amq-broker /var/opt/amq-broker/mybroker/bin/artemis run
$ 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
$ /var/opt/amq-broker/mybroker/bin/artemis helpWhen started, the broker will produce output similar to the following:
4.2.1. Starting a Broker as a Linux Service
If the broker is installed on Linux, you can run it as a service.
Procedure
-
Create a new
amq-broker.servicefile in the/etc/systemd/system/directory. Copy the following text into the file.
Modify the path and user fields according to the information provided during the broker instance creation. In the example below, the user
amq-brokerstarts the broker service installed under the/var/opt/amq-broker/mybroker/directory.Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Open a terminal.
Enable the broker service using the following command:
sudo systemctl enable amq-broker
sudo systemctl enable amq-brokerCopy to Clipboard Copied! Toggle word wrap Toggle overflow Run the broker service using the following command:
sudo systemctl start amq-broker
sudo systemctl start amq-brokerCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.2.2. Starting a Broker as a Windows Service
If the broker is installed on Windows, you can run it as a service.
Procedure
The following steps 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
BROKER_INSTANCE_DIR\bin\artemis-service.exe installCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the service by using the following command:
BROKER_INSTANCE_DIR\bin\artemis-service.exe start
BROKER_INSTANCE_DIR\bin\artemis-service.exe startCopy to Clipboard Copied! Toggle word wrap Toggle overflow (Optional) Uninstall the service:
BROKER_INSTANCE_DIR\bin\artemis-service.exe uninstall
BROKER_INSTANCE_DIR\bin\artemis-service.exe uninstallCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.3. Stopping a Broker Instance
You can stop the broker manually by issuing the stop command. Immediately after the command is entered, all connections to the broker are forcefully stopped and the shutdown process begins.
Procedure
Stop the broker.
If you are running the broker on Linux, issue the following command:
BROKER_INSTANCE_DIR\bin\artemis stop
BROKER_INSTANCE_DIR\bin\artemis stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow If you are running the broker on Windows as a service, issue the following command:
BROKER_INSTANCE_DIR\bin\artemis-service.exe stop
BROKER_INSTANCE_DIR\bin\artemis-service.exe stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.3.1. Stopping a Broker Instance Gracefully
A manual shutdown forcefully disconnects all clients after a stop command is entered. As an alternative, configure the broker to shutdown gracefully by using the graceful-shutdown-enabled configuration element.
When graceful-shutdown-enabled is set to true, no new client connections are allowed after a stop command is entered. However, existing connections are allowed to close on the client-side before the shutdown process is started. The default value for graceful-shutdown-enabled is false.
Use the graceful-shutdown-timeout configuration element to set a length of time, in milliseconds, for clients to disconnect before connections are forcefully closed from the broker side. After all connections are closed, the shutdown process is started. One advantage of using graceful-shutdown-timeout is that it prevents client connections from delaying a shutdown. The default value for graceful-shutdown-timeout is -1, meaning the broker waits indefinitely for clients to disconnect.
The following procedure demonstrates how to configure a graceful shutdown that uses a timeout.
Procedure
-
Open the configuration file
BROKER_INSTANCE_DIR\etc\broker.xml. Add the
graceful-shutdown-enabledconfiguration element and set the value totrue.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add the
graceful-shutdown-timeoutconfiguration element and set a value for the timeout in milliseconds. In the following example, client connections are forcefully closed 30 seconds (30000milliseconds) after the stop command is issued.Copy to Clipboard Copied! Toggle word wrap Toggle overflow
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 run. 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 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.
Install Maven for your operating system.
For more information, see Installing Apache Maven.
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 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.xmlfile 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.xmlfile in${user.home}/.m2/, there is a default version located in theconf/directory of your Maven installation. Copy the defaultsettings.xmlfile into the${user.home}/.m2/directory. Copy the following XML into the
<profiles>element of thesettings.xmlfile.Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Replace JBOSS_AMQ_REPOSITORY_PATH within the
urlelement 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.xmlfile.<activeProfile>jboss-amq-maven-repository</activeProfile>
<activeProfile>jboss-amq-maven-repository</activeProfile>Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
(Optional) If you copied the default
settings.xmlfrom 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 following command 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
sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev loRunning 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, 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/queuedirectory:cd INSTALL_DIR/examples/features/standard/queue
$ cd INSTALL_DIR/examples/features/standard/queueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Run the
mvn clean verifycommand:mvn clean verify
$ mvn clean verifyCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Maven will start the broker and run the example. When completed the output should look something like the following example. Note that the example may take a long time to run the first time since Maven will download any missing dependencies required to run the example.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}