include::../shared-doc/attributes.adoc[]

= helloworld-jms: Helloworld JMS Example
:author: Weston Price
:level: Intermediate
:technologies: JMS

[abstract]
The `helloworld-jms` quickstart demonstrates the use of external JMS clients with {productName}.

:standalone-server-type: full
:archiveType: jar
:includes-cli-scripts:
:restoreScriptName: remove-jms.cli
:app-user-groups: guest

== What is it?

The `helloworld-jms` quickstart demonstrates the use of external JMS clients with {productNameFull}.

It contains the following:

. A message producer that sends messages to a JMS destination deployed to a {productName} server.

. A message consumer that receives message from a JMS destination deployed to a {productName} server.

// System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]
// Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
// Add the Authorized Application User
include::../shared-doc/add-application-user.adoc[leveloffset=+1]
// Back Up the {productName} Standalone Server Configuration
include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1]
// Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]

[[configure_the_server]]
== Configure the Server

You configure the JMS `test` queue by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-jms.cli` script provided in the root directory of this quickstart.

. Before you begin, make sure you do the following:

* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above.
* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone full profile] as described above.

. Review the `configure-jms.cli` file in the root of this quickstart directory. This script adds the `test` queue to the `messaging` subsystem in the server configuration file.
. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing __{jbossHomeName}__ with the path to your server:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-jms.cli
----
+
NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script.

. You should see the following result when you run the script:
+
[source,options="nowrap"]
----
The batch executed successfully
----

. Stop the {productName} server.

== Review the Modified Server Configuration

After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file and review the changes.

The following `testQueue` jms-queue was configured in the default server configuration of the `messaging-activemq` subsystem.

[source,xml,options="nowrap"]
----
<jms-queue name="testQueue" entries="queue/test java:jboss/exported/jms/queue/test"/>
----


== Build and Execute the Quickstart

. xref:start_the_eap_standalone_server[Start the {productName} server with the standalone full profile] as described above.

. Open a terminal and navigate to the root of the helloworld-jms quickstart directory:
+
[source,options="nowrap"]
----
$ cd PATH_TO_QUICKSTARTS/helloworld-jms
----

. Type the following command to compile and execute the quickstart:
+
[source,options="nowrap"]
----
$ mvn clean compile exec:java
----

[NOTE]
====
If you execute this command multiple times, you may see the following warning and exception, followed by a stacktrace. This is caused by a bug in Artemis that has been fixed, but not yet released. For details, see https://issues.apache.org/jira/browse/ARTEMIS-158. You can ignore this warning._

[source,options="nowrap"]
----
WARN: AMQ212007: connector.create or connectorFactory.createConnector should never throw an exception, implementation is badly behaved, but we will deal with it anyway.
java.lang.IllegalArgumentException: port out of range:-1
----
====

== Investigate the Console Output

If the Maven command is successful, with the default configuration you will see output similar to this:

[source,options="nowrap"]
----
timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
INFO: Attempting to acquire connection factory "jms/RemoteConnectionFactory"
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.
timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
INFO: Found connection factory "jms/RemoteConnectionFactory" in JNDI
timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
INFO: Attempting to acquire destination "jms/queue/test"
timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
INFO: Found destination "jms/queue/test" in JNDI
timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
INFO: Sending 1 messages with content: Hello, World!
timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main
INFO: Received message with content Hello, World!
----

== Optional Properties

The example provides for a certain amount of customization for the `mvn:exec` plug-in using the system properties.

[cols="20%,30%,50%",options="headers"]
|===
| Property
| Default value
| Description

| username
| quickstartUser
| This `username` is used for both the JMS connection and the JNDI look up. Instructions to set up the quickstart application user can be found here: link:{addApplicationUserDocUrl}[Add an Application User].

| password
| quickstartPwd1!
| This `password` is used for both the JMS connection and the JNDI look up. Instructions to set up the quickstart application user can be found here: link:{addApplicationUserDocUrl}[Add an Application User]

| connection.factory
| jms/RemoteConnectionFactory
| The name of the JMS `ConnectionFactory` you want to use.

| destination
| jms/queue/test
| The name of the JMS `Destination` you want to use.

| message.count
| 1
| The number of JMS messages you want to produce and consume.

| message.content
| "Hello, World!"
| The content of the JMS `TextMessage`.

| java.naming.provider.url
| "localhost"
| This property allows configuration of the JNDI directory used to look up the JMS destination. This is useful when the client resides on another host.
|===

// Restore the {productName} Standalone Server Configuration
include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1]

// Additional information about this script
This script removes the `test` queue from the `messaging` subsystem in the server configuration. You should see the following result when you run the script.

[source,options="nowrap"]
----
The batch executed successfully
----

// Restore the {productName} Standalone Server Configuration Manually
include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2]
// Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse
include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1]

// Additional JBoss Developer Studio instructions
This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

. Make sure you xref:add_the_application_user[add the authorized application user] as described above.
. Configure and start the {productName} server in Red Hat JBoss Developer Studio:
** Define a server runtime environment that uses the `standalone-full.xml` configuration file.
** Start the server defined in the previous step.
. Outside of JBoss Developer Studio, configure the JMS `test` queue by running the JBoss CLI commands as described above under xref:configure_the_server[Configure the Server].
. In JBoss Developer Studio, right-click on the *{artifactId}* project and choose *Run As* -> *Java Application*. In the *Select Java Application* window, choose *HellowWorldJMSClient - org.jboss.as.quickstarts.jms* and click *OK*. The client output displays in the *Console* window.
The output messages appear in the *Console* window.
. Make sure you xref:restore_the_server_configuration[restore the {productName} server configuration] when you have completed testing this quickstart.

// Debug the Application
include::../shared-doc/debug-the-application.adoc[leveloffset=+1]
