Using an XML Document as the Client of a Provider

The TXMLTransformClient component acts as an adapter to let you use an XML document (or set of documents) as the client for an application server (or simply as the client of a dataset to which it connects via a TDataSetProvider component). That is, TXMLTransformClient lets you publish database data as an XML document and to make use of update requests (insertions or deletions) from an external application that supplies them in the form of XML documents.

To specify the provider from which the TXMLTransformClient object fetches data and to which it applies updates, set the ProviderName property. As with the ProviderName property of a client dataset, ProviderName can be the name of a provider on a remote application server or it can be a local provider in the same form or data module as the TXMLTransformClient object. For information about providers, see Using Provider Components.

If the provider is on a remote application server, you must use a DataSnap connection component to connect to that application server. Specify the connection component using the RemoteServer property. For information on DataSnap connection components, see Connecting to the Application Server.

Fetching an XML document from a provider

TXMLTransformClient uses an internal TXMLTransform component to translate data packets from the provider into an XML document. You can access this TXMLTransform component as the value of the TransformGetData property.

Before you can create an XML document that represents the data from a provider, you must specify the transformation file that TransformGetData uses to translate the data packet into the appropriate XML format. You do this by setting the TXMLTransform component's TransformationFile or TransformationDocument property, just as when using a stand-alone TXMLTransform component. If that transformation includes any user-defined nodes, you will want to supply TransformGetData with an OnTranslate event handler as well.

There is no need to specify the source document for TransformGetData, TXMLTransformClient fetches that from the provider. However, if the provider expects any input parameters, you may want to set them before fetching the data. Use the SetParams method to supply these input parameters before you fetch data from the provider. SetParams takes two arguments: a string of XML from which to extract parameter values, and the name of a transformation file to translate that XML into a data packet. SetParams uses the transformation file to convert the string of XML into a data packet, and then extracts the parameter values from that data packet.

Note: You can override either of these arguments if you want to specify the parameter document or transformation in another way. Simply set one of the properties on TransformSetParams property to indicate the document that contains the parameters or the transformation to use when converting them, and then set the argument you want to override to an empty string when you call SetParams. For details on the properties you can use, see Converting XML Documents Into Data Packets.

Once you have configured TransformGetData and supplied any input parameters, you can call the GetDataAsXml method to fetch the XML. GetDataAsXml sends the current parameter values to the provider, fetches a data packet, converts it into an XML document, and returns that document as a string. You can save this string to a file:

Copy Code

var
  XMLDoc: TFileStream;
  XML: string;
begin
  XMLTransformClient1.ProviderName := 'Provider1';
  XMLTransformClient1.TransformGetData.TransformationFile := 'CustTableToCustXML.xtr';
  XMLTransformClient1.TransFormSetParams.SourceXmlFile := 'InputParams.xml';
  XMLTransformClient1.SetParams('', 'InputParamsToDP.xtr');
  XML := XMLTransformClient1.GetDataAsXml('');
  XMLDoc := TFileStream.Create('Customers.xml', fmCreate or fmOpenWrite);
  try
    XMLDoc.Write(XML, Length(XML));
  finally
    XMLDoc.Free;
  end;
end;

Copy Code

XMLTransformClient1->ProviderName = "Provider1";
XMLTransformClient1->TransformGetData->TransformationFile = "CustTableToCustXML.xtr";
XMLTransformClient1->TransFormSetParams->SourceXmlFile = "InputParams.xml";
XMLTransformClient1->SetParams("", "InputParamsToDP.xtr");
AnsiString XML = XMLTransformClient1->GetDataAsXml("");
TFileStream pXMLDoc = new TFileStream("Customers.xml", fmCreate || fmOpenWrite);
__try
{
  pXMLDoc->Write(XML.c_str(), XML.Length());
}
__finally
{
  delete pXMLDoc;
}

Applying updates from an XML document to a provider

TXMLTransformClient also lets you insert all of the data from an XML document into the provider's dataset or to delete all of the records in an XML document from the provider's dataset. To perform these updates, call the ApplyUpdatesmethod, passing in

A string whose value is the contents of the XML document with the data to insert or delete.

The name of a transformation file that can convert that XML data into an insert or delete delta packet. (When you define the transformation file using the XML mapper utility, you specify whether the transformation is for an insert or delete delta packet.)

The number of update errors that can be tolerated before the update operation is aborted. If fewer than the specified number of records can't be inserted or deleted, ApplyUpdates returns the number of actual failures. If more than the specified number of records can't be inserted or deleted, the entire update operation is rolled back, and no update is performed.

The following call transforms the XML document Customers.xml into a delta packet and applies all updates regardless of the number of errors:
Copy Code

StringList1.LoadFromFile('Customers.xml'); nErrors := ApplyUpdates(StringList1.Text, 'CustXMLToInsert.xtr', -1);

Copy Code

StringList1->LoadFromFile("Customers.xml"); nErrors = ApplyUpdates(StringList1->Text, "CustXMLToInsert.xtr", -1);

See Also

Defining Transformations

Converting XML Documents into Data Packets

Using an XML Document as the Source for a Provider