Using an XML Broker

Go Up to Writing Web-based Client Applications

The XML broker receives updates in the form of XML delta packets from browsers and applies them to the application server.

When you add the XML broker to the Web module (or data module containing a TWebDispatcher), it automatically registers itself with the Web dispatcher as an auto-dispatching object. This means that, unlike other components, you do not need to create an action item for the XML broker in order for it to respond to update messages from a Web browser. These messages contain XML delta packets that should be applied to the application server. Typically, they originate from a button that you create on one of the HTML pages produced by the Web client application.

So that the dispatcher can recognize messages for the XML broker, you must describe them as presented in the Dispatching request messages topic.

When the dispatcher passes an update message on to the XML broker, it passes the updates on to the application server and if there are update errors, it receives an XML delta packet describing all update errors. Finally, it sends a response message back to the browser, which either redirects the browser to the same page that generated the XML delta packet or sends it some new content.

A number of events allow you to insert custom processing at all steps of this update process:

1. When the dispatcher first passes the update message to the XML broker, it receives a XMLBrokr.TXMLBroker.BeforeDispatch event, where you can preprocess the request or even handle it entirely. This event allows the XML broker to handle messages other than update messages.
2. If the BeforeDispatch event handler does not handle the message, the XML broker receives an XMLBrokr.TXMLBroker.OnRequestUpdate event, where you can apply the updates yourself rather than using the default processing.
3. If the OnRequestUpdate event handler does not handle the request, the XML broker applies the updates and receives a delta packet containing any update errors.
4. If there are no update errors, the XML broker receives an XMLBrokr.TXMLBroker.OnGetResponse event, where you can create a response message that indicates the updates were successfully applied or sends refreshed data to the browser. If the OnGetResponse event handler does not complete the response (does not set the Handled parameter to True), the XML broker sends a response to redirect the browser back to the document which had generated the delta packet.
5. If there are update errors, the XML broker receives an XMLBrokr.TXMLBroker.OnGetErrorResponse event instead. You can use this event to try to resolve update errors or to generate a Web page that describes them to the end user. If the OnGetErrorResponse event handler does not complete the response (does not set the Handled parameter to True), the XML broker calls on a special content producer called the ReconcileProducer to generate the content of the response message.
6. Finally, the XML broker receives an XMLBrokr.TXMLBroker.AfterDispatch event, where you can perform any final actions before sending a response back to the Web browser.