Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
This documentation is for WSO2 Message Broker version 3.2.0. For the latest documentation, see the documentation for WSO2 Enterprise Integrator.
Skip to end of metadata
Go to start of metadata

When a JMS client connects to WSO2 Message Broker (WSO2 MB), the connection parameters are specified using the connectionfactory interface as shown below.

  • connectionfactory.ConnectionFactory = <Connection_URL>

  • connectionfactory.QueueConnectionFactory = <Connection_URL>
  • connectionfactory.TopicConnectionFactory = <Connection_URL>

See the following topics:

Parameters used in the connection URL

The connection URL takes the following format, when the AMQP transport is used:


For example:

connectionfactory.QueueConnectionFactory = amqp://admin:[email protected]/carbon?brokerlist='tcp://IP1:5672'

Note that the clientID is used for identifying the client and is only applicable for durable topic subscriptions. However, since this value is not validated in WSO2 MB, you can enter any arbitrary string as the clientID.

Now, let's look at the parameters used in the above URL format:

  • <user>:<pass>@: This is the username:password that will be used to connect to WSO2 MB. Note that this user should have the required permissions granted in WSO2 MB. See the section for user permissions in WSO2 MB for more information on how permissions are defined.

  • /<virtualhost>: The name of the virtual host, where the virtual host is a path that acts as a namespace. A name consists of any combination of the following: At least one alphanumerical value [A-Za-z0-9] and optionally special characters [.-_+!=:].

  • <option>='<value>': You can enter multiple options with values as explained below. These options should be separated by '&'.


    The list of brokers to use for this connection. The value should contain the URL of the broker as well as any other optional values. You can add any number of broker URLs separated by ';' as shown below.

    brokerlist='<broker url>[;<broker url>]'

    See the topic below on Using the brokerlist option for details on how to configure the broker URL.

    failoverThis option controls how failover occurs when you have a list of brokers. The value used with the failover option should contain the failover method as well as any other optional values. See the topic below on Using the failover option for details.

    This option can be used to specify the required delay in redelivering a message to the subscriber client when the first attempt fails. The value should be in milliseconds.

    Note that this option is available only as a WUM update, and is available from the 5th of April, 2018. For instructions on getting updates for WSO2 MB, see Updating WSO2 Products.

    See Redelivering Messgaes to Subscriber for more information on this option.

Using the 'brokerlist' option

When you use the brokerlist option, the broker URL should be as follows:


Now, let's look at each of the parameters used in the broker URL:

  • <transport>: The transport should be TCP.

    To support more transports, the ''client.transportTransportConnection'' class needs to be updated along with the parsing to handle the transport.

  • <host>: The IP address.
  • <port>: The default AMQP port of 5672 is used if no port is specified.
  • <option>='<value>': Each broker can have additional options that are specific to that broker. The following are the options that are currently implemented:

    OptionDefault ValueDescription



    The number of retry attempts when connecting to the broker.



    Use SSL on the connection.



    How long (in milliseconds) to wait for the connection to succeed.



    How long (in milliseconds) to wait before attempting to reconnect. The recommended value is 30000 milliseconds.

Using the 'failover' option

When you use the failover option, the following format should be followed:


Now, let's look at the parameters in the above format:

  • <method>: Listed below are the supported methods. Note that 'singlebroker' is used when only one broker is present and the 'roundrobin' method is used with multiple brokers. The 'nofailover' method is useful if you are using a 3rd party tool that has its own reconnection strategy that you wish to use.



    This will only use the first broker in the list.


    This method tries each broker in turn.


    [New in 0.5] This method disables all retry and failover logic.

    onetimeThis method ensures that XA transactions do not failover from one node another. That is, if the connection fails before all messages are committed to the broker node, the XA transaction will be canceled. The client will then reconnect to the next available broker in the list and resend all the messages from the beginning. See Handling Distributed Transactions for more information

    The <method> value in the URL may also be any valid class on the classpath that implements the FailoverMethod interface.

  • <option>: The following options should be used for the failover method.

    OptionDefault ValueDescription



    The number of times to loop through the list of available brokers before failure.


For example, see how multiple brokers are defined in the connection URL, along with failover parameters.

connectionfactory.QueueConnectionFactory = amqp://admin:[email protected]/carbon?failover='roundrobin'&cyclecount='2'&brokerlist='tcp://localhost:5673?retries='5'&connectdelay='50';tcp://localhost:5674?retries='5'&connectdelay='50';tcp://localhost:5675?retries='5'&connectdelay='30000''
  • No labels