Using an XML Broker
The XML broker serves two major functions:
- It fetches XML data packets from the application server and makes them available to the Web Items that generate HTML for the InternetExpress application.
- It receives updates in the form of XML delta packets from browsers and applies them to the application server.
Fetching XML data packets
Before the XML broker can supply XML data packets to the components that generate HTML pages, it must fetch them from the application server. To do this, it uses the IAppServer interface, which it acquires from a connection component.
Note: Even when using SOAP, where the application server supports IAppServerSOAP, the XML broker uses IAppServer because the connection component acts as an adapter between the two interfaces.
You must set the following properties so that the XML producer can use the IAppServer interface:
- Set the RemoteServer property to the connection component that establishes the connection to the application server and gets its IAppServer interface. At design time, you can select this value from a drop-down list in the Object Inspector.
- Set the ProviderName property to the name of the provider component on the application server that represents the dataset for which you want XML data packets. This provider both supplies XML data packets and applies updates from XML delta packets. At design time, if the RemoteServer property is set and the connection component has an active connection, the Object Inspector displays a list of available providers. (If you are using a DCOM connection the application server must also be registered on the client machine).
Two properties let you indicate what you want to include in data packets:
- You can limit the number of records that are added to the data packet by setting the MaxRecords property. This is especially important for large datasets because InternetExpress applications send the entire data packet to client Web browsers. If the data packet is too large, the download time can become prohibitively long.
- If the provider on the application server represents a query or stored procedure, you may want to provide parameter values before obtaining an XML data packet. You can supply these parameter values using the Params property.
Note: When the XML broker supplies a data packet to another component (or when you call RequestRecords), it receives an XMLBrokr.OnRequestRecords event. You can use this event to supply your own XML string instead of the data packet from the application server. For example, you could fetch the XML data packet from the application server using GetXMLRecords and then edit it before supplying it to the emerging Web page.
Applying updates from XML delta packets
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 using the [[Dispatching Request Messages |Dispatching request messages]].
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, 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:
- When the dispatcher first passes the update message to the XML broker, it receives a XMLBrokr.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.
- If the BeforeDispatch event handler does not handle the message, the XML broker receives an XMLBrokr.OnRequestUpdate event, where you can apply the updates yourself rather than using the default processing.
- 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.
- If there are no update errors, the XML broker receives an XMLBrokr.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 that redirects the browser back to the document that generated the delta packet.
- If there are update errors, the XML broker receives an XMLBrokr.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.
- Finally, the XML broker receives an XMLBrokr.AfterDispatch event, where you can perform any final actions before sending a response back to the Web browser.