Contact Us 1-800-596-4880
  1. Homepage
  2. JMS Connector (1.9)

  3. JMS Connector Studio Configuration

All Connectors

Using Anypoint Studio to Configure JMS Connector 1.9 - Mule 4

Anypoint Studio (Studio) editors help you design and update your Mule applications, properties, and configuration files.

To add and configure a connector in Studio:

  1. Create a Mule project.

  2. Add the connector to your Mule project.

  3. Configure a source for the connector’s flow.

  4. Add a connector operation to the flow.

  5. Configure a global element for the connector.

  6. Configure the connection to a broker.

When you run the connector, you can view the app log to check for problems, as described in View the App Log.

If you are new to configuring connectors in Studio, see Using Anypoint Studio to Configure a Connector. If, after reading this topic, you need additional information about the connector fields, see the JMS Connector Reference.

Create a Mule Project

In Studio, create a new Mule project in which to add and configure the connector:

  1. In Studio, select File > New > Mule Project.

  2. Enter a name for your Mule project and click Finish.

Add the Connector to Your Mule Project

Add Anypoint Connector for JMS (JMS Connector) to your Mule project to automatically populate the XML code with the connector’s namespace and schema location and to add the required dependencies to the project’s pom.xml file:

  1. In the Mule Palette view, click (X) Search in Exchange.

  2. In the Add Dependencies to Project window, type jms in the search field.

  3. Click JMS Connector in Available modules.

  4. Click Add.

  5. Click Finish.

Adding a connector to a Mule project in Studio does not make that connector available to other projects in your Studio workspace.

Configure a Source

A source initiates a flow when a specified condition is met. You can configure one of these input sources to use with JMS Connector:

  • JMS > On New Message
    Initiates a flow by listening for incoming messages

  • HTTP > Listener
    Initiates a flow each time it receives a request on the configured host and port

  • Scheduler
    Initiates a flow when a time-based condition is met

For example, to configure an On New Message source, follow these steps:

  1. In the Mule Palette view, select JMS > On New Message.

  2. Drag On New Message to the Studio canvas.

  3. In the On New Message configuration screen, optionally change the value of the Display Name field.

  4. Click the plus sign (+) next to the Connector configuration field to configure a global element that can be used by all instances of the source in the app.

  5. In the JMS Config window, for Connection, select either one of the connection types to provide to this configuration:

    • Active MQ Connection

    • Active MQ Connection -No Connectivity Test - (DEPRECATED)

    • Generic Connection

  1. On the General tab, specify the connection information for the connector, such as required libraries for the broker, JMS specification, cache strategy, authentication, and connection factory.

  2. On the TLS/SSL tab, optionally specify a TLS configuration.

  3. On the Advanced tab, optionally specify a reconnection strategy and XA connection pool.

  4. Click OK to close the window.

  5. In the On New Message configuration screen, in Destination, specify the name of the destination from where to consume the message.

  6. Configure other optional fields in the On New Message configuration screen.

Add a Connector Operation to the Flow

When you add a connector operation to your flow, you immediately define a specific operation for that connector to perform.

To add an operation for JMS Connector, follow these steps:

  1. In the Mule Palette view, select JMS Connector and then select the desired operation.

  2. Drag the operation onto the Studio canvas and to the right of the input source.

The following screenshot shows the JMS Connector operations in the Mule Palette view of Anypoint Studio:

Select any of the JMS Connector Operations from the Mule Palette view on the right side of Anypoint Studio
Figure 1. JMS Connector Operations

Configure a Global Element for the Connector

To avoid connectivity issues, create separate JMS configurations for publishing and consuming, instead of creating a shared JMS configuration for both publishing and consuming. JMS Connector comes with a fine-tuned set of default values for publishing and consuming messages. The only requirement is to configure which connection to use. You can define a global default behavior for all the operations associated with the configuration and then override each parameter in only the operations that require a custom behavior.

To configure the global element for JMS Connector, follow these steps:

  1. Select the operation in the Studio canvas.

  2. In the configuration screen for the operation, click the plus sign (+) next to the Connector configuration field to access the global element configuration fields.

  3. In the JMS Config window, for Connection, select either one of the connection types to provide to this configuration:

    • Active MQ Connection

    • Active MQ Connection -No Connectivity Test - (DEPRECATED)

    • Generic Connection

  1. On the General tab, specify the connection information for the connector, such as required libraries for the broker, JMS specification, cache strategy, authentication, and connection factory.

  2. On the TLS/SSL tab, optionally specify a TLS configuration.

  3. On the Advanced tab, optionally specify a reconnection strategy, and XA connection pool.

  4. On the Consumer tab, optionally define global default behavior configurations for all the Consume and On New Message operations you have in your flow.

  5. On the Producer tab, optionally define global default behavior configurations for all the Publish and Publish consume operations you have in your flow.

  6. Click OK to close the window.

The following screenshot shows the JMS Connector Global Element Configuration window in Anypoint Studio:

JMS Connector Global Element Configuration window
Figure 2. JMS Connector Global Element Configuration

In the XML editor, the <jms:config> configuration looks like this:

<jms:config name="JMS_Config">
  <jms:active-mq-connection clientId="${env.clientId}"/>
</jms:config>

In the following example, you define a default Selector behavior when consuming a message in any of the Consume or On New Message operations associated with this configuration, while every Publish or Publish consume operation produces the outgoing message with a Time to live (TTL) of 60 seconds:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box type jms and select JMS Config.

  4. Click OK.

  5. In the JMS Config window, for Connection, select Active MQ Connection.

  6. In the Consumer tab, set the Selector field to JMSType = `INVOICE to filter incoming messages as invoices.

In the Consumer tab
Figure 3. JMS Connector Consumer Global Configuration

  1. In the Producer tab, set the Time to live field to 60000 to define the default time the message is in the broker before it expires and is discarded.

In the Producer tab
Figure 4. JMS Connector Producer Global Configuration

In the XML editor, the <jms:config>,selector, and timeToLive configurations looks like this:

<jms:config name="JMS_Config">
  <jms:active-mq-connection/>
  <jms:consumer-config selector="JMSType = `INVOICE`"/>
  <jms:producer-config timeToLive="60000"/>
</jms:config>

You can override these properties at the operation level when required. In the following example, you publish a message with a shorter TTL. To override the value of the Time to live field set on the global element, follow these steps:

  1. In Studio, select the Publish operation from your flow.

  2. In the Publish configuration screen, scroll down to the Publish Configuration section.

  3. Set the Time to live field to 10000 to override the default global configuration previously set.

In the Publish Configuration section
Figure 5. JMS Connector Publish Configuration Override

In the XML editor, the <jms:publish> and timeToLive configurations looks like this:

<jms:publish config-ref="JMS_Config" timeToLive="10000"/>

Configure the Connection to a Broker

To configure the connection in the global element, define the connection by selecting either ActiveMQ Connection or Generic Connection and set up the connection libraries and the JMS specification.
JMS Connector also enables you to provide credentials, if you require an authenticated connection, and also to configure connection caching to increase the performance of the application.

Configure an Active MQ Connection

JMS Connector supports ActiveMQ 5 by using the ActiveMQ Connection setting. With this connection, you can use JMS_1_1 (Default) or JMS_1_0_2b specifications. You can also configure all the general connection parameters for JMS, as well as the custom parameters present only in ActiveMQ.

After you declare the ActiveMQ connection, customize Connection Factory to your desired configuration. Every parameter in the connection comes with a default value, meaning that you are required to configure only the parameters relevant for your use case. Also, the ActiveMQ connection exposes parameters that are exclusive to the ActiveMQ implementation, like Initial redelivery delay.

In the following example, you configure an ActiveMQ Connection:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box type jms and select JMS Config.

  4. Click OK.

  5. In the Connection field select ActiveMQ Connection.

  6. In the Factory configuration field, select Edit Inline.

  7. Set the Broker url field value to the address of the broker to connect to, for example, tcp://localhost:61616.

  8. Click OK.

ActiveMQ Connection Configuration.
Figure 6. JMS Connector ActiveMQ Configuration

In the XML editor, the <jms:active-mq-connection> and <jms:factory-configuration> configuration looks like this:

 <jms:config name="JMS_Config">
  <jms:active-mq-connection >
   <jms:factory-configuration brokerUrl="tcp://localhost:61616" />
  </jms:active-mq-connection>
 </jms:config>

Configure a Generic Connection

Use Generic Connection to configure a connection to any broker implementation. JMS Connector provides a JNDI based (Java Naming and Directory Interface) connection factory builder that enables you to configure the connection using JNDI in the context of the application.

In the following example, you configure Generic Connection to Artemis to use the JMS_2_0 specification using JNDI:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box, type jms and select JMS Config.

  4. Click OK.

  5. In the Connection field, select Generic Connection.

  6. In the Specification field, select JMS_2_0.

  7. In the Connection factory field, select Edit inline.

  8. Set the Connection factory jndi name field to ConnectionFactory.

  9. In the Lookup destination field, select any of the following options:

    • NEVER

      No lookup is done and the destinations are created using the existing JMS session.

    • TRY_ALWAYS

      Tries to find the destination using JNDI, and in case it doesn’t exist, creates the destination using the current JMS session.

    • ALWAYS

      If a queue or topic cannot be found via JNDI, the lookup fails with a JMS:DESTINATION_NOT_FOUND error.

  10. Select the Name resolver builder field.

  11. Set the Jndi initial context factory field to org.apache.activemq.artemis.ActiveMQInitialContextFactory.

  12. Set the Jndi provider url field to tcp://localhost:61616?broker.persistent=false&broker.useJmx=false.

  13. Set Provider properties to Edit inline.

  14. Click the plus sign (+) to add a new provider property.

  15. In the Provider property window, set the Key field to queue.jndi-queue-in and the Value field to in.queue.

  16. Click Finish.

  17. Repeat Step 14.

  18. Set the Key field to topic.jndi-topic-in and the Value field to in.topic.

  19. Click OK.

Generic Connection Configuration.
Figure 7. JMS Connector Generic Configuration

In the XML editor, the <jms:generic-connection> and <jms:jndi-connection-factory> configuration looks like this:

<jms:config name="JMS_Config">
    <jms:generic-connection specification="JMS_2_0">
        <jms:connection-factory>
            <jms:jndi-connection-factory connectionFactoryJndiName="ConnectionFactory" lookupDestination="ALWAYS">
                <jms:name-resolver-builder
                        jndiInitialContextFactory="org.apache.activemq.artemis.ActiveMQInitialContextFactory"
                        jndiProviderUrl="tcp://localhost:61616?broker.persistent=false&amp;broker.useJmx=false">
                    <jms:provider-properties>
                        <jms:provider-property key="queue.jndi-queue-in" value="in.queue"/>
                        <jms:provider-property key="topic.jndi-topic-in" value="in.topic"/>
                    </jms:provider-properties>
                </jms:name-resolver-builder>
            </jms:jndi-connection-factory>
        </jms:connection-factory>
    </jms:generic-connection>
</jms:config>

Configure the Connection Libraries

When you configure any connection type, you must always configure a library containing the JMS client implementation, because JMS Connector is not bound to any particular implementation. You can configure ActiveMQ external libraries and generic external libraries found in the global elements view of Studio, you can manually add the library dependency in your pom.xml file.

ActiveMQ External Libraries

For an ActiveMQ Connection, you can configure three libraries:

  • ActiveMQ KahaDB
    The activemq-kahadb-store dependency is required only when using an persistent in-memory broker based on the VM transport (such as vm://localhost?broker.persistent=true). This dependency provides a valid org.apache.activemq.store.kahadb.KahaDBPersistenceAdapter implementation.

    In your pom.xml file in Studio, adding the dependency looks like this:

    <dependency>
    <groupId>org.apache.activemq</groupId>
    <artifactId>activemq-kahadb-store</artifactId>
    <version>5.14.4</version>
</dependency>

  • ActiveMQ Broker
    The activemq-broker dependency is required only when using an in-memory broker based on the VM transport (which is the one configured by default). This dependency provides a valid org.apache.activemq.broker.Broker implementation.

    In your pom.xml file in Studio, adding the dependency looks like this:

    <dependency>
    <groupId>org.apache.activemq</groupId>
    <artifactId>activemq-broker</artifactId>
    <version>5.14.4</version>
</dependency>

  • ActiveMQ Client
    The activemq-client dependency is always required. Choose one that provides a valid org.apache.activemq.ActiveMQConnectionFactory implementation.

In your pom.xml file in Studio, adding the dependency looks like this:

+

<dependency>
     <groupId>org.apache.activemq</groupId>
     <artifactId>activemq-client</artifactId>
     <version>5.14.4</version>
 </dependency>

To configure these libraries in the Global Element view, follow these steps:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box, type jms and select JMS Config.

  4. Click OK.

  5. In the Connection field, select ActiveMQ Connection.

  6. In the Required Libraries section that shows the ActiveMQ KahaDB, ActiveMQ Broker and ActiveMQ Client libraries, click the Configure…​ button to install the dependency.

  7. Select any of the following install options:

    • Add recommended library Installs the recommended library.

    • Use local file Browse to a local file for the required engine library and install it.

    • Add Maven dependency Browse to the dependency and install it.

Generic External Libraries

For Generic Connection, provide all the libraries that the connection factory of your implementation requires. Ensure that you supply all the required dependencies to the application.

In the following example, you configure a generic library for a connection that uses a JMS 2.0 specification, which requires a generic connection with a different client library, like Apache Artemis:

In your pom.xml file in Studio, adding the dependency looks like this:

<dependency>
    <groupId>org.apache.activemq</groupId>
    <artifactId>artemis-jms-client-all</artifactId>
    <version>2.17.0</version>
</dependency>

To configure these libraries in the Global Element view, follow these steps:

  1. In Studio, navigate to the Global Elements tab.

  2. Click Create.

  3. In the filter box, type jms and select JMS Config.

  4. Click OK.

  5. In the Connection field, select Generic Connection.

  6. In the Required Libraries section that shows the JMS Client, click the Configure…​ button to install the dependency.

  7. Select any of the following install options:

    • Add recommended library Installs the recommended library.

    • Use local file Browse to a local file for the required engine library and install it.

    • Add Maven dependency Browse to the dependency and install it.

Configure the JMS Specification

The JMS Specification you configure must be supported by the broker implementation associated with the connection; otherwise, the connection fails. Note that features that are available only in JMS_2_0 won’t work with any other specification.

To configure the JMS specification in Studio, follow these steps:

  1. In Studio, open the JMS Config global element window.

  2. In the Specification field, select one of the following supported specifications:

    • JMS_1_1 (Default)

    • JMS_1_0_2b

    • JMS_2_0

  3. Click OK.

In the Specification field select one of the supported specifications
Figure 8. JMS Connector specification configuration

In the XML editor, the specification configuration looks like this:

<jms:config name="JMS_Config" >
		<jms:active-mq-connection specification="JMS_1_0_2b" />
	</jms:config>

Configure Connection Caching

To connect with a broker and execute required operations, JMS Connector creates multiple sessions of consumers and producers that can be cached and reused to increase application performance. JMS Connector enables you to configure the Caching strategy field to use when creating new connections. By default, both consumers and producers are cached and as many concurrent instances are cached in memory.

Do not disable the sessions cache by using the No caching configuration, which is used only with a custom connection factory that already manages its own cache.

In the following example you configure the caching strategy:

  1. In Studio, open the JMS Config global element window.

  2. In the Caching strategy field, select Default caching (Default).

  3. Set the Session cache size field to 100.

  4. Select Cache producers.

  5. Click OK.

In the Caching strategy field select the desired caching strategy
Figure 9. JMS Connector caching strategy configuration

In the XML editor, the <jms:caching-strategy> and <default-caching> configuration looks like this:

<jms:config name="JMS_Config">
  <jms:active-mq-connection>
    <jms:caching-strategy>
      <jms:default-caching sessionCacheSize="100" consumersCache="false" producersCache="true"/>
    </jms:caching-strategy>
  </jms:active-mq-connection>
</jms:config>

In the following XML example, the <jms:no-caching/> configuration looks like this:

<jms:config name="JMS_Config">
  <jms:generic-connection connectionFactory="customConnectionFactory">
    <jms:caching-strategy>
        <jms:no-caching/>
    </jms:caching-strategy>
  </jms:generic-connection>
</jms:config>

Configure the Client Identifier and Credentials for Authentication

The client identifier associates a connection and its objects with a state that is maintained on behalf of the client by a provider. It is mandatory for identifying an unshared durable subscription. Note that the client state identified in the Client id can be used by only one connection at a time.

In the following example, you configure an authenticated connection and the client identifier:

  1. In Studio, open the JMS Config global element window.

  2. In the Connection section, set the Username field to ${env.user} and the Password field to ${env.pass}.

  3. Set the Client id field to ${env.clientId}.

  4. Click OK.

In the Connection section, set the Username, Password, and Client id fields.
Figure 10. JMS Connector authenticated connection and client identifier configuration

In the XML editor, the username, password, and clientId configuration looks like this:

<jms:config name="JMS_Config">
  <jms:active-mq-connection username="${env.user}" password="${env.pass}" clientId="${env.clientId}"/>
</jms:config>

View the App Log

To check for problems, you can view the app log as follows:

  • If you’re running the app from Anypoint Platform, the output is visible in the Anypoint Studio console window.

  • If you’re running the app using Mule from the command line, the app log is visible in your OS console.

Unless the log file path is customized in the app’s log file (log4j2.xml), you can also view the app log in the default location MULE_HOME/logs/<app-name>.log.

See Also

Back to top
View on GitHub