In the Patch Bay configuration, a component can be configured to send its messages to a destination (or group of destinations), or to receive its messages from a destination (or group of destinations). Sometimes, however, you might want a component to have more control over where its messages are going. For example, a message filter might read in a message and then resend that message to one of several outputs based on some aspect of the message, such as its JMSType. Each of those outputs are then configured in Patch Bay to go to a separate set of destinations.

In Patch Bay, those outputs are called ports. The author of a messaging component chooses the names of the ports that are used by that component. Whenever a message source (or filter) sends a message, it must specify the name of the port through which the message is sent. This means that the port names used by the component are hard-coded into the component.

In Patch Bay, each of a component’s output ports can be attached to a different set of destinations. For example:

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

  <output-port>
    <port-name>
      Normal
    </port-name>

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

  </output-port>

  <output-port>
    <port-name>
      Emergency
    </port-name>

    <output-destination>
      <provider-name>
        local
      </provider-name>
      <destination-name>
        localdms:/local/EmergencyMessages
      </destination-name>
      <destination-type>
        Topic
      </destination-type>
    </output-destination>
  </output-port>
</message-source>

In this example, it is assumed that TestMessageSource1 is sending messages through at least two ports: Normal and Emergency. Patch Bay then directs messages coming out of those two ports to different destinations:

If TestMessageSource1 sends a message through some other port name, that message goes nowhere.

A MessageSource must be coded to specify which port it wants a message to use. The port is specified in both the createMessage and sendMessage methods. For example, this sends a TextMessage through the Normal port.

public void sendOneMessage ()
  throws JMSException
{
  if (mStarted && mContext != null) {
    TextMessage msg = mContext.createTextMessage ("Normal");
    msg.setJMSType ("atg.test.Test1");
    msg.setText ("Test text string");
    mContext.sendMessage ("Normal", msg);
  }
}

Notice that the message source does not need to declare what ports it uses. It just sends a message out using a name, and if Patch Bay has destinations hooked up to that name, the message is sent to those destinations. It is the responsibility of the message source developer to provide documentation as to what output ports it uses and in what situations.

Message sinks can also make use of ports. Whenever a message is received, the receiveMessage method passes in the name of the port through which the message arrived. For example, the DMS configuration might look something like this:

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

  <input-port>
    <port-name>
      LowPriority
    </port-name>

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

  </input-port>

  <input-port>
    <port-name>
      HighPriority
    </port-name>

    <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>

If a message arrives from localdms:/local/TestMessages, the receiveMessage method is passed LowPriority as the name of the port. But if a message arrives from sqldms:/PersistentTopic1, the receiveMessage methods are passed HighPriority. An input port can have many input destinations. If a message arrives from any of those destinations, it is passed in with the name of its associated input port. Again, the message sink need not declare what ports it uses. However, the message sink developer should document what port names the message sink expects to see.

Ports provide another level of flexibility available through Patch Bay, but they should be used with care because they push some of the hookup responsibility into the messaging component code. Many of the functions provided by ports can be provided by other means, such as using different JMSTypes. The vast majority of message sources and sinks use only one output or input port. Use of multiple ports should be kept to a minimum, perhaps restricted to special general-purpose components such as multiplexers/demultiplexers or other message distribution components that really require them.

Using the Default Port

If a message source uses only one output port, that port should be called DEFAULT. The same is true for message sinks that use one input port. This is illustrated in the examples in the Connecting to Destinations section.

Note: If you use the DEFAULT port name, you can omit the portname tag from the Patch Bay configuration file, because the default value for this tag is DEFAULT.

The createMessage and sendMessage methods also default to using DEFAULT for the port name. For example:

MessageSourceContext.createTextMessage()

is equivalent to

MessageSourceContext.createTextMessage("DEFAULT")

and

MessageSourceContext.sendMessage(pMessage)

is equivalent to

MessageSourceContext.sendMessage("DEFAULT",pMessage)

 
loading table of contents...