= helloworld-mdb-propertysubstitution: MDB (Message-Driven Bean) Using Property Substitution
:author: Serge Pagop, Andy Taylor, Jeff Mesnil
:productName: WildFly
:productNameFull: WildFly Application Server
:jbossHomeName: WILDFLY_HOME
:productVersion: 12
:buildRequirements: Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later
include::../shared-doc/attributes.adoc[]

:level: Intermediate
:technologies: JMS, EJB, MDB
:source: {githubRepoUrl}

[abstract]
The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of JMS and EJB MDB, enabling property substitution with annotations.

:standalone-server-type: full
:archiveType: war
:includes-cli-scripts:

== What is it?

The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of JMS and EJB Message-Driven Bean in {productNameFull}.

It is based on the link:../helloworld-mdb/README{outfilesuffix}[helloworld-mdb] quickstart, but has been enhanced to enable property substitution using the `@Resource` and `@ActivationConfigProperty` annotations.

This project creates two JMS resources:

* A queue named `HELLOWORLDMDBQueue` bound in JNDI as `java:/${property.helloworldmdb.queue}`
* A topic named `HELLOWORLDMDBTopic` bound in JNDI as `java:/${property.helloworldmdb.topic}`

//*************************************************
// Add System Requirements
//*************************************************
// == System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]

//*************************************************
// Add Use of JBoss Home Name
//*************************************************
// == Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]

//*************************************************
// Back up the server configuration files
//*************************************************
// == Back Up the {productName} Standalone Server Configuration
include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1]

//*************************************************
// Start the server with the full profile
//*************************************************
// == Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]


[[configure_the_server]]
== Configure the Server

You enable MDB property substitution by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `enable-mdb-property-substitution.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 `enable-mdb-property-substitution.cli` script file in the root of this quickstart directory. This script first enables MDB annotation property substitution the `ee` subsystem of the server configuration file by creating an `annotation-property-replacement` property with a value of `true`. It then defines the system properties that are used in the substitution.
. 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=enable-mdb-property-substitution.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 `<annotation-property-replacement>` attribute is set to true in the `ee` subsystem :

[source,xml,subs="attributes+",options="nowrap"]
----
<subsystem xmlns="{EESubsystemNamespace}">
    ...
    <annotation-property-replacement>true</annotation-property-replacement>
    ...
</subsystem>
----

The following system properties are defined and appear after the `<extensions>`:

[source,xml,options="nowrap"]
----
<system-properties>
    <property name="property.helloworldmdb.queue" value="java:/queue/HELLOWORLDMDBPropQueue"/>
    <property name="property.helloworldmdb.topic" value="java:/topic/HELLOWORLDMDBPropTopic"/>
    <property name="property.connection.factory" value="java:/ConnectionFactory"/>
</system-properties>
----

//*************************************************
// Build and deploy the quickstart WAR
//*************************************************
// == Build and Deploy the Quickstart
include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]

// Additional instructions.
Look at the {productName} console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations:

[source,options="nowrap"]
----
INFO  [org.wildfly.extension.messaging-activemq] (MSC service thread 1-8) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.queue}
INFO  [org.wildfly.extension.messaging-activemq] (MSC service thread 1-5) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.topic}
...
INFO  [org.wildfly.extension.messaging-activemq] (ServerService Thread Pool -- 70) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/queue/HELLOWORLDMDBPropQueue
INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 73) AMQ221003: trying to deploy queue jms.topic.HelloWorldMDBTopic
INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 72) AMQ221003: trying to deploy queue jms.topic.HELLOWORLDMDBTopic
INFO  [org.wildfly.extension.messaging-activemq] (ServerService Thread Pool -- 72) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/topic/HELLOWORLDMDBPropTopic
INFO  [org.apache.activemq.artemis.core.server] (ServerService Thread Pool -- 71) AMQ221003: trying to deploy queue jms.queue.HelloWorldMDBQueue
INFO  [org.jboss.as.ejb3] (MSC service thread 1-7) WFLYEJB0042: Started message driven bean 'HelloWorldQTopicMDB' with 'activemq-ra.rar' resource adapter
INFO  [org.jboss.as.ejb3] (MSC service thread 1-6) WFLYEJB0042: Started message driven bean 'HelloWorldQueueMDB' with 'activemq-ra.rar' resource adapter
----

== Access the Application

The application will be running at the following URL: http://localhost:8080/{artifactId}/ and will send some messages to the queue.

To send messages to the topic, use the following URL: http://localhost:8080/{artifactId}/HelloWorldMDBServletClient?topic

== Investigate the Server Console Output

Look at the {productName} console or Server log and you should see log messages like the following:

[source,options="nowrap"]
----
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-7 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 4
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-5 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 2
INFO  [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 3
----

//*************************************************
// Undeploy the quickstart archive
//*************************************************
// == Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]


//************************************************************
// Restore the {productName} Standalone Server Configuration
//************************************************************
// == Restore the {productName} Standalone Server Configuration
:restoreScriptName: disable-mdb-property-substitution.cli
include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1]

This script removes the system properties and sets the `<annotation-property-replacement>` value to `false` in the `ee` subsystem of the server configuration. You should see the following result when you run the script:

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

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


//*************************************************
// Add JBoss Developer Studio instructions
//*************************************************
// == 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
* Make sure you enable MDB property substitution by running the JBoss CLI commands as described above under xref:configure_the_server[Configure the Server]. Stop the server at the end of that step.
* Within JBoss Developer Studio, make sure you define a server runtime environment that uses the `standalone-full.xml` configuration file.
* Make sure you xref:restore_the_server_configuration[restore the server configuration] when you have completed testing this quickstart.

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