# XBUP - Dokumentace: Vzdálené volání funkcí

### Úvod

Tento dokument je součástí dokumentace projektu eXtensible Binary Universal Protocol. Obsahuje popis protokolu pro vzdálené volání funkcí.

O úroveň výše

### Obsah

1. Vzdálené volání funkcí
1.1. Zpracování příkazu
1.1.1. Stav korektního vyhodnocení
1.1.2. Chyby zpracování vstupu
1.1.3. Chyby spuštění příkazu
1.1.4. Chyby zpracování výstupu
1.2. Předávání parametrů
1.2.1. Pojmenované parametry
1.3. Navázání spojení
1.4. Transakční zpracování
2. Konkrétní příklady služeb
2.1. Rozhraní seznamu dostupných funkcí
2.2. Protokol vzdáleného obsahu
3. Odkazy

### 1. Vzdálené volání funkcí

Protokol pro vzdálené volání funkcí definuje způsob předávání parametrů pro vzdálené volání funkcí, vracení výsledků a rozhraní pro zjišťování dostupných funkcí, a to především těch potenciálně vzdálených. Cílem je poskytnout na základech komunikačního protokolu XBUP postavenou alternativu pro protokoly HTTP, XML-RPC, WSDL, CORBA a další.

Běžné datové formáty jsou obalovány funkčnímy předpisy, které definují, jaká operace se nad danými daty má provést. Funkční předpisy jsou realizovány obdobně jako funkce programů, mají předán seznam parametrů a cíl, kam má být vrácen výsledek. Popisováno je tedy především jakým způsobem mají být řešeny výjimky a definován typ výsledků a parametry. Snahou je postavit řešení co nejblíže protokolu tak, aby data reprezentované tímto protokolem mohlo být možné použít přímo jako součást volání.

Řešení by taktéž mělo zahrnovat jak stavovou tak bezstavovou komunikaci a podporu pro transakční zpracování.

Jedním z možných řešení je přímé použití vyhodnocování přijatých dat bez použití jakékoliv speciální konstrukce. Parametry by tak byly ekvivalentní parametrům a atributům použitého bloku. Toto řešení je však nevhodné pro transakční zpracování, kde je vhodné použít zahájení, ukončení a identifikaci transakce v jejím průběhu. Jako řešení tohoto problému by mělo postačit obalit posílaná data vhodným blokem tak, aby bylo možné rozlišit data vrácená běhovou službou od dat vrácených vykonáním dané vzdálené funkce. Tyto obalovací bloky (pro požadavek a pro vrácenou hodnotu) je případně možné po dohodě s klientem vynechat.

### 1.1. Zpracování příkazu

Standardním zpracováním přijatého příkazu je zaslání odpovědi na výstupním kanále. Primárně se zpracovává kořenový blok, volitelně mohou pomocné bloky obsahovat dodatečné parametry zpracování. Způsob vlastního provedení na straně serveru je plně v jeho režii. Odesílání odpovědi může být započato dřívě než je znám/odeslán výsledek. Jakožto návratový kód volání je vráce stavový kód a pro chybové stavy jsou definovány jím odpovídající odpovědi. Chybové stavy vzniklé při zpracování vlastních příkazů nejsou zahrnuty do základní definice vzdáleného volání.

Skupiny chybových zpráv:

- Chyby zpracování vstupu
- Chyby spuštění příkazu
- Chyby zpracování výstupu

### 1.1.1. Stav korektního vyhodnocení

V případě, že server korektně provede zpracování příkazu je vrácen následující stav, který může volitelně obsahovat výstup vrácený provedeným příkazem.

RPCState_OK
any RPCResult

### 1.1.2. Chyby zpracování vstupu

Tyto chybové stavy nastávají při zpracování vstupu před samotným zavoláním obslužného příkazu. Jde o následující chybové stavy:

- Internal Server Error
- Service Unavailable (temporary, removed)
- Redirecting (temporary, single/multiple targets)
- Not Implemented

### 1.1.3. Chyby spuštění příkazu

Tyto chyby nastávají po přečtení vstupu při zpracování obsahu a hledání obsluhy příkazu.

- Bad Request (unknown, reserved, insufficient parameters)
- Forbidden (temporary, required authorization, obsolete)
- Not Found
- Moved

### 1.1.4. Chyby zpracování výstupu

Tyto chyby nastávají po spuštění obsluhy a při zpracování výstupu.

- Terminated (killed, resource overflow)
- Timeout
- Output truncated

### 1.2. Předávání parametrů

Kromě vlastního zavolání funkce je potřeba taktéž i seznam parametrů. Zřejmě bude vhodné odlišit povinné a volitelné parametry.

V úvahu přichází také zohlednění pojmenovaných a nepojmenovaných parametrů. Možná realizace je zde použít přímo mechanismus pro definování typu bloku a rozšíření katalogu NAME pro pojmenování bloků.

### 1.2.1. Pojmenované parametry

Předávané parametry je možné rozšířit o pojmenování...

### 1.3. Navázání spojení

Je možné navázat trvalé spojení se službou poskytování vzdáleného spuštění, a to ve formě posloupnosti...

### 1.4. Transakční zpracování

Pro implementaci transakčního zpracování je použit přístup...

### 2. Konkrétní příklady služeb

Jako součást standardní implementace je k dispozici několik konkrétních rozhraní služeb poskytujících základní funkcionalitu pro přístup například ke katalogu...

### 2.1. Rozhraní seznamu dostupných funkcí

Tato část dokumentace popisuje rozhraní serveru nabízejícího vzdálené provedení funkcí. Funkce jsou popisovány pomocí identifikačních klíčů, pomocí nichž je možné dohledat jejich význam.

### 2.2. Protokol vzdáleného obsahu

Tento protokol by měl poskytnout na principech protokolu XBUP postavenou alternativu k protokolu HTTP. Cílem je poskytnout náhradu pro následující základní funkcionalitu:

- GET(adresa) - čtení hodnoty
- POST(adresa,data) - předání hodnoty dané adrese (SEND,PUT - možná varianty bez odezvy)
- SET(adresa,data) - nastavení hodnoty
- DELETE(adresa) - smazání hodnoty

Adresa je zde reprezentována stejně jako v případě protokolu HTTP jakožto částečně strukturovaný textový řetězec. Data jsou pak reprezentovány jako blok libovolného typu. Prostředí tohoto jednoduchého protokolu předpokládá na vzdálené straně prostředí představované množinou hodnot, na které je možné aplikovat sadu příkazů CRUD (Create, Remove, Update, Delete). Není však požadována žádná atomicita, tudíž hodnota zapsaná/čtená v předchozím kroku nemusí být při příštím čtení vrácena ve stejném tvaru (jde o tzv. bezstavový protokol).

### 3. Odkazy

Seznam souvisejících odkazů:

RPC - Remote Procedure Call [http://en.wikipedia.org/wiki/Remote_procedure_call]
HTTP - HyperText Transfer Protocol [http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol]
CORBA - Common Object Request Broker Architecture [http://en.wikipedia.org/wiki/Corba]
WSDL - Web Services Description Language [http://en.wikipedia.org/wiki/Web_Services_Description_Language]
CRUD -

Homepage: http://xbup.sf.net
License: GNU Free Documentation License (FDL)
Latest update: 2010-01-09