ATG Programming Guide

Once 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 the 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, then messages will 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, the Dynamo Application Framework includes two providers: Local JMS and SQL JMS. The following table specifies the required information for each provider:

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 may 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 will be sent to a destination in Local JMS, and a destination in SQL JMS. The messages will be 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 will be passed to the TestMessageSink1 component, using the MessageSink.receiveMessage() call.

Notice that the sqldmsinput-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 will be held under this name. When the subscriber starts up, the messages held under that name will be passed to the message sink.

The durable-subscriber-name is optional. If it’s not supplied, then the subscription will be non-durable, meaning that the message sink will miss any messages sent to the topic while the message sink’s Dynamo is off-line. Durable subscriptions will probably be used whenever SQL JMS is used, since most applications that require the robust persistence of SQL JMS will probably want the functionality of durable subscriptions as well.

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 may 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 BEA WebLogic Server, because you may 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 BEA 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: