Chapter 3. Getting Started
3.1. Using the helloworld-mdb Quickstart
The helloworld-mdb quickstart uses a simple message-driven bean to demonstrate basic Java EE 7 messaging features. Having the quickstart up and running as you review the basic configuration is an excellent way to introduce yourself to the features included with the JBoss EAP messaging server.
Build and Deploy the helloworld-mdb Quickstart
See the instructions in the README.md file provided with the quickstart for instructions on building and deploying the helloworld-mdb quickstart. You will need to start the JBoss EAP server specifying the full configuration, which contains the messaging-activemq subsystem. See the README.md file or the JBoss EAP Configuration Guide for details on starting JBoss EAP with a different configuration file.
3.2. Overview of the Messaging Subsystem Configuration
Default configuration for the messaging-activemq subsystem is included when starting the JBoss EAP server with the full or full-ha configuration. The full-ha option includes advanced configuration for features like clustering and high availability.
Although not necessary, it is recommended that you use the helloworld-mdb quickstart as a working example to have running alongside this overview of the configuration.
For information on all settings available in the messaging-activemq subsystem, see the schema definitions located in the EAP_HOME/docs/schema/ directory, or run the read-resource-description operation on the subsystem from the management CLI, as shown below.
/subsystem=messaging-activemq:read-resource-description(recursive=true)
The following extension in the server configuration file tells JBoss EAP to include the messaging-activemq subsystem as part of its runtime.
<extensions> ... <extension module="org.wildfly.extension.messaging-activemq"/> ... </extensions>
The configuration for the messaging-activemq subsystem is contained within the <subsystem xmlns="urn:jboss:domain:messaging-activemq:2.0"> element.
<subsystem xmlns="urn:jboss:domain:messaging-activemq:2.0">
<server name="default">
<cluster password="${jboss.messaging.cluster.password:CHANGE ME!!}"/>
<security-setting name="#">
<role name="guest" send="true" consume="true" create-non-durable-queue="true" delete-non-durable-queue="true"/>
</security-setting>
<address-setting name="#" dead-letter-address="jms.queue.DLQ" expiry-address="jms.queue.ExpiryQueue" max-size-bytes="10485760" page-size-bytes="2097152" message-counter-history-day-limit="10" redistribution-delay="1000"/>
<http-connector name="http-connector" socket-binding="http" endpoint="http-acceptor"/>
<http-connector name="http-connector-throughput" socket-binding="http" endpoint="http-acceptor-throughput">
<param name="batch-delay" value="50"/>
</http-connector>
<in-vm-connector name="in-vm" server-id="0"/>
<http-acceptor name="http-acceptor" http-listener="default"/>
<http-acceptor name="http-acceptor-throughput" http-listener="default">
<param name="batch-delay" value="50"/>
<param name="direct-deliver" value="false"/>
</http-acceptor>
<in-vm-acceptor name="in-vm" server-id="0"/>
<broadcast-group name="bg-group1" connectors="http-connector" jgroups-channel="activemq-cluster"/>
<discovery-group name="dg-group1" jgroups-channel="activemq-cluster"/>
<cluster-connection name="my-cluster" address="jms" connector-name="http-connector" discovery-group="dg-group1"/>
<jms-queue name="ExpiryQueue" entries="java:/jms/queue/ExpiryQueue"/>
<jms-queue name="DLQ" entries="java:/jms/queue/DLQ"/>
<connection-factory name="InVmConnectionFactory" connectors="in-vm" entries="java:/ConnectionFactory"/>
<connection-factory name="RemoteConnectionFactory" ha="true" block-on-acknowledge="true" reconnect-attempts="-1" connectors="http-connector" entries="java:jboss/exported/jms/RemoteConnectionFactory"/>
<pooled-connection-factory name="activemq-ra" transaction="xa" connectors="in-vm" entries="java:/JmsXA java:jboss/DefaultJMSConnectionFactory"/>
</server>
</subsystem>Connection Factories
Messaging clients use a JMS ConnectionFactory object to make connections to the server. The default JBoss EAP configuration defines several connection factories. Note that there is a <connection-factory> for in-vm, http, and pooled connections.
<connection-factory name="InVmConnectionFactory" connectors="in-vm" entries="java:/ConnectionFactory"/> <connection-factory name="RemoteConnectionFactory" ha="true" block-on-acknowledge="true" reconnect-attempts="-1" connectors="http-connector" entries="java:jboss/exported/jms/RemoteConnectionFactory"/> <pooled-connection-factory name="activemq-ra" transaction="xa" connectors="in-vm" entries="java:/JmsXA java:jboss/DefaultJMSConnectionFactory"/>
See the Configuring Connection Factories section for more details.
Connectors and Acceptors
Each JMS connection factory uses connectors to enable JMS-enabled communication from a client producer or consumer to a messaging server. The connector object defines the transport and parameters used to connect to the messaging server. Its counterpart is the acceptor object, which identifies the type of connections accepted by the messaging server.
The default JBoss EAP configuration defines several connectors and acceptors.
Example: Default Connectors
<http-connector name="http-connector" socket-binding="http" endpoint="http-acceptor"/> <http-connector name="http-connector-throughput" socket-binding="http" endpoint="http-acceptor-throughput"> <param name="batch-delay" value="50"/> </http-connector> <in-vm-connector name="in-vm" server-id="0"/>
Example: Default Acceptors
<http-acceptor name="http-acceptor" http-listener="default"/> <http-acceptor name="http-acceptor-throughput" http-listener="default"> <param name="batch-delay" value="50"/> <param name="direct-deliver" value="false"/> </http-acceptor>
See the Acceptors and Connectors section for more details.
Socket Binding Groups
The socket-binding attribute for the default connectors reference a socket binding named http. The http connector is used because JBoss EAP can multiplex inbound requests over standard web ports.
You can find this socket-binding as part of the <socket-binding-group> section elsewhere in the configuration file. Note how the configuration for the http and https socket bindings appear within the <socket-binding-groups> element:
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
...
<socket-binding name="http" port="${jboss.http.port:8080}"/>
<socket-binding name="https" port="${jboss.https.port:8443}"/>
...
</socket-binding-group>For information on socket bindings, see Configuring Socket Bindings in the JBoss EAP Configuration Guide.
Messaging Security
The messaging-activemq subsystem includes a single security-setting element when JBoss EAP is first installed:
<security-setting name="#"> <role name="guest" delete-non-durable-queue="true" create-non-durable-queue="true" consume="true" send="true"/> </security-setting>
This declares that any user with the role guest can access any address on the server, as noted by the wildcard #. See Configuring Address Settings for more information on the wildcard syntax .
For more information on securing destinations and remote connections see Configuring Messaging Security.
Messaging Destinations
The full and full-ha configurations include two helpful queues that JBoss EAP can use to hold messages that have expired or that cannot be routed to their proper destination.
<jms-queue name="ExpiryQueue" entries="java:/jms/queue/ExpiryQueue"/> <jms-queue name="DLQ" entries="java:/jms/queue/DLQ"/>
You can add your own messaging destinations in JBoss EAP using one of the following methods.
Using the management CLI
Use the following management CLI command to add a queue.
jms-queue add --queue-address=testQueue --entries=queue/test,java:jboss/exported/jms/queue/test
Use the following management CLI command to add a topic.
jms-topic add --topic-address=testTopic --entries=topic/test,java:jboss/exported/jms/topic/test
Using the management console
Messaging destinations can be configured from the management console by selecting the Configuration tab, navigating to the Messaging - ActiveMQ subsystem, and selecting Queues/Topics on the messaging provider.
Defining your destinations using a Java EE 7 deployment descriptor or annotation.
Starting with Java EE 7, deployment descriptors can include configuration for queues and topics. Below is a snippet from a Java EE 7 descriptor file that defines a JMS queue.
... <jms-destination> <name>java:global/jms/MyQueue</name> <interfaceName>javax.jms.Queue</interfaceName> <destinationName>myQueue</destinationName> </jms-destination> ...
For example, the message-driven beans in the
helloworld-mdbquickstart contain annotations that define the queue and topic needed to run the application. Destinations created in this way will appear in the list of runtime queues. Use the management CLI to display the list of runtime queues. After deploying the quickstart the runtime queues it created will appear as below:/subsystem=messaging-activemq/server=default/runtime-queue=*:read-resource { "outcome" => "success", "result" => [ ... { "address" => [ ("subsystem" => "messaging-activemq"), ("server" => "default"), ("runtime-queue" => "jms.queue.HelloWorldMDBQueue") ], "outcome" => "success", "result" => {"durable" => undefined} }, ... { "address" => [ ("subsystem" => "messaging-activemq"), ("server" => "default"), ("runtime-queue" => "jms.topic.HelloWorldMDBTopic") ], "outcome" => "success", "result" => {"durable" => undefined} }, ... ] }
See Configuring Messaging Destinations for more detailed information.
