Obsah tohoto dokumentu podléhá ochraně podle zákona o právu autorském, o právech souvisejících s právem autorským a o změně některých zákonů (autorský zákon) ve znění pozdějších změn a doplnění a je určen výhradně k užívání subjekty (oprávněnými uživateli), kterým bylo právo užívání uděleno společností Syntea software group a.s. Obsah dokumentu, ani žádná jeho část nesmí být bez souhlasu společnosti Syntea software group a.s. šířen mimo okruh oprávněných osob nebo používán k jiným účelům, než ke kterým byl určen.
Úvodem ........................................................................................................................................................ 1 2.1 Struktura elementu, model elementu a X-definice ......................................................................... 1
3 3.1 3.2
X-definice ...................................................................................................................................................... 8 Model ............................................................................................................................................ 8 X-skript .......................................................................................................................................... 8
Identifikátory v X-skriptu ....................................................................................................................................... 10 Typy hodnot proměnných a výrazů v X-skriptu ..................................................................................................... 10 Odkazy na hodnoty ve zpracovávaném dokumentu ............................................................................................ 15 Lokální proměnné X-skriptu ................................................................................................................................... 15 Proměnné modelu elementu ................................................................................................................................. 15 Globální proměnné a uživatelské metody............................................................................................................. 16 Předdefinované globální proměnné a konstanty ................................................................................................. 17 Výrazy ..................................................................................................................................................................... 17 Události a akce ....................................................................................................................................................... 18 Specifikace výskytu textových hodnot a atributů ................................................................................................. 19 Kontrola typu hodnot ............................................................................................................................................. 20 Implementované metody pro kontrolu typů ......................................................................................................... 20 Uživatelské typy ..................................................................................................................................................... 25 Tabulky unikátních hodnot a typové metody ID, SET, IDREF a CHKID ................................................................. 25 Tabulka unikátních hodnot bez pojmenovaných položek .................................................................................... 26 Propojení tabulek unikátních hodnot .................................................................................................................... 26 Specifikace výskytu elementů ................................................................................................................................ 26 Template element .................................................................................................................................................. 27 Příkazy X-skriptu .................................................................................................................................................... 27 Implementované metody X-skriptu ....................................................................................................................... 28 Matematické metody ............................................................................................................................................ 42 Externí metody ....................................................................................................................................................... 43 Volby (options) ....................................................................................................................................................... 44 Odkazy na objekty X-definic .................................................................................................................................. 46 Porovnání struktury ............................................................................................................................................... 48 Makra ("xd:macro") ............................................................................................................................................... 49 Nedefinované atributy (xd:attr")........................................................................................................................... 50 Nedefinované elementy ("xd:any") ....................................................................................................................... 51 Ignorované textové hodnoty ................................................................................................................................. 51
Skupiny objektů ........................................................................................................................... 51
3.3.1 3.3.2 3.3.3 3.3.4 3.3.5
3.4
Neuspořádaná skupina ("mixed") ......................................................................................................................... 51 Výběrová skupina ("choice") ................................................................................................................................. 52 Uspořádaná skupina ("sequence") ........................................................................................................................ 52 Specifikace akcí skupiny ......................................................................................................................................... 53 Konstrukční mód pro skupiny ................................................................................................................................ 53
Použití BNF v X-definicích ........................................................................................................................... 57 5.1 BNF gramatika ............................................................................................................................. 57 5.1.1 5.1.2 5.1.3 5.1.4 5.1.5 5.1.6 5.1.7 5.1.8 5.1.9
5.2 1
Produkční pravidla ................................................................................................................................................. 57 Jednoduché (terminální) symboly ......................................................................................................................... 57 Množiny znaků ....................................................................................................................................................... 57 Specifikace opakování komponenty (kvantifikátory) ........................................................................................... 57 BNF výrazy .............................................................................................................................................................. 57 Externí pravidla ...................................................................................................................................................... 58 Definiční sekce - jména a parametry pro externí metody ................................................................................... 58 Poznámky a mezery v zápisu BNF gramatiky ....................................................................................................... 58 Předdefinované metody ........................................................................................................................................ 58
Použití BNF v X-definici ................................................................................................................ 59 Syntea software group a.s.
X-definice 2.0 6 6.1 6.2
Činnost procesoru X-definic ........................................................................................................................ 60 Režim validace (kontroly dat) ....................................................................................................... 60 Režim konstrukce (tvorby XML objektů) ....................................................................................... 61
7
Specifikace X-definic v XML souboru .......................................................................................................... 62
8
Způsob tvorby X-definice podle XML dat .................................................................................................... 62
9
Možnosti nastavení vlastností zpracování .................................................................................................. 65
10
Spuštění režimu validace z příkazové řádky ................................................................................................ 65
11
Spuštění režimu konstrukce z příkazové řádky ........................................................................................... 66
12 Spuštění z Java programu ........................................................................................................................... 66 12.1 Ukázka spuštění v režimu validace ............................................................................................... 69 12.2 Ukázka spuštění v režimu konstrukce ........................................................................................... 69 12.3 Ukázka uložení a načtení souboru s X-definicemi ......................................................................... 70 12.4 Ukázka validace velkých souborů ................................................................................................. 71 13
Kontrola správnosti X-definice .................................................................................................................... 71
14
Přeformátování zdrojového tvaru X-definice .............................................................................................. 71
15 Převod mezi XML schématy a X-definicemi ................................................................................................ 72 15.1 Převod z XML schémat do X-definic ............................................................................................. 72 15.2 Převod z X-definic do XML schémat ............................................................................................. 72 Příloha A: X-definice X-definic ................................................................................................................................ 73 Příloha B: Příklady .................................................................................................................................................. 81 Příloha C: Slovník nejdůležitějších pojmů ............................................................................................................... 82 Příloha D: Odkazy na literaturu .............................................................................................................................. 82
Tabulky Tabulka 1 - Řídicí znaky v datumové masce ......................................................................................................................................... 12 Tabulka 2 - Jména typů hodnot parametrů .......................................................................................................................................... 16 Tabulka 3 - Předefinované globální proměnné a konstanty ................................................................................................................ 17 Tabulka 4 - Klíčová slova pro alternativní zápis operátorů XML .......................................................................................................... 18 Tabulka 5 - Události ............................................................................................................................................................................... 18 Tabulka 6 - Pojmenované parametry, které jsou v XML schématech .................................................................................................. 20 Tabulka 7 - Metody pro kontrolu typů shodných s typy v XML schématech ....................................................................................... 21 Tabulka 8 - Metody pro kontrolu typů, které nejsou v XML schématech ............................................................................................ 22 Tabulka 9 - Metody pro kontrolu typů, které mají z důvodů kompatibility alternativní jméno .......................................................... 24 Tabulka 10 - Základní metody ............................................................................................................................................................... 28 Tabulka 11 - Jména typů X-skriptu a odpovídající ID typů ................................................................................................................... 34 Tabulka 12 - Metody nad objekty všech typů ....................................................................................................................................... 35 Tabulka 13 - Metody nad objekty typu BNFGrammar.......................................................................................................................... 35 Tabulka 14 - Metody nad objekty typu BNFRule .................................................................................................................................. 35 Tabulka 15 - Metody nad objekty typu Bytes ....................................................................................................................................... 35 Tabulka 16 - Metody nad objekty typu Container ................................................................................................................................ 36 Tabulka 17 - Metody nad objekty typu Datetime (datum a čas) ......................................................................................................... 36 Tabulka 18 - Metody nad objekty typu Duration (časový interval)...................................................................................................... 37 Tabulka 19 - Metody nad objekty typu XML Element........................................................................................................................... 38 Tabulka 20 - Metody nad objekty typu Exception ................................................................................................................................ 38 Tabulka 21 - Metody nad objekty typu Input (vstupní soubor) ............................................................................................................ 38 Tabulka 22 - Metody nad objekty typu NamedValue (pojmenovaná hodnota) .................................................................................. 39 Tabulka 23 - Metody nad objekty typu ParseResult ............................................................................................................................. 39 Tabulka 24 - Metody nad objekty typu Output ..................................................................................................................................... 39 Tabulka 25 - Metody nad objekty typu Regex ...................................................................................................................................... 39 Tabulka 26 - Metody nad objekty typu RegexResult ............................................................................................................................ 39 Tabulka 27 - Metody nad objekty typu Report ..................................................................................................................................... 40
Syntea software group a.s.
2
X-definice 2.0 Tabulka 28 - Metody nad objekty typu ResultSet ................................................................................................................................. 40 Tabulka 29 - Metody nad objekty typu Service ..................................................................................................................................... 40 Tabulka 30 - Metody nad objekty typu Statement ............................................................................................................................... 41 Tabulka 31 - Metody nad objekty typu String....................................................................................................................................... 41 Tabulka 32 - Metody nad objekty typuXmlOutStream ......................................................................................................................... 41 Tabulka 33 - Metody matematických funkcí převzatých z java.lang.Math ......................................................................................... 42 Tabulka 34 - Metody matematických funkcí převzatých z java.math.BigDecimal .............................................................................. 43 Tabulka 35 - Typy hodnot předávaných externím uživatelským metodám ......................................................................................... 43 Tabulka 36 - Volby (options) .................................................................................................................................................................. 45
3
Syntea software group a.s.
X-definice 2.0
Změny dokumentu Verze 2.0.0053.190 (8.2.2017) (1)
Doplnena metoda getElementText() (viz 3.2.20)
(2)
Metoda ListOf(typ) je deprecated, nahradte ji list(typ)
(3)
Do interface XXNode jsou doplneny 3 metody: public Object setUserObject(String id, Object obj); public Object removeUserObject(String id); public Object getUserObject(String id);
Verze 2.0.0053.189 (24.1.2017) (1)
Namespace "http://www.syntea.cz/xdef/2.0/instance" nahrazeno "http://www.syntea.cz/xdef/instance". (ale fungují oba) Viz 7.
Verze 2.0.0053.188 (18.1.2017) (1) Doplněny option „ignoreOther“ a „acceptOther“ (viz 3.2.23).
Verze 2.0.0053.183 (2.12.2016) (1) Typ Context je přejmenován na Container (viz 12).
Verze 2.0.0053.181 (24.11.2016) (1) Objekty typu Context mohou vystupovat jako hodnota boolean (viz 12).
Verze 2.0.0053.180 (14.11.2016) (1) V deklaraci typu a v deklaraci uniqueSet se ruší zápis klíčového slova „parse“.
Verze 2.0.0053.178 (10.11.2016) (1) Popis typu se zapisuje zjednodušeně: typ mujTyp string(10, 20); místo původního zápisu typ mujTyp { parse: string(10, 20) } (2) Deklarace uniqueSet pokud musí mít pojmenované položky klíče (i když má klíč jen jednu položku): uniqueSet tabulka {xxx: string(10, 20);} místo původního zápisu uniqueSet tabulka {parse: string(10, 20);} (3) Kontrola unikátních hodnot je rozšířena o složené klíče a další možnosti (viz kapitoly 4.2.13 – 4.2.15 ) uniqueSet tabulka {xxx: string(10, 20);} místo původního zápisu uniqueSet tabulka {parse: string(10, 20);}
Verze 2.0.0053.170 (31.10.2016) (1) Aktualizovaný popis typů, typových metod a implementovaných metod.
Verze 2.0.0053.133 (14.1.2016) (1) Mění se způsob kontroly minimálního a maximálního roku v datumech. Byly zrušeny konstanty XDPROPERTY_CHECKDATE, XDPROPERTYVALUE_CHECKDATE_FALSE a XDPROPERTYVALUE_CHECKDATE_TRUE v cz.syntea.xd.XDConstants, které umožňovaly zapnout/vypnout kontrolu roku s hodnotami aktuální rok +/* 200. To bylo možné nastavit pomocí property nebo pomocí metody XDPool.setCheckdate(boolean). Nyní se kontrola datumu nastavuje pomocí hodnot v property "xdef.minyear" minimální povolený rok a "xdef.maxyear" maximální povolený rok. Viz cz.syntea.xd.XDConstants. XDPROPERTY_MINYEAR, XDPROPERTY_MAXYEAR. Pomocí property "xdef.specdates" (XDPROPERTY_SPECDATES) se nastavuje seznam povolených datumů mimo shora uvedených omezení ve formátu ISO8601 a položky musí být odděleny čárkou. Tyto hodnoty se nastaví do XDPool a zkopírují se do XDDocument. Dynamicky je možné nastavit hodnoty v cz.syntea.xd.XDDocument pomocí metod: setMinYear(int), setMaxYear(int), setSpecialDates(SDatetime[]) a případně přečíst: int getMinYear(), int getMaxYear(), SDatetime[] getSpecialDates() Stejné metody jsou implementovány také v XDPool.
Verze 2.0.0053.123 (25.6.2015) (1) Doplněna metoda hasAttibute a hasAttributeNS do objektu Element a hasNamedItem do Context
Verze 2.0.0053.122 (23.6.2015) (1) Doplněna metoda toContext do objektu Element
Verze 2.0.0053.120 (15.6.2015) (1) Při parsování datumu v X-definici se nyní kontroluje výsledná hodnota tak, že rok musí být v intervalu (aktualni_rok – 200, aktualni_rok + 200 ) nebo datum musí být 3000-12-31 resp. 3000-12-31T23:59:59 nebo 3000-12-31T00:00:00. Tato vlastnost se dá vypnout nastavením property "xdef.checkdate" na "false" (defaultní hodnota je "true").
Verze 2.0.0053.119 (5.6.2015) (1) Doplněny properties "xdef.display" (hodnoty "true", "errors", "false"). Pokud je jastavena hodnota "errors", pak se při výskytu chyby v X-definici zobrazí okénko, ve kterém je možné zdrojový tvar editovat. Pokud je nastaveno "true", pak se editované okénko nastaví vždy. Navíc pokud je nastavena hodnota "true" nebo "errors" současně s "xdef.debug" na hodnotu "true", pak se před spuštěním procesoru X-definic zobrazí okénko, ve kterém je možné nastavit "breakpointy".
Syntea software group a.s.
4
X-definice 2.0 Verze 2.0.0053.065 (18.9.2012) (1) Externí metody je možné volat také plně kvalifikovaným jménem (třida "." metoda). (2) Strukturu elementu je možné porovnat s modelem pomocí "implements" nebo "uses"
Verze 2.0.0053.056 (18.9.2012) (1) Doplněna metoda X-skriptu getElementLocalName (2) xd:any lze deklarovat jako model, tj. může být zapsáno jako přímý potomek X-definice s parametrem xd:name a je možné se na tento model odkazovat sekcí ref.
Verze 2.0.0053.055 (5.9.2012) (1) Doplněn atribut "xd:methods" v X-definici
Verze 2.0.53 (15.7.2011) (1) Doplněna možnost zápisu XDPool do souboru a načtení XDPool ze souboru (2) Možnost proudového zpracování ve validačním režimu
Verze 2.0.52 (16.2.2011) (1) Zápis oktalových čísel (0onnn) byl zrušen.
Verze 2.0.49 (9.3.2009) (1) Dočasná implementace xpath byla nahrazena knihovnou y distribuce java (platí pro verze java 1.5 a další). (2) Doplněn atribut "xd:textcontent", pomocí něhož lze pracovat s obsahem všech spojených textových uzlů, které se na konci zpracování (ale před finally elementu) odstraní z elementu a přidají se na konec elementu. (3) Jedna X-definice v kolekci nemusí mít uvedeno jméno (výhodné např. pokud je XDefPoll tvořen jedinou X-definicí). Tuto X-definici je možné získat y XdefPool objektu metodou getDefinition(""). Na tuto X-definici je možné se odvolat v referenci, která začíná znakem "#". (4) Jsou zavedeny nové typy hodnot: BNFGrammar BNFRule AnyValue (5) BNF gramatika se definuje ve zvláštní sekci <xd:BNFGrammar name=”jméno objektu”> (6) Pravidlo gramatiky se získá příkazem gramatika.getRule("jméno pravidla"). (7) Jako typ hodnoty je možné uvést BNF pravidlo. (8) Ve formátové masce datumu byl doplněn znak "RR" pro dvojmístný rok podle databází (Oracle), "Y" (ISO specifikace) a "YY"- dvojmístný rok, století převzaté z aktuálního data. (9) Bylo změněno a doplněno API pro použití v Java.
Verze 2.0.48 (7.4.2009) (1) V X-skriptu je možné zapsat výskyt zkráceným způsobem (na místo "optional" stačí zapsat "?", místo occurs je možné psát jen výskyt) (2) U metod kde je prázdný seznam parametrů není nutné psát závorky (tj. místo "string()" stačí zapsat „string“). (3) V X- skriptu skupin je možné nahradit speciální atributy jediným atributem "script" (např <xd:choice occurs="*" ref="foo" /> je nyní možné zapsat jako <xd:choice script="*; ref foo" />). (4) Doplněny metody lastDayOfMonth(d) a easterMonday(date). (5) Doplněna třída XsdToXdef pro převod schémat do X-definic.
Verze 2.0.45 (27.8.2008) (1) U metod newElement, newElements, setAttr, getAttr, hasAttr a removeAttr je přidán nepovinný parametr, umožňující specifikovat namespace. (2) Doplněny volby acceptQualifiedAttr, notAcceptQualifiedAttr. (3) V X-skriptu attributu doplněna možnost zapsat akci “match” (4) v sekcích <xd:sequence>, <xd:choice > a <xd:mixed> je nyní možné definovat metody "init" a "finally" pomocí prislušných parametrů. Metody se vyvolají na začátku a na konci zpracování sekvence. (5) U X-definice je možné pomocí atributu "metaNamespace" (ze jmenného prostoru X-definic) specifikovat namespace URI, ktere definuje jmenný prostor pro objekty X-definic (umožňuje psát metajazyky). (6) Doplněny metody uriList(), urlList()
Verze 2.0.43 (18.6.2008) (1) Doplněny metody kontroly typů normString, normToken, normTokenst, ISOlanguage a ISOlanguages (kompatibilní s typy token, normalizedString a language v XML schematech).
Verze 2.0.42 (16.5.2008) (1) Atribut "empty" zůstává jen pro "<xd:mixed>". V sekcích "<xd:choice>" a "<xd:sequence>" je třeba použít atribut "occurs" a v těchto sekcích naopak atribut "empty" nemá být použit. Při použití atributů původním způsobem je hlášeno varování.
5
Syntea software group a.s.
X-definice 2.0 (2) V sekcích "<xd:mixed>", "<xd:choice>" a "<xd:sequence>" je nyní možné použít atribut "create", který obsahuje výraz k vytvoření kontextu, který je použit pro celou sekci (viz odstavec 3.3).
Verze 2.0.41 (26.2.2008) (1) Zápis oktalových čísel v X-skriptu je změněn (původně bylo jako oktalové číslo chápáno číslo s vedoucími nulami, nyní je to číslo začínající nulou, následovanou malým písmenem ‘o’ a sekvencí oktalových cifer (např 0o377 je 255). (2) Doplněny standardní metody List.addItem(obj), context.sort(s) a xparseL(s).
Verze 2.0.38 (30.1.2008) (1) Typová metoda datetimeISO byla přejmenována na ISOdateTime (odpovídá typu dateTime v XML schématech). (2) Typová metoda timePeriod byla přejmenována na ISOduration (odpovídá typu duration v XML schématech) (3) Byly doplněny metody ISOdate, ISOtime, ISOday, ISOmonth, ISOmonthDay, ISOyear a ISOyearMonth (odpovidají následujícím typům v XML schématech: date, time, gDay, gMonth, gMonthDay, gYear a gYearMonth). (4) rozšíření možností masky pro parsování datumu a času: obsahuje-li maska před specifikací řetězce znaků znak ‘?‘, pak následující znak může být kterýkoliv ze znaků uvedených v řetězci.
Verze 2.0.36 (3.12.2007) (1) Klíčové slovo "typem" je nahrazeno slovem "uniqueSet". Z důvodů kompatibility je možno použít obě slova, při použití "typem" se hlásí varování. (2) Doplněna třída s externími metodami pro práci se strukturovanými klíči (cz.syntea.xdef.ext.XExtUtils). Tato třída je určena pro provizorní interní řešení pro projekt BPEL a popis jejích metod je v příslušném dokumentu.
Verze 2.0.29 (12.9.2007) (1) Jsou doplněny metody checkURI, getNamespaceURI, getQnamePrefix, getQnameLocalpart, getQnameURI. (2) Je doplněna typová metoda timePeriod (3) Doplněny metody kontroly typu QnameURI() QnameListURI() (4) Jsou doplněny metody odpovídající kontrole typů z DTD: ENTITY(), ENTITIES(), NMTOKEN, NMTOKENS(), ID(), IDREF(), IDREFS(), NOTATION().
Verze 2.0.24 (24.7.2007) (1) Atribut "setOccurs" v elementech xd:list a xd:includeChildNodes je nahrazen atributem "occurs". (2) V popisu intervalu occurs je možno zapsat "*" místo "0..", "+" místo "1.." a "?" místo "0..1". Je rovněž povolen zápis "n..*" který je ekvivalentní zápisu "n..".
Verze 2.0.4.0 (13.11.2006) (1) "xd:defPool" je nahrazeno "xd:collection" (původní "defPool" je možné použít; hlásí se však varování). Jde jen o přejmenování, funkčnost se nemění. (2) Zápis X-skriptu pro popis textových hodnot ("<xd:text>") do atributu "xd:script" byl nahrazen zápisem přímo do textové hodnoty elementu "xd:text" (původní forma zápisu je možná, způsobí však hlášení varování). (3) Volba "forget" se nyní zapisuje jako akce (původní "options forget" je možné použít, způsobí však hlášení varování). (4) Doplnění option „clearAdoptedForgets“ – tato volba způsobí, že se zruší všechny převzaté akce „forget“ v tomto uzlu včetně podstromu. Akci „Forget je nicméně možné v tomto uzlu specifikovat“. (5) Doplnění konstrukce „<xd:includeChildNodes name = “odkaz na model elementu“ />“ (odkaz na sekvenci potomků elementu). (6) Java třída DefPool byla přejmenována na XDefPool. (7) V X-skriptu X-definic je možné nově specifikovat volbu „ignoreEntities“ a „resolveEntities“. (8) Zaveden pomocný element „<xd:sequence>“. (9) Elementy „<xd:mixed>“, „<xd:sequence>“ a „<xd:choice>“ mohou nyní mít atribut empty=“true“ nebo empty=“false“. (10) Zavedeny metody „trace()“ a „pause()“ jako prostředky pro ladění X-skriptu. (11) Volby copyAttrWhiteSpaces, copyTextWhiteSpaces, notSetAttrCase a notSetTextCase jsou nahrazeny volbami preserveAttrWhiteSpaces, preserveTextWhiteSpaces, preserveAttrCase a preserveTextCase. (12) Rozšíření metody datetime o parametr, kterým se popisuje tvar, do něhož se převedou vstupní data. Maska pro popis tvaru datumu je rozšířena o možnost popsat varianty a případně nastavit defaultní hodnoty. (13) Metody „list“ a „listi“ jsou nahrazeny metodami „tokens“ a „tokensi“ (použití původních metod je povoleno, ale hlásí se warning). (14) Doplněna metoda isDatetime. (15) Doplněna metoda xpath. (16) Doplněny typové metody file(), url(),email(), emailList(),emailDate() (17) Možnost deklarace skupin (choice, mixed, sequence) na root úrovni X-definice a použít odkazy <xd:choice ref=“jméno“/>, <xd:mixed ref=“jméno“ />, <xd:sequence ref=“jméno“ />. (18) Doplněna možnost deklarace seznamu prvků (na root úrovni X-definice) <xd:list name = “jméno”> a použít reference <xd:list ref=“jméno“ />.Seznam lze vložit do choice, mixed nebo sequence. (19) V referencích includeChildNodes a list je možnost uvést atribut „setOccurs“, který způsobí, že výskyt pro všechny referované prvky se nastaví na danou hodnotu. (20) Doplněna typová funkce uri()
Syntea software group a.s.
6
X-definice 2.0 (21) Doplněna událost “default” pro atributy a textové hodnoty (připojená akce musí vrátit string). (22) Implementováno include (liší se od Xinclude podle W3C.org). Činnost je možné řídit volbou „resoveIncludes“ nebo „notResolveIncludes“. Default hodnota je „resoveIncludes“. (23) Globální proměnné a uživatelské metody je možné nyní zapisovat do elementu <xd:declaration> který nahrazuje xd:method a xd:variable. Jména globálních proměnných a funkcí už nemusí začínat znakem ‘$’ (dolar). (24) Rozšíření možností zápisu formátu při parsování a formátování datumu a času. (25) Doplněna možnost napsat „template“ do X-skriptu elementu (pak se celý vnitřek elementu generuje jako fixed, occurs 1..1) (26) Doplněna deklarace kontrolních typů "type" a "typeId" a methody ID a IDREF (viz odst.3.2.13,3.2.14,3.2.15). (27) Klíčové slovo "filter" nahrazeno slovem "match". Z důvodů kompatibility je možno použít obě slova, při použití „filter“ se hlásí varování.
Verze 2.0.3.0 (5.5.2005) (1) Zavedení maker.
Verze 2.0.2.0 (25.01.2005) (1) Zrušení "skupin atributů". (2) Změna spouštění z Java programu.
Verze 2.0.1.0 (23.12.2004) (1) Změna syntaxe - jednotlivé akce oddělené středníky. Úprava a rozšíření některých implementovaných metod. (2) Doplnění rozhraní na externí uživatelské metody. (3) Doplnění základních typů o kontext, soubory vstupu a výstupu, bloby (Bytes) a o obsluhu výjimek dle pravidel Javy. (4) Doplnění filtrů v X-skriptu elementu.
Verze 2.0.0.0 (1) Výchozí verze tohoto dokumentu.
7
Syntea software group a.s.
X-definice 2.0
1
Anotace
Tento dokument je součástí interní projekční dokumentace obecných nástrojů používaných v projektech společnosti Syntea. Obsahuje specifikaci technologie, která je nazývána "X-definice" a je používána u projektů, ve kterých se pracuje se zprávami a dokumenty XML. Dokument není přílohou žádné konkrétní projekční dokumentace. Je součástí obecné interně používané technologie, sloužící pro popis a zpracování strukturovaných zpráv a XML dokumentů. Vzhledem k neustálému rozvoji technologie X-definic je i tento dokument průběžně doplňován a upravován. Dále uvedený text předpokládá, že čtenář je alespoň elementárně seznámen se strukturovaným zápisem pomocí značkového jazyka XML. Pro základní orientaci lze doporučit českou publikaci [1], případně webové odkazy [2] až [4]. X-definice je prostředek, který umožňuje popsat strukturu, obsah a zároveň i zpracování obsahu XML objektů. Xdefinice mohou nahradit existující technologie, užívané pro validaci XML dokumentů, a to jak DTD (definice datových typů), tak i XML schémat. Pomocí X-definic je možné kromě kontroly obsahu popsat i jeho zpracování, takže jimi lze nahradit i XSLT transformace. Oproti klasickým DTD a XML schématům je možné pomocí X-definic propojit validaci XML dokumentu s výkonnými procedurami (tzv. "akce") v jediném objektu. Výhodou X-definic je rovněž skutečnost, že na rozdíl od DTD definice a XML schémat umožňují snazší vytvoření, větší přehlednost i údržbu těchto definic. Programové prostředky pro X-definice byly navrženy tak, aby jimi bylo možné zpracovávat datové soubory s neomezenou velikostí (soubory v reálných projektech mohou mít velikost jednotek až desítek GB). Základní vlastností X-definic je maximální respektování tvaru popisovaných XML dokumentů. X-definice (stejně, jako popisovaná data) je opět XML dokument, jehož struktura se velmi podobá struktuře popisovaných XML objektů. To umožňuje rychle a víceméně intuitivně navrhnout odpovídající X-definici pro danou třídu XML dokumentů. Základní princip při tvorbě X-definic spočívá v tom, že se, v nejjednodušším případě, datové údaje v XML dokumentu nahradí popisem vlastností těchto dat. Na takto vzniklou X-definici se lze dívat jako na metajazyk, kterým se popisují data v XML dokumentech. Při návrhu X-definice lze pak dále popis rozšířit o procesní příkazy, tzv. "akcemi", které zajistí zpracování XML dat.
2
Úvodem
Představme si, že máme nějaký XML element, např. popisující záznam o zaměstnanci, který bude mít tvar:
= = = = = =
Vidíme, že tento záznam obsahuje údaje různého typu (jména, datum, plat, popis kvalifikace). Chceme-li formálně popsat obsah takového elementu, můžeme na místo údajů napsat, zda jsou povinné a popsat jejich typ. Formální popis našeho elementu pak může vypadat následujícím způsobem:
= = = = = =
Vidíme, že tento popis se velmi podobá původnímu tvaru záznamu, jen údaje jsou nahrazeny zápisem ve zvláštním jazyce. Důležité je, že je to opět XML dokument, který se velmi podobá popisovaným datovým objektům. V tomto jazyce, který nazýváme X-definice, je možné popsat formální strukturu XML dat, vlastnosti jednotlivých údajů, jejich výskyt i případně jejich další zpracování. X-definice je možné použít k popisu XML dat, ke kontrole jejich správnosti a obecně i k jejich zpracování i k transformaci do jiného tvaru.
2.1 Struktura elementu, model elementu a X-definice V této kapitole neformálně vyložíme pojmy, se kterými budeme v X-definicích pracovat. V dalších kapitolách pak budou tyto pojmy vysvětleny podrobně. Syntea software group a.s.
1 / 82
X-definice 2.0 Základní koncept, z něhož vychází filosofie modelu elementu v X-definicích, je tzv. struktura XML elementu. Podklad pro její vytvoření získáme z reálného XML elementu tak, že z něho odstraníme všechny datové hodnoty a nahradíme je údaji o jejich výskytu. Nechť popisovaný XML element má tvar:
= = = =
"Karel" "Novák" "13.7.1971" "21700" />
Popis struktury elementu "Osoba" nyní vytvoříme z tohoto elementu tak, že v něm textové hodnoty nahradíme informací o požadovaném výskytu těchto hodnot. Pro povinné údaje použijeme klíčové slovo "required" a pro nepovinné "optional". Dejme tomu, že všechny údaje v atributech jsou povinné, ale výskyt atributu "Plat" je nepovinný. Popis struktury shora uvedeného elementu pak bude mít tvar:
Jmeno Prijmeni DatumNarozeni Plat
= = = =
"required" "required" "required" "optional" />
Jak vidíme, popis struktury se podobá struktuře původního XML dokumentu. Text, kterým jsme nahradili hodnoty v atributech je zvláštní jazyk, který nazýváme X-skript X-definic. Reálná data bývají většinou složitější a mají více elementů. Předpokládejme například element, který popisuje zaměstnance takto: Je to velmi dobrý pracovník.
Uvedený příklad obsahuje nejen prosté elementy s atributy, ale také textovou hodnotu uvnitř elementu ("Je to velmi dobrý pracovník"). Aby bylo možné popsat textové hodnoty uvnitř XML elementů obdobně jako atributy, zapíšeme X-skript přímo jako textovou hodnotu tohoto elementu. Popis struktury pro posledně uvedený příklad může mít tvar: Název vnitřního elementu Název elementu
Název atributu Skript pro textovou hodnotu atributu
optional Skript pro textovou hodnotu elementu
Abychom mohli prohlásit, že dokument je správný (validní), je třeba zkontrolovat nejen výskyt, ale i formální správnost údajů textových hodnot atributů a elementů. Je nasnadě, že je možné doplnit v X-skriptu atributů a textových uzlů popisu struktury elementu další údaje o vlastnostech, které mají splňovat. Bude se jednat o specifikaci kontroly typu dat, která tvoří dohromady s údajem o výskytu tzv. "validační sekci" X-skriptu. Výsledkem kontroly typu dat je logická hodnota "pravda" nebo "nepravda" ("true" nebo "false"), podle toho, zda údaj požadovanou vlastnost splňuje nebo nesplňuje. Budeme-li například požadovat, aby nějaký údaj představoval celočíselnou hodnotu, zapíšeme tuto skutečnost v X-skriptu slovem "int()" (jedná se vlastně o vyvolání metody, která provede 2 / 82
Syntea software group a.s.
X-definice 2.0 příslušnou kontrolu typu, v tomto případě se jedná o kontrolu, zda hodnota atributu je platný zápis čísla). Metody obecně mohou mít i uveden seznam parametrů, které dále určují jejich činnost. Např. ve funkci "int()" lze pomocí parametrů zadat minimální a maximální povolenou hodnotu. Zápisem "int(100,999)" se tak zkontroluje, zda hodnota je číslo v rozsahu 100 až 999. Chceme-li, aby nějaký údaj obsahoval řetězec minimálně o délce 2 a maximálně 30 znaků, můžeme to zapsat jako "string(2,30)". Validační metoda "dateTime('d.M.yyyy')" otestuje datum podle masky v parametru. Implementované kontrolní metody a popis jejich parametrů jsou uvedeny v Tabulka 7 a Tabulka 8. Náš příklad elementu "osoba" může nyní vypadat takto:
= = = =
Shora uvedený příklad představuje objekt, který kromě údajů o výskytu jednotlivých částí obsahuje i údaje o charakteru datových hodnot elementu. Takovému objektu budeme říkat model elementu. Model elementu je element, který představuje popis obsahu elementu ve zpracovávaných datech. Má-li tento popis sloužit v X-definici jako model, musí být zapsán jako přímý potomek X-definice (X-definici zapisujeme do příslušného XML dokumentu pomocí speciálního elementu a model elementu musí být jeho přímým potomkem). Je vlastně vzorem, na nějž je možno se odkazovat v rámci X-definice. Může sloužit jako popis kořenového elementu popisovaných dat, ale je možné se na něj odkázat i z kteréhokoliv místa X-definice a pomocí něho popsat vlastnosti potomků. Samotný model elementu tedy neobsahuje popis výskytu (ten vyplývá z místa, kde je na něj odkaz). Předpokládejme například strukturu, která popisuje takovouto konkrétní bydlící rodinu:
Poznámka: Pro jména speciálních elementů a atributů v X-definicích je používán zápis ve tvaru "xd:jméno". Tento zápis slouží k odlišení objektů X-definic a datových objektů. Zápis "xd:jméno" znamená, že objekt "jméno" patří do jmenného prostoru "xd" (je to tzv. prefix jmenného prostoru). Identifikátor, který definuje jmenný prostor X-definic je "www.syntea.cz/xdef/2.0" a musí být deklarován pomocí atributu xmlns:xd="www.syntea.cz/xdef/2.0" v kořenovém elementu X-definic. V našem textu používáme pro jmenný prostor X-definic prefix "xd". Uživatel může pro X-definice definovat vlastní jiný prefix, např. "p" pomocí atributu xmlns:p="www.syntea.cz/xdef/2.0" v záhlaví X-definice. Jmenné prostory tvoří zvláštní kategorii v technologii XML, která přesahuje rozsah tohoto dokumentu (podrobný popis čtenář nalezne v [1] a [2]). Kompletní příklad X-definice (tj. celý příslušný XML soubor) je uveden v závěru této kapitoly. Chceme-li využít strukturu definovanou odděleně, můžeme použít odkaz, který se zapisuje do X-skriptu pomocí "ref". Modely představují základní kameny, z nichž se skládají X-definice. V jedné X-definici může být popsáno více modelů elementů. V X-skriptu modelu elementu se může pomocí zápisu "ref" vyskytnout odkaz na jiný model, informace o výskytu však musí být uvedena. Všimněme si, že mezi odkazem a validační částí je znak ";" (středník), který v X-skriptu slouží jako oddělovač jednotlivých částí. Středník na konci X-skriptu je nepovinný. X-skript, vztahující se k elementu se zapisuje do zvláštního atributu ze jmenného prostoru X-definic "xd:script". Údaj o minimálním a maximálním počtu výskytů následuje klíčové slovo "occurs", za nímž následují údaje o minimálním a maximálním povoleném počtu výskytů, které jsou odděleny dvěma tečkami (pokud se maximální počet rovná minimálnímu, stačí uvést pouze jeden údaj): <Syn xd:script = "ref Osoba; occurs 0..12" />
Syntea software group a.s.
3 / 82
X-definice 2.0 Tímto způsobem je možné vytvářet agregovanější definice. Uvažujme definici rodiny, která může mít otce, musí mít matku a ne více než 12 dcer či 12 synů. Popis elementu "Rodina" bude vypadat například takto:
Z tohoto zápisu je např. patrné, že na daném místě má být element "Syn", který je však popsán modelem elementu se jménem "Osoba", počet výskytů elementu "Syn" je 0 až 12krát. Do X-skriptu můžeme dále doplnit informace o tom, co se má stát, když některý typový výraz nebude splněn a naopak, je-li typ v pořádku. Skutečnost, že nastala v nějakém okamžiku zpracování určitá podmínka, nazýváme událost. Každé události definované X-definicí je v X-skriptu přiděleno jméno. Zápis, který začíná jménem události, za nímž následuje příkaz v této události vyvolaný, nazýváme akce. Není-li akce popsána, provedou se standardní akce, které jsou definovány pro danou událost zvlášť (např. zkopírování údaje do výsledného objektu, hlášení chyby atd.). Událost, kdy typová kontrola proběhne s kladným výsledkem, má jméno onTrue, opačná událost má jméno onFalse. Mluvíme pak o akci "onFalse", o akci "onTrue" atd. V našem příkladě můžeme například popsat akce, které se provedou na základě kontroly typu atributu "plat": Plat = "optional int(1000,50000); onTrue uloz(); onFalse error('chybný plat')"
Bude-li údaj správný, vyvolá se uživatelská procedura "uloz", nebude-li, pak se vyvolá standardní procedura "error" s parametrem "chybný plat" (která do protokolu o zpracování zapíše údaj o chybě). Není-li k určité události popsána žádná akce, pak procesor provede akci standardní (např. zápis hodnoty do výsledného objektu v případě splněného typového výrazu nebo hlášení příslušné chyby v opačném případě). Všimněme si, že zápis znakového řetězce v metodě "error" je ohraničen apostrofy, zatímco celá textová hodnota atributu je uzavřena do uvozovek. To umožňuje přehledný zápis znakových literálů uvnitř hodnot atributů. Použití obou znaků je možné obrátit: Plat = 'optional int(1000,50000); onTrue uloz(); onFalse error("Chybný plat");'
Model elementu představuje popis elementu, obsahující pro jednotlivé objekty X-skript s validační sekcí a případně s dalšími informacemi (jejich podrobný popis v tomto úvodním odstavci neuvádíme). Připomeňme, že v modelu elementu nemá smysl zápis výskytu, protože je uveden jako kořenový prvek. Pozorný čtenář si asi položí otázku, proč jsme zavedli pojmy "struktura elementu" a "model". Důvodem je skutečnost, že v praxi mnohdy provádíme transformace XML objektů, ve kterých se mění či transformují hodnoty objektů do výsledného tvaru, který se může lišit od tvaru původního, ale jejich struktura je stejná, nebo velmi podobná, takže je vhodné oddělit popis struktury objektu od jeho obsahu. Např. datum může být na vstupu zapsáno několika povolenými způsoby, ale výsledný tvar může být převeden např. na číslo, odpovídající počtu milisekund od 1.1.1990. Jiným typickým příkladem je zpracování XML objektů v databázích, kdy se mohou nahradit některé vstupní hodnoty hodnotami z číselníků apod. Model elementu obsahuje oproti popisu struktury i popis typů a případně akcí v konkrétních instancích objektů. O modelech elementů můžeme pak prohlásit, zda jsou či nejsou odvozeny z určité konkrétní struktury. V praxi se často vyskytují situace, kdy víme, že skupiny potomků určitého elementu tvoří určité skupiny. Popis skupin se vkládá do zvláštních pomocných elementů. Jako příklad si uveďme situaci, kdy známe vlastnosti potomků elementu, ale neznáme jejich pořadí. K popisu takové situace může sloužit tzv. neuspořádaná skupina - "xd:mixed", ve které popíšeme její prvky, které ale mohou být ve skutečnosti libovolně promíchané: <Syn xd:script
Při popisu dat se také může vyskytnout potřeba popsat situaci, kdy se jako prvek smí vyskytnout právě jeden prvek z uvedené množiny. Pro tyto účely slouží tzv. výběrová skupina - "xd:choice". Jestliže se smí např. na nějakém místě popisu vyskytnout prvek, popisující buď fyzickou osobu, nebo firmu, můžeme to popsat pomocí výběrové sekce takto: 4 / 82
Syntea software group a.s.
X-definice 2.0 <Subjekt> <xd:choice>
V některých aplikacích je třeba rozlišit několik modelů elementu podle hodnoty atributu. Pro tyto případy lze v X-skriptu X-definice popsat akci "match": <Subject> <xd:choice>
