RAD Studio
ContentsIndex
PreviousUpNext
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.

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.
The components that generate HTML and javascript for the InternetExpress application automatically use the XML broker's XML data packet once you set their XMLBroker property. To obtain the XML data packet directly in code, use the RequestRecords method.
Note: When the XML broker supplies a data packet to another component (or when you call RequestRecords), it receives an 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.

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 WebDispatch property. Set the PathInfo property to the path portion of the URL to which messages for the XML broker are sent. Set MethodType to the value of the method header of update messages addressed to that URL (typically mtPost). If you want to respond to all messages with the specified path, set MethodType to mtAny. If you don't want the XML broker to respond directly to update messages (for example, if you want to handle them explicitly using an action item), set the Enabled property to False. For more information on how the Web dispatcher determines which component handles messages from the Web browser, see 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:

  1. When the dispatcher first passes the update message to the XML broker, it receives a 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 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 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.
  5. If there are update errors, the XML broker receives an 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 AfterDispatch event, where you can perform any final actions before sending a response back to the Web browser.

Copyright(C) 2008 CodeGear(TM). All Rights Reserved.
What do you think about this topic? Send feedback!