Chapter 4. Using Celtix Advanced Messaging as a JMS Replacement

Summary

Celtix Advanced Messaging offers a JMS interface and can be used in place of a dedicated JMS deployment. Deploying your services so that they use Celtix Advanced Messaging through the JMS transport involves providing the correct connection information as part of the JMS transport configuration. You do not need to make any changes to your application's code.

To configure an endpoint to use Celtix Advanced Messaging as its JMS provider you must specify the following Celtix Advanced Messaging specific information:

The class name of the Celtix Advanced Messaging initial context factory.
The URL of the Celtix Advanced Messaging JNDI provider.
The URL used to connect to the Celtix Advanced Messaging connection factory.
The URL of the JMS destination(s) used by the application.

	Important
	In addition to the above, you will also need to provide the standard JMS configuration information.

	Tip
	This information can be provided as part of an endpoint's WSDL document or in an endpoint's configuration.

JMS Addressing Information

Regardless of the JMS provider in use, you will always need to provide some standard addressing information using the jms:address element's attributes. Table 4.1, “jms:address Attributes for Using Celtix Advanced Messaging” shows the attributes needed when using Celtix Advanced Messaging as a JMS provider.

Table 4.1. jms:address Attributes for Using Celtix Advanced Messaging

Attribute	Description
`destinationStyle`	Celtix Advanced Messaging supports both queues and topics.
`jndiConnectionFactoryName`	The JNDI name for the connection factory can be any string. You will need to use this value when providing the Celtix Advanced Messaging specific JMS properties.
`jndiDestinationName`	The JNDI name for the destination can be any string. You will need to use this value when providing the Celtix Advanced Messaging specific JMS properties.

The JNDI Initial Context Factory

You specify the Celtix Advanced Messaging JNDI initial context factory using a jms:JMSNamingProperty element. As shown in Example 4.1, “Specifying the JNDI Initial Context Factory”, the value of the name attribute is java.naming.factory.initial and the value of the value attribute is org.apache.qpid.jndi.PropertiesFileInitialContextFactory.

Example 4.1. Specifying the JNDI Initial Context Factory

<jms:address ...>
  <jms:JMSNamingProperty name="java.naming.factory.initial"
                         value="org.apache.qpid.jndi.PropertiesFileInitialContextFactory" />
  ...
</jms:address>

The JNDI Provider URL

You specify the JNDI provider's URL using a jms:JMSNamingProperty element. The value of the name attribute is java.naming.provider.url. The value of the value attribute is the URL at which the Celtix Advanced Messaging broker is running.

	Tip
	The default URL for the Celtix Advanced Messaging broker is `tcp://localhost:5672`/

For more information about setting up the Celtix Advanced Messaging broker see http://cwiki.apache.org/qpid/qpid-design-configuration.html.

The connection factory URL

You specify the connection factory's URL using a jms:JMSNamingProperty element. The name of the property you are going to set and the value of the property are dependent on your environment's set up.

The name of the property, specified in the name attribute, uses the value provided for the JNDI connection factory name in the jms:address element's jndiConnectionFactoryName attribute. To determine the property name you append that value of the jms:address element's jndiConnectionFactoryName attribute to connectionfactory. For example, if you specified that the JNDI name of the connection factory was Qpid, then the property name would be connectionfactory.Qpid.

The value of the property, specified in the value attribute, uses the syntax ampq://[username:password@][clientid]virtualhost?brokerlist='providerURL'[&option='value']]. Table 4.2, “Celtix Advanced Messaging Connection Factory URL Fields” describes each of the fields in the URL.

Table 4.2. Celtix Advanced Messaging Connection Factory URL Fields

Field	Description
username	Specifies the username used to connect to the broker. The default value is `guest`.
password	Specifies the password used to connect to the broker. The default value is `guest`.
clientid	Specifies the name of the server from which you are connecting. This field is optional.
virtualhost	Specifies the virtualhost ID. The virtualhost is a path that acts as a namespace. It must start with a `/` followed by any combination of non-whitespace, alphanumeric characters.
providerURL	Specifies the URL of the broker. This is the value specified in The JNDI Provider URL.
option	Specifies the options used to connect to the specified broker. Supported options include `ssl`, `failover`, and `cyclecount`.
value	Specifies the value used to configure the associated option.

Example 4.2, “Setting the Celtix Advanced Messaging Connection Factory URL” shows a configuration entry setting the connection factory URL.

Example 4.2. Setting the Celtix Advanced Messaging Connection Factory URL

<jms:address ...
             jndiConnectionFactoryName="rope"
             ... >
  ...
  <jms:JMSNamingProperty name="java.naming.provider.url"
                         value="tcp://localhost:5672" />
  <jms:JMSNamingProperty name="connectionfactory.rope"
                         value="amqp://joe:1234@joescafe/counter?brokerlist='tcp://localhost:5672'" />
  ...
</jms:address>

For more information see http://cwiki.apache.org/qpid/connectionurlformat.html.

The destination URL

You specify a destination's URL using a jms:JMSNamingProperty element. The name of the property you are going to set and the value of the property are dependent on your environment's set up.

The name of the property, specified in the name attribute, is determined by appending either topic or queue to the value of the jms:address element's jndiDestinationName attribute. You use topic if your destination is a JMS topic. You use queue if your destination is a JMS queue.

The value of the property, specified in the value attribute, is the URL assigned to the destination. It is specified as either topic://topicName for a JMS topic or queue://queueName for a JMS queue.

Example 4.3, “Setting the Celtix Advanced Messaging Destination URL” shows a configuration entry setting the destination URL.

Example 4.3. Setting the Celtix Advanced Messaging Destination URL

<jms:address destinationStyle="queue"
             jndiDestinationName="testQueue"
             ... >
  ...
  <jms:JMSNamingProperty name="queue.testQueue"
                         value="queue://queuetest" />
  ...
</jms:address>

For more information see http://cwiki.apache.org/qpid/bindingurlformat.html.

	Tip
	If you are using a named reply destination, you will need to specify its URL as well.

Example

Example 4.4, “Defining a JMS Endpoint that Uses Celtix Advanced Messaging” shows a WSDL document fragment for an endpoint using Celtix Advanced Messaging as its JMS provider.

Example 4.4. Defining a JMS Endpoint that Uses Celtix Advanced Messaging

<wsdl:definitions ...>
  ...
  <wsdl:service ...>
    <wsdl:port ...>
      <jms:address destinationStyle="topic"
                   jndiConnectionFactoryName="local"
                   jndiDestinationName="direct">
        <jms:JMSNamingProperty name="java.naming.factory.initial"
                               value="org.apache.qpid.jndi.PropertiesFileInitialContextFactory"/>
        <jms:JMSNamingProperty name="java.naming.provider.url"
                                  value="tcp://localhost:5672"/>
        <jms:JMSNamingProperty name="connectionfactory.local"
                               value="amqp://guest:guest@ce_home/test?brokerlist='tcp://localhost:5672'"/>
        <jms:JMSNamingProperty name="topic.direct" value="topic://topictest"/>
      </jms:address>
    </wsdl:port>
  </wsdl:service>
 <wsdl:definitions>