Dr.Bob Examines... #25: Delphi 6 XML Document Programming and XML Mapping Tool (XML Mapper)

Delphi Clinic

C++Builder Gate

Training & Consultancy

Delphi Notes Weblog

Dr.Bob's Webshop


	Dr.Bob Examines... #25
See Also:	other Dr.Bob Examines columns or Delphi articles

Delphi 6 XML Mapping Tool (XML Mapper)
Delphi 6 contains a lot of new and enhanced XML support, such as XML document programming, XML Data Binding Wizard, XML Mapper and BizSnap (SOAP/XML Web Services). This is the third - and for now last - in a series of articles about Delphi 6 XML support. This time covering the Delphi 6 XML Mapping Tool (also called the XML Mapper).

XML Mapper
Both as stand-alone tool and in the Tools menu of the IDE, you'll find a menu item called "XML Mapper". An entire tool to map XML document to a DataSet representation! In the past few months, we've used a single clinic.xml file for plain XML document programming and data-bound XML programming - both using the TXMLDocument component. This time, however, we will no longer treat an XML document as a document, nor will we need the XMLDocument component. Instead, we'll use the XML Mapping Tool to define a transformation from the XML document to a data packet (and back), so we can treat it as a dataset - something we've known and worked with for years in Delphi.
The XML Mapper File Open dialog tells you that is can load XML document files as well as data packet files (*.xml,*.cds), schema files (*.dtd,*.xdr,*.xsd), repository files (*.xrp) and transformation files (*.xtr). The latter is actually a file type generated by the XML Mapper itself. Let's just load the clinic.xml file from last month and see how a dataset mapping looks like.

As you can see in figure 1, the Clinic.xml file consists of a structure called Clinics (the meta type), which has a number of Clinic items. Each Clinic consists of four fields: @No (the attribute value of the Clinic open tag), Title, Date, and Topics. The difference between the @No field and the Title, Date and Topics nodes should be clear: the former is just an attribute of the Clinic tag, the other three have their own open and close tags.
Now, select the Clinic node, right-click with the mouse, and pick "Select All" (Ctrl+A) or "Select All Children". This will put the four nodes @No, Title, Date and Topics in the middle pane of the XML Mapper, but will not yet show the corresponding dataset fields. For that, we need to click on the Clinic node again, and select the "Create Datapacket from XML" choice (Ctrl+D). This last action will result in a Datapacket layout, generated in the right pane, and four corresponding dataset fields (one for each XML node that we selected):

As you can also see from figure 2, we can transform an XML document into four different kinds of data packets. First and foremost, the default regular dataset data packet (that we'll use in this example). But apart from the regular dataset, we can also transform the XML document into an insert or delete data packet. These can be especially useful when - in a typical B2B (business-2-business) situation - you receive an XML document with data (records) that need to be merged (inserted) into your existing back-office database. Using the XML Mapper, you can transform an XML document into such an update data packet for insert or delete.

Create and Test Transformation
Anyway, now there was just one thing left to do: click on the Create and Test Transformation button. This results in a pop-up form with a DBGrid and apparently all records from the clinic.xml document but this time transformed into a ClientDataSet data packet.
As a result of the transformation, there were a couple of formats I could save with the XML Mapper. For starters, I could save the resulting data package; the .xml ClientDataSet file version of the Clinic.xml file. If you do that, you must make sure not to accidentally overwrite the XML document with an XML dataset of the same name! Alternately, you can decide to save the transformation information into clinic.xtr. The latter can be used by the new XMLTransform components from the Data Access tab of Delphi 6 Enterprise.

XMLTransform
In the July issue of Delphi Developer, I already explained that there are three XML transformation components in Delphi 6 Enterprise. For the clinic.xtr transformation information, we need the TXMLTransformProvider component, which uses the clinic.xtr in order to transform the original clinic.xml document into a ClientDataSet. Very useful, because for the first time, we can actually access the information from the clinic.xml document using simple data-aware controls!
To demonstrate this, start Delphi 6 Enterprise (in case you've run the XML Mapper as stand-alone tool), and start a new project. Drop a TXMLTransformProvider from the Data Access tab on your main form, and set the TransformationFile subproperty of the TransformRead property to the clinic.xtr file. This will make sure that the transformation information from clinic.xtr is used whenever we try to read information (which will end up in the ClientDataSet provided by the TXMLTransformProvider component itself). Apart from the transformation information, we should of course also make sure to set the XMLDataFile property to the clinic.xml document itself.
Once we've done this, we can drop a ClientDataSet component and point its ProviderName property to the XMLTransformProvider component. Now, activate the ClientDataSet, and the transformation will start whenever the data from the XMLTransformProvider is requested (and since the ClientDataSet has the PacketRecords property set to -1 by default, it means that the entire XML document will be transformed right away). To see the result data, we have to drop a DataSource and a DBGrid with a DBNavigator (for example) and connect the DataSource to the ClientDataSet and the DBGrid and the DBNavigator to the DataSource, like we've done for year now. The output - at design-time - can be seen in the figure below (a bit similar to the preview from the XML Mapper itself).

We can now use the above client application to browse through the grid as if we were indeed browsing through a regular dataset. A question that may come up at this time is: what if we make changes to the data in the grid? Well, all these changes can be resolved back to the XML document, provided that we call the ClientDataSet.ApplyUpdates method (otherwise the changes will remain local to the ClientDataSet only).
However, we cannot just call the ClientDataSet.ApplyUpdate method, without providing the XMLTransformProvider component with the required information to transform the dataset information back to an XML document. We cannot simply assign the clinic.xtr file as the TransformationFile subproperty of the TransformationWrite property, because the clinic.xtr file contains the transformation information from an XML document to a dataset. We must start the XML Mapper again, load the clinic.xtr file, and then change the choice for the Transformation Direction from "XML to Datapacket" to "Datapacket to XML". Then, we must click on the "Create and Test Transformation" button again, which this times shows an empty XML document, just to verify that the transformation is done. Close that document again, and save the transformation, this time in ClinicToXml.xtr (instead of just clinic.xtr which was used for the transformation from XML).
Now, specify the new ClinicToXml.xtr as value for the TransformationFile subproperty of the TransformationWrite property of the TXMLTransformationProvider component.
Now it's time to add the single line of code for this month. In the Form's OnClose method, I've written this line of code to make sure that the ClientDataSet is sending all changes back to the provider, which in this case is the XMLTransformProvider, which thus results in an updated XML document.

  ClientDataSet1.ApplyUpdates(-1)

And now, if you close your application, the ClientDataSet will send the updates (if any) to the XMLTransformProvider component, which will use the transformation information stored in ClinicToXml.xtr to transform the datapacket back into an XML document. Ready to be processed by another virtual tier in a B2B environment. Delphi 6 BizSnap - makes e-business truly a snap!

For more recent information on Delphi for Win32 XML Programming, check out my Delphi 2010 XML, SOAP & Web Services courseware manual.