In addition to Web services that call Nucleus methods, the ATG platform enables you to create Web services that send JMS messages through Patch Bay. Many events in the ATG platform are triggered by JMS messages, so by calling a Web service that sends a JMS message, a client can start execution of various services and processes. In particular, scenario actions are triggered by JMS messages, so you can use Web service calls to invoke scenario actions remotely. For example, suppose a new user registers in some application, which invokes a Web service that sends the registration information to the ATG platform. The client application could then call a Web service that sends a JMS message of type atg.dps.Register into Patch Bay, thereby triggering a scenario action that (for instance) sends an e-mail message to the new user.
This chapter discusses how to create Web services that send JMS messages, and how to configure components to listen for these messages. For more information about JMS and Patch Bay
Using the JMS Message Web Service Wizard
To create a Web service that sends a JMS message, you use the Web Service Creation Wizard, just as you do for Web services that invoke Nucleus methods. On the first screen of the wizard, however, you click the JMS Message Web Service link (rather than the Component Method Web Service link). In this version of the wizard, you do not select a Nucleus component and method; instead, the key selections are the message type and the Patch Bay port name to use. The message type is the JMSType value for the message. This is a String, stored in the message’s header, that identifies the kind of message it is. For example, a message of JMSTypeatg.dps.PageVisit is sent when a site visitor displays a page.
For the port name, the wizard gives you two options, IndividualEvents and GlobalEvents. These are the standard ports where the Scenario Manager listens for scenario events.
The names of the classes generated by the wizard are based on the JMS message type of the message. For example, if you create a Web service that sends a message whose JMSType is atg.dps.PageVisit, the service implementation interface is named SendPageVisitSEI, and the service implementation class is named SendPageVisitSEIImpl.
Structure of a JMS Web Service
JMS Web services generated by the wizard are similar to Web services that call Nucleus methods. JMS services expose a Nucleus method, but it is always the receiveObjectMessage() method of the component /atg/dynamo/messaging/MessageImporter. This method receives the message object and forwards it into Patch Bay.
The receiveObjectMessage() method takes three parameters:
the message object
a String indicating the JMSType of the message
a String indicating the Patch Bay port name to use
The Web service call itself takes only a single argument, the message object. The JMSType and port name are hard-coded when you generate the Web service, and the service implementation class passes them (along with the message object supplied by the client) to the receiveObjectMessage() method. This simplifies the client’s task, because it does not need to be aware of either the JMSType or the port name.
For example, a Web service that sends a JMS message when a user views a page would be called like this:
public void sendPageVisit(atg.userprofiling.dms.PageVisitMessage a);
The service implementation class then calls the receiveObjectMessage() method like this:
messageImporter.receiveObjectMessage(a, "atg.dps.PageVisit",
"IndividualEvents");
For information about calling Web services that send JMS messages from Java clients, see the Accessing ATG Web Services from Java Clients chapter. (Note that you cannot use the dynamic process described in that chapter for calling these Web services.) For information about calling Web services that send JMS messages from .NET clients,
Patch Bay Configuration
The /atg/dynamo/messaging/MessageImporter component, whose receiveObjectMessage() method is invoked by JMS Web services, is a Patch Bay message source. When a Web service invokes the method, the message passed to that method is sent either to the destination patchbay:/sqldms/MessageImporter/IndividualEvents or to patchbay:/sqldms/MessageImporter/CollectiveEvents, depending on the message type.
The standard Patch Bay configuration file, /atg/dynamo/messaging/dynamoMessagingSystem.xml, includes the necessary declarations for the message source and destinations:
<message-source>
<nucleus-name>
/atg/dynamo/messaging/MessageImporter
</nucleus-name>
<output-port>
<port-name>
IndividualEvents
</port-name>
<output-destination>
<destination-name>
patchbay:/sqldms/MessageImporter/IndividualEvents
</destination-name>
<destination-type>
Topic
</destination-type>
</output-destination>
</output-port>
<output-port>
<port-name>
GlobalEvents
</port-name>
<output-destination>
<destination-name>
patchbay:/sqldms/MessageImporter/CollectiveEvents
</destination-name>
<destination-type>
Queue
</destination-type>
</output-destination>
</output-port>
</message-source>
The Scenario Manager is a message sink configured to receive messages from these destinations. This configuration occurs in two places:
In the standard Patch Bay configuration file, the Scenario Manager is configured to receive individual scenario events from the destination patchbay:/sqldms/MessageImporter/IndividualEvents.
In the /atg/dynamo/messaging/dynamoMessagingSystemDSSGlobal.xml file, the Scenario Manager is configured to receive global scenario events from the destination patchbay:/sqldms/MessageImporter/CollectiveEvents.
You can configure other message sinks to receive messages from the patchbay:/sqldms/MessageImporter/IndividualEvents destination by declaring them in the dynamoMessagingSystem.xml file. Note, however, that you cannot configure other sinks to receive messages from patchbay:/sqldms/MessageImporter/CollectiveEvents. This destination is a queue, used by global Scenario Managers only; adding sinks to this destination may interfere with the global Scenario Managers receiving messages. If you want another message sink to receive these messages, configure an additional destination for MessageImporter to send global scenario events to, and configure your sink to listen to that destination instead.
No comments:
Post a Comment