XPartial » History » Version 1

Jakub Jirůtka, 06/26/2011 02:21 PM

1 1 Jakub Jirůtka
h1. XPartial
2 1 Jakub Jirůtka
3 1 Jakub Jirůtka
Server standardně vrací úplnou reprezentaci požadovaného zdroje, tedy se všemi elementy, které jsou pro něj definované. Ty ovšem mohou obsahovat mnoho elementů, které klient aktuálně nevyužije, ale musí vynaložit přenosovou kapacitu a výpočetní výkon pro jejich zpracování. V případě serverových aplikací, které mají k dispozici dostatečný výkon a využívají HTTP(Hypertext Transfer Protocol) cache, to většinou nikterak nevadí, ale u lehkých aplikací, např. v JavaScriptu běžících ve webovém prohlížeči, to může představovat nezanedbatelnou zátěž.
4 1 Jakub Jirůtka
5 1 Jakub Jirůtka
Právě pro tento typ aplikací byl vyvinut XPartial, filtr aplikující restriktivní projekci nad výstupním dokumentem. XPartial vám umožní u každého GET zdroje určit, které elementy chcete zahrnout do výstupu, a to pomocí jednoduché syntaxe inspirované XPath. Požadované elementy se zapisují pomocí XPartial výrazu do URL parametru [[URLParameters#fields|fields]]. 
6 1 Jakub Jirůtka
7 1 Jakub Jirůtka
Příklad: https://kosapi.fit.cvut.cz/api/3/courses/MI-MDW?fields=id,content(code,completion,name)
8 1 Jakub Jirůtka
9 1 Jakub Jirůtka
Vrátí dokument obsahující pouze elementy @/entry/id, /entry/content/code, /entry/content/completion, /entry/content/name@ a všechny jejich předky po cestě ke kořenovému elementu @entry@. Ekvivalentně lze zapsat také jako @fields=id,content/code,content/completion,content/name@.
10 1 Jakub Jirůtka
11 1 Jakub Jirůtka
12 1 Jakub Jirůtka
h2. Syntaxe
13 1 Jakub Jirůtka
14 1 Jakub Jirůtka
Formát XPartial výrazu je založen na syntaxi XPath a je kompatibilní se syntaxí "Partial response":http://code.google.com/intl/cs/apis/gdata/docs/2.0/reference.html#PartialResponse "Google Data protokolu":http://code.google.com/intl/cs/apis/gdata/, ovšem implementuje jen jeho podmnožinu.
15 1 Jakub Jirůtka
16 1 Jakub Jirůtka
* Cesty všech elementů jsou relativní vůči kořenovému elementu.
17 1 Jakub Jirůtka
* Názvy elementů a cesty se oddělují čárkami, např. @updated,content/name@.
18 1 Jakub Jirůtka
* Cesta k zanořenému elementu se skládá z po sobě jdoucích elementů oddělených lomítkem, např. @entry/content/name@.
19 1 Jakub Jirůtka
* Zápis více zanořených elementů na stejné úrovni lze zkrátit pomocí podvýběru mezi kulatými závorkami ( ), např. @content(name,code)@. Toto lze libovolně zanořovat a kombinovat, např. @entry(content/name,content(code,range))@.
20 1 Jakub Jirůtka
* Výběr pouze těch elementů, které obsahují požadovaný/é atribut/y, se zapisuje jako @element[@atribut='hodnota']@, např. @name[@lang='cs']@. Mezi [ ] lze zapsat více podmínek oddělených čárkami, např. @name[@lang='cs',@type='xml']@. 
21 1 Jakub Jirůtka
22 1 Jakub Jirůtka
23 1 Jakub Jirůtka
h2. Pár slov o implementaci
24 1 Jakub Jirůtka
25 1 Jakub Jirůtka
Implementace se skládá z parseru XPartial výrazu a SAX(Simple API for XML) filtru, který je zařazen na výstupu služby, příp. před generátorem cílové datové reprezentace. Tady je nutné si uvědomit, že projekce se aplikuje až po zpracování celého požadavku, tedy až po načtení dat z databáze (či databázové cache) a jejich zpracování. Není proto vhodné ho nadužívat pro složitější filtrování dat, které lze dosáhnout jinými prostředky (např. pomocí [[RSQL]] dotazu). Jelikož _známe své lidi_, raději jsem možnosti XPartial cíleně omezil, aby ho nebylo možné nadužívat nežádoucím způsobem.