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 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:4.0"> element.

<subsystem xmlns="urn:jboss:domain:messaging-activemq:4.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-cluster="activemq-cluster"/>
        <discovery-group name="dg-group1" jgroups-cluster="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 navigating to ConfigurationSubsystemsMessaging (ActiveMQ)Server, selecting the server, selecting Destinations, and clicking View. Select the JMS Queue tab to configure queues and select the JMS Topic to configure topics.

  • Defining your destinations using a Java EE 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 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-mdb quickstart 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.