30.12.2002

Interní komunikace

Požadavky

soulad s cyklem činnosti
napojování cyklů (přes formuláře vrácené uživateli)
možnost transparentního spojování modulů
API z hlediska modulů

Cyklus činnosti

uživatel posílá (prostřednictvím browseru/mailu/...) požadavek/vyplněný formulář
žádost dostane formulářník/pošťák/...
ten z ní uďělá požadavek na centrálu
centrála rozesílá další požadavky na všechno ostatní
uživatel čeká na odpověď; v případě WWW formuláře mu ji muže vrátit pouze formulářník, a to pouze ta instance, která zpracovala původní uživatelův požadavek

Z toho vyplývá:

formulářníka volá pouze uživatel; všechny informace o odpovědi uživateli dostane formulářník jako odpověď na svou žádost o zpracování
nejjednoduší řešení je úplně zakázat požadavky bez čekání na opověď; pak vznikne stromová struktura komunikace
jelikož uživatel se může rozhodnout neodpovědět, je potřeba buďto
- celý stav session udržovat v putujících požadavcích a formulářích takovým způsobem, aby se po ní nemuselo uklízet, nebo
- nechat putovat pouze session-id, stav udržovat v databázi a definovat, kdy je potřeba session "uklidit".

Návrh API (prostřednictvím příkladu)

Modul, který může být adresát, může vkládat další moduly a sám být vkládán:

		#modul 'modul.php'
		require('komunik.php');
		#vkládání dalších modulů
		require_once('modul1.php');
		...
		require_once('moduln.php');
		#require_once místo require, aby se zamezilo cyklickému vkládání

		...

		kom_register_address('modul.php', 'modul_addr');
		funcion modul_addr($request, &$metadata, &$data) {
			...
			$state	= $kom_send('modul2.php', 'request2', $metadata, $send_data, $receive_data);
			...
			kom_reply(KOM_OK, $metadata, $reply_data);
		}

		...

		#poslední akce v modulu
		kom_listen();

Modul, který pouze vytváří adresu zpracovanou jinde:

		#modul 'adresa.php'
		require('zpracovavajici_modul.php');

Příjemci požadavků budiž adresováni jménem souboru, který je volán (np. pro URL 'http://www.caddis.cz/centrala.php?verbose' je adresa 'centrala.php'); to nemusí nutně být soubor, ve kterém je adresát implementován (a registrován).
Požadavky se posílají voláním 'kom_send(...);', viz.
odpovědi na požadavky se posílají voláním 'kom_reply(...);', viz.
Registrace adresátů:
```
			kom_register_address( 'adresa.php', 'jmeno_funkce' )
			jmeno_funkce( $pozadavek, $metadata, $data )
			{ ... }
		
```
(obě instance řetězce 'jmeno_funkce' v tomto příkladě se pochopitelně musí nahradit něčím jedinečným pro příslušného adresáta; pokud to není úplně jasné, tak se musí obě nahradit *týmž* (novým, jedinečným, platným, ...) jménem funkce)
Volání 'kom_reply(...);' na konci (ani jinde v průběhu) registrobané funkce není vyžadováno; v takovém případě jsou vrácena poslední platná metadata (vstup do fukce, výstup posledního kom_send), nedefinovaná data a stav KOM_NO_REPLY.
Parametry '$request', '$metadata', '$data' volání 'kom_send' je předán adresátovi (v konečném volání 'jmeno_funkce( $request, ... )
Parametry '$metadata', '$data' volání 'kom_reply' jsou předány volajícímu v parametrech '&$metadata', '&$rcv_data'
Parametr '$state' volání 'kom_reply' je vrácen příslušným 'kom_send'.
Stav KOM_ERROR je určen pro uživatelským modulem indikovanou chybu, stav KOM_OK pro řádně dokončené volání. Ostatní stavy jsou generované tímto modulem a indikují různé chyby. Extra data o stavu požadavku, atd ... si prosím posílejte v metadatech/datech

Proč rozdělení na metadata a data

Metadata by měla být perzistentní data o stavu session, ...; formulářník je musí transparentně zapracovat do generovaných stránek (uživatel u prohlížeče by si jich vůbec neměl všimnout); pošťák takovou možnost nemá, ale tam se předpokládá vyšší úroveň spolupráce uživatele.

Struktura předávaných dat

Přepokládá se stromová struktura, uzly jsou pole, synové jsou pojmenování názvy klíčů v poli, listy jsou typu boolean/integer/double/string.

Poznámky

Funkce, (globální) proměnné a top-level položky $metadata a $data s prefixem 'kom_' jsou rezervované pro tento modul.