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 may 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 would then be configured in the Patch Bay to go to a separate set of destinations.
In the Patch Bay, those outputs are called ports. The author of a messaging component chooses the names of the ports that will be 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 will be sent. This means that the port names used by the component will be hard-coded into the component.
In the 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 will be sending messages through at least two ports - Normal and Emergency. The Patch Bay then directs messages coming out of those two ports to different destinations:
Normal messages go to
localdms:/local/NormalMessages.Emergency messages go to
localdms:/local/EmergencyMessages.
If TestMessageSource1 sends a message through some other port name, that message will go 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 will send 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 will use. It just sends a message out using a name, and if the Patch Bay has destinations hooked up to that name, the message will be sent to those destinations. It is the responsibility of the message source developer to provide documentation as to what output ports it will use in what situations.
Message sinks can also make use of ports. Whenever a message is received, the receiveMessage method will pass 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, then the receiveMessage method will be passed LowPriority as the name of the port. But if a message arrives from sqldms:/PersistentTopic1, then the receiveMessage methods will be passed HighPriority. An input port may have many input destinations. If a message arrives from any of those destinations, it will be passed in with the name of its associated input port. Once 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 the 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 will 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 that if you use the DEFAULT port name, you can omit the port-name 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)