<?php
/**
 *
 * @author Peter Csubak (chuby)
 * @copyright Peter Csubak (chuby)
 */

/**
 * Ajax alapú kérések feldolgozása alatt előforduló hibák esetén kiváltandó kivétel típus. 
 * Előkészítve a lokalizációra. Működése megfelel a szabályos PEA kivételek működésének, 
 * azaz a változók azonosítóját a szövegben << és >> határolók közzé helyezve, és a változók 
 * azonosítóját mint kulcsot, és a változók értékét mint értéket kell egy asszociatív tömbbe 
 * elhelyezni. Egy privát metódus ezeket a párosításokat a lokalizáció után feloldja, és az így
 * feloldott üzenet kerül a kivétel szövegébe, ami így már akár közvetlenül a felhasználó felé
 * is elküldhető, de természetesen bármikor elkapható a kivétel, és feldolgozható másképp is.
 * Viszont amennyiben ezt nem tesszük meg, akkor például az Ajax kezelőfelületre a kivétel szövege
 * jut el, nyilván a különböző kliensek esetében ez a kliens felépítésétől függ. 
 *
 */
class AjaxException extends Exception{

	/**
	 * PEA kivételek szabályos üzenet lokalizációs metódusa amely az üzenetben megjelenítendő
	 * változók üzenetbe elhelyezéséért is felelős. A metódus két paramétert kap, magát a 
	 * lokalizálatlan üzenetet, és az üzenethez tartozó változókat és azonok azonosítóját
	 * tartalmazó asszociaítv tömböt. Az üzenetet lokalizáltatja a Translator osztály 
	 * Translate metódusával majd párosítja az üzenetben lévő azonosítókat a változó értékekkel
	 * és az így előált üzenetet adja vissza.
	 * 
	 * @param string $msg A lokalizáció kiindulási nyelvén megfogalmazott üzenet szövege.
	 * @param array $params A kivétel üzenetének szövegében megjeleníteni kívánt változók
	 * azonosítóját és az azokhoz tartozó értékét tartalmazó asszociatív tömb.
	 * @return string A lokalizált, és változó behelyettesített üzenet szövege.
	 */
	private function message($msg, $params){
		$mess = Translator::Translate($msg);
		if (is_array($params)){
			foreach ($params as $key => $value){
				$mess = str_replace("<<".$key.">>", $value, $mess);
			}
		}
		return $mess;
	}

	/**
	 * Szabályos PEA kivétel konstruktor amelynek hívásakor az üzenet lokalizálható, úgy hogy közben a
	 * kivétel szövegében megjelenítendő változók sem vesznek el. Ennek módszere, hogy a válozók értékei
	 * és a hozzájuk tartozó (szabadon választott) azonosítók egy asszociatív tömmben kerülnek átadásra a
	 * kivétel konstruktorában. Továbbá a kivétel szövegében << és >> határolók közt megnevezhetőek a 
	 * változók, nyilván az asszociatív tömben megadott azonosítókkal. Ezeket az azonosítókat fogja a 
	 * konstruktor egy privát metódus hívásával kicserélni az értékekre a lokalizáció után.
	 * Ezen felül a konstruktor vár még egy kódot, amivel könnyíthető a kivételek feldolgozása, illetve 
	 * a mobil eszközökre csak a kivétel típusa, és ez a kód kerül elküldésre, az adatmennyiség 
	 * csökkentésének érdekében. (Ez az utóbbi funkció egyelőre még nem él!)
	 * 
	 * @param string $msg A kivétel szövege lokalizáció kiindulási nyelvén. Azonosítókat a szabályos PEA 
	 * kivételeknek megfelelően tartalmazhat.
	 * @param array $params A kivétel szövegében megjeleníteni kívánt változók értékeit, illetve az azokhoz 
	 * tartozó azonosítókat tartalmazhatja. Ha nincsenek ilyenek, akkor az értéke legyen null.
	 * @param int $code A kivétel azonosító kódja. A PEA alkalmazások esetén az API által dobott kivételek
	 * mindegyike 1000 értéknél alacsonyabb értékű, éppen ezért ajánlott az alkalmazás saját kivételeinek
	 * ezen érték feletti kódokat választani, így elválaszthatóak lesznek az API illetve az alkalmazás kivételei.
	 */
	public function __construct($msg, $params = null, $code = 0){
		parent::__construct($this->message($msg, $params), $code);
	}
}
?>