A transzformációs fájl előállításához az xmlmapper.exe segédprogramot használhatjuk, melyet legegyszerűbben a Tools menüből indíthatunk el (XML Mapper menüpont).
A forrás adatcsomagot vagy XML fájlt háromféleképpen adhatjuk meg:
- használjuk a SourceXmlFile property-t, ha a forrás dokumentum a háttértáron van (fájl);
- használjuk a SourceXml property-t, ha a forrás dokumentum a memóriában van (sztringként);
- használjuk a SourceXmlDocument property-t, ha a forrás dokumentumot DOM interfészen keresztül érjük el (IDOMDocument).
Az átalakítás akkor történik meg, amikor kiolvassuk a Data property-t, vagy meghívjuk a TransformXML függvényt. Miután a konvertálás megtörtént használhatjuk a DOM interfészt az új dokumentum eléréséhez, vagy kilvashatjuk az adatcsomagot a ResultDocument property-ből, vagy közvetlenül a Data property-ből, amely az XML sztringet tartalmazza.
Data
Osztály: TXMLTransform
property Data: string;
Ebből a property-ből kiolvashatjuk az eredmény XML sztringet. Mielőtt a property értékét visszakapjuk, megtörténik a konvertálás. Az eredmény nem marad a memóriában, tehát a property újbóli kiolvasása során megint megtörténik a konvertálás.
Ha a forrás XML egy XML dokumentum, és a transzformációs fájl azt mondja meg, hogy ezt hogyan kell adatcsomaggá alakítani, akkor a Data property-ből az adatcsomagot olvashatjuk ki XML formátumban.
Ha a forrás XML egy adatcsomag és a transzformációs fájl azt mondja meg, hogy hogyan kell ezt egy más felépítésű XML dokumentumba konvertálni, akkor a Data property az XML dokumentumot fogja tartalmazni.
TranslateException kivétel keletkezik a Data property kiolvasása közben akkor, ha a SourceXMLFile property-ben rossz fájlnév lett megadva, vagy a property üres sztringet, a SourceXML pedig érvénytelen XML sztringet tartalmaz, vagy a SourceXMLFile és a SourceXML property-k üres sztringet tartalmaznak és a SourceXMLDocument property nincs beállítva.
A transzformációs fájl megadására két lehetőség van:
- ha a transzformációs fájl a háttértáron van, akkor a fájl nevét a TransformationFile property-ben adhatjuk meg.
- ha a transzformációs fájl DOM interfészen keresztül érhető el, akkor ezt TransofrmationDocument property-ben adhatjuk meg.
Ha a TransformationFile property érvénytelen fájlnevet tartalmaz, vagy üres sztringet tartalmaz, miközben a TransformationDocument property nincs beállítva, a Data property kiolvasásakor egy TranslationException kivétel keletkezik.
A konvertálás során minden, a felhasználó által definiált csomópont feldolgozásánál létrejön az OnTranslate esemény, amelyben elvégezhetjük a csomópont konvertálást.
Ha az eredmény egy adatcsomag, akkor a Data property értéke átadható a kliens adatkészlet XMLData property-jének.
EmptyDestinationDocument
Osztály: TXMLTransform
property EmptyDestinationDocument: IDOMDocument;
A transzformációs fájl (dokumentum) tartalmazza a cél dokumentum felépítését, struktúráját. Ezen változtathatunk úgy, hogy ebben a property-ben megadjuk a vázlat dokumentum DOM interfészének objektumát. A dokumentum tartalmazza a csomópontokat, de más adatot nem, mivel ezek a forrás dokumentumból lesznek átvéve.
Ez a property akkor használható ki, ha olyan adatokat is el akarunk helyezni a cél dokumentumban, melyeket a forrás dokumentum nem tartalmaz.
A konvertálás során a property-ben megadott dokumentum nem változik, az eredmény dokumentum DOM objektuma a ResultDocument property-ben érhető el.
ResultDocument
Osztály: TXMLTransform
property ResultDocument: IDOMDocument;
A konvertálás után ebben a property-ben érhető el az eredmény dokumentum DOM interfészének objektuma.
ResultString
Osztály: TXMLTransform
property ResultString: string;
A konvertálás után ebből a property-ből olvasható ki az eredmény XML sztring.
SourceXml
Osztály: TXMLTransform
property SourceXml: string;
A forrás XML sztring formátumban, ami tetszőleges XML dokumentumot vagy adatcsomagot tartalmazhat. A forrás XML-nek természetesen alkalmazkodnia kell a transzformációs fájl tartalmához. Ez azt jelenti, hogy ha egy XML dokumentumot konvertálunk adatcsomaggá, akkor a forrás dokumentumnak alkalmazkodnia kell az adatcsomag szerkezetéhez, illetve ha adatcsomagot konvertálunk XML dokumentummá, akkor a forrás XML-nek tartalmaznia kell a metaadatokat (adatbázis tábla szerkezete) is.
A SourceXML property-t csak akkor veszi figyelembe, ha a SourceXmlFile property nincs beállítva. Ha a SourceXML és SourceXmlFile property-k közül egyik sincs beállítva, akkor a SourceXmlDocument property-t használja. A SourceXML property elsőbbséget élvez a SourceXmlDocument property-vel szemben, még akkor is, ha hibás XML dokumentumot tartalmaz.
SourceXmlDocument
Osztály: TXMLTransform
property SourceXmlDocument: IDOMDocument;
A property a forrás dokumentum DOM interfészének objektumát tartalmazhatja. A forrás dokumentum tartalmára ugyanazok a szabályok vonatkoznak, mint a SourceXML property-nél.
Csak akkor van használva, ha a SourceXMLFile és a SourceXML property-k nincsenek beállítva.
SourceXmlFile
Osztály: TXMLTransform
property SourceXmlFile: string;
Ha a forrás fájlként van tárolva, akkor a fájl nevét ebben a property-ben adhatjuk meg. A forrás dokumentum tartalmára ugyanazok a szabályok vonatkoznak, mint a SourceXML property-nél.
Ez a property elsőbbséget élvez a SourceXML és a SourceXmlDocument property-kkel szemben, még akkor is, ha hibás fájlnevet tartalmaz.
TransformationDocument
Osztály: TXMLTransform
property TransformationDocument: IDOMDocument;
Ebben a property-ben adhatjuk meg annak a dokumentumnak a DOM objektumát, amely az átalakítás szabályait tartalmazza. Ez egy speciális XML dokumentum (transzformációs fájl), melyet az XML Mapper segédprogrammal állíthatunk elő.
A property csak abban az esetben lesz figyelembe véve, ha a TransformationFile property üres sztringet tartalmaz.
TransformationFile
Osztály: TXMLTransform
property TransformationFile: string;
Az átalakítás szabályait tartalmazó speciális XML fájl nevét adhatjuk meg ebben a property-ben. A transzformációs fájl kiterjesztése .xtr. Ezt legegyszerűbben az XML Mapper segédprogrammal állíthatjuk elő.
TransformXML
Osztály: TXMLTransform
function TransformXML(
const SourceXml: string;
const ATransformationFile: string = ''
): string;
Átalakítja a paraméterként megadott XML dokumentumot tartalmazó sztringet a transzformációs fájl tartalma szerint.
Paraméterek
const SourceXml: string
Az átalakítandó XML dokumentumot tartalmazó sztring.
const ATransformationFile: string = ''
A transzformációs fájl neve. Ez a paraméter opcionális, ha nem adjuk meg, akkor a TransformationFile, illetve a TransformationDocument property-ket használja.
Visszatérési érték
A függvény az eredmény XML dokumentumot tartalmazó sztringgel tér vissza.
AfterEachRow
Osztály: TXMLTransform
property AfterEachRow: TRowEvent;
Ez az esemény akkor jön létre, amikor az adatcsomag egy rekordjának konvertálása befejeződött. Felhasználhatjuk ezt az eseményt például egy vagy több mező értékének összesítésére úgy, hogy az adott rekordban lévő értéket hozzáadjuk egy globális változó értékéhez.
type
TRowEvent = procedure(Sender: TObject; Id: string; SrcNode: IDOMNode; DestNode: IDOMNode) of object;
Az Id paraméterben megkapjuk a csomópont azonosítóját. Ezt az azonosítót az XML Mapper programban a Repository lapon adhatjuk meg. Ha nincs megadva, akkor a paraméter értéke egy üres sztring.
Az SrcNode paraméterben kapjuk meg forrás dokumentumban lévő, éppen konvertált csomópont DOM interfészének objektumát. Ez tartalmazhatja a teljes adatcsomagot, egy rekordot, vagy egy mezőt.
A DestNode az átalakított SrcNode DOM interfészének objektumát tartalmazza.
AfterEachRowSet
Osztály: TXMLTransform
property AfterEachRowSet: TRowEvent;
Ez az esemény akkor jön létre, amikor befejeződött a teljes forrás adatcsomag, vagy egy beágyazott detail adatkészlet konvertálása.
BeforeEachRow
Osztály: TXMLTransform
property BeforeEachRow: TRowEvent;
Az adatcsomag egy rekordjának konvertálása előtt jön létre ez az esemény.
BeforeEachRowSet
Osztály: TXMLTransform
property BeforeEachRowSet: TRowEvent;
Ez az esemény azelőtt jön létre, mielőtt a teljes adatcsomag, vagy a beágyazott detail adatkészlet konvertálásra kerülne.
OnTranslate
Osztály: TXMLTransform
property OnTranslate: TTranslateEvent;
Ez az esemény akkor jön létre, amikor egy a felhasználó által definiált csomópont konvertálását kell elvégezni.
type
TTranslateEvent = procedure(Sender: TObject; Id: string; SrcNode: IDOMNode; var Value: string; DestNode: IDOMNode) of object;
Az Id paraméterben megkapjuk a csomópont azonosítóját. Ezt az azonosítót az XML Mapper programban a Repository lapon adhatjuk meg.
Az SrcNode paraméter a konvertálandó csomópont DOM interfészének objektumát tartalmazza. Ha XML dokumentumot konvertálunk adatcsomaggá, akkor a csomópont az Id paraméterben megkapott azonosítóval rendelkező csomópont. Ha adatcsomagot konvertálunk XML dokumentummá, akkor az adatcsomag konvertálandó csomópontjának objektumát tartalmazza.
A Value paraméter tartalmazza az SrcNode fordítását sztring formátumban. Ha XML dokumentumot alakítunk át adatcsomaggá, akkor ez a paraméter az SrcNode csomópontot tartalmazza, amennyiben ez lehetséges. Ekkor a Value property-ben megadhatjuk az adatcsomag megfelelő mezőjének adatait. Ha adatcsomagot alakítunk át XML dokumentummá, akkor a Value paraméter a mező vagy paraméter adatait tartalmazza. Ekkor megadhatjuk a megfelelő csomópontot, ami megfelel az Id paraméterben megkapott azonosítónak. Ez a csomópont tartalmazhat beágyazott csomópontokat is.