After a message source, sink, or filter has been declared in the configuration file, it must be hooked up to JMS in order for its messages to go anywhere, or for it to receive messages. As discussed earlier, a messaging component is never connected directly to another component. Instead, a messaging component is hooked up to a JMS destination, maintained by one of the JMS providers registered with Patch Bay. Messaging components communicate with each other by hooking up to the same destination—if message source A sends messages to destination D, and message sink B receives messages from destination D, messages flow from A to B.

Whenever a destination is specified in the DMS configuration file, it must specify which provider owns that destination. The destination must also be named by its JNDI name, using the prefix appropriate to that destination’s provider. As discussed earlier, Oracle ATG Web Commerce includes two providers: Local JMS and SQL JMS. The following table specifies the required information for each provider:

Provider

provider-name

Destination JNDI prefix

Local JMS

local

localdms:/local

SQL JMS

sqldms

sqldms:/

The following illustrates how a message source is connected to a destination in the DMS configuration file. In this case, the destination is managed by Local JMS, and is called localdms:/local/TestMessages:

<message-source>
  <nucleus-name>
    /atg/dynamo/j2ee/examples/TestMessageSource1
  </nucleus-name>

  <output-port>
    <port-name>
      DEFAULT
    </port-name>

    <output-destination>
      <provider-name>
        local
      </provider-name>
      <destination-name>
        localdms:/local/TestMessages
      </destination-name>
      <destination-type>
        Topic
      </destination-type>
    </output-destination>

  </output-port>

</message-source>

The output-port definition is described in the Using Messaging Ports section of this chapter. The important part of this example is the output-destination definition. This definition says that messages coming out of this Nucleus component should be directed to the topic called localdms:/local/TestMessages, managed by JMS provider local. Multiple destinations can be specified for a component. For example:

<message-source>
  <nucleus-name>
    /atg/dynamo/j2ee/examples/TestMessageSource1
  </nucleus-name>

  <output-port>
    <port-name>
      DEFAULT
    </port-name>

    <output-destination>
      <provider-name>
        local
      </provider-name>
    <destination-name>
      localdms:/local/TestMessages
    </destination-name>
    <destination-type>
      Topic
    </destination-type>
    </output-destination>

    <output-destination>
      <provider-name>
        sqldms
      </provider-name>
      <destination-name>
         sqldms:/PersistentTopic1
      </destination-name>
      <destination-type>
        Topic
      </destination-type>
    </output-destination>

  </output-port>

</message-source>

This says that each message coming out of the component is sent to a destination in Local JMS, and a destination in SQL JMS. The messages are sent in the order specified.

Message sinks are configured in much the same way. For example:

<message-sink>
  <nucleus-name>
    /atg/dynamo/j2ee/examples/TestMessageSink1
  </nucleus-name>

  <input-port>
    <port-name>
      DEFAULT
    </port-name>

    <input-destination>
      <provider-name>
        local
      </provider-name>
      <destination-name>
        localdms:/local/TestMessages
      </destination-name>
      <destination-type>
         Topic
      </destination-type>
    </input-destination>

    <input-destination>
      <provider-name>
        sqldms
      </provider-name>
      <destination-name>
        sqldms:/PersistentTopic1
      </destination-name>
      <destination-type>
         Topic
      </destination-type>
      <durable-subscriber-name>
        testMessageSink1
      </durable-subscriber-name>
    </input-destination>

  </input-port>

</message-sink>

This configuration says that messages sent to either topic in either provider are passed to the TestMessageSink1 component, using the MessageSink.receiveMessage() call.

Notice that the sqldms input-destination specifies a durable-subscriber-name. This means that the connection to the topic should be made using a durable subscription, with the given durable subscriber name. If messages are sent to this topic while the subscriber is off-line, those messages are held under this name. When the subscriber starts up, the messages held under that name are passed to the message sink.

The durable-subscriber-name is optional. If it is not supplied, the subscription is non-durable, meaning that the message sink misses any messages sent to the topic while the message sink server is off-line. Durable subscriptions are probably used whenever SQL JMS is used, as most applications that require the robust persistence of SQL JMS also probably want the functionality of durable subscriptions.

Specifying Destinations for the Default Provider

A potential problem with specifying destinations as described above is that the names are provider-specific, because each provider can use different naming conventions for destinations. This means that if you change providers, you might need to rename all of your destinations in the Patch Bay configuration file. This is especially likely if your application server is IBM WebSphere Application Server or Oracle WebLogic Server, because you might want to switch at some point from SQL JMS to the application server’s own provider.

To simplify this process, Patch Bay provides a generic naming scheme for destinations, and automatically maps these names to the actual names used by SQL JMS, IBM WebSphere Application Server, or Oracle WebLogic Server, depending on the provider designated as the default provider in Patch Bay. (See Declaring JMS Providers for information about the default JMS provider.) In this naming scheme, destinations for the default provider begin with the prefix patchbay:/. For example, suppose you specify a destination name as patchbay:/myQueues/alertsQueue. The following table shows the actual destination name that Patch Bay maps this name to, depending on whether the default JMS provider is SQL JMS, WebSphere, or WebLogic:

Provider

Destination Name

SQL JMS

sqldms:/myQueues/alertsQueue

IBM WebSphere Application Server

jms/myQueues/alertsQueue

Oracle WebLogic Server

myQueues.alertsQueue