<?php

/**
 * 
 * @author Peter Csubak (chuby)
 * @copyright Peter Csubak (chuby)
 */

/**
 * Az Entity Handler interfész amelyet implementálva lehet definiálni a különböző
 * adatbázisnyelvekhez a magasszintű utasításkészletet. A dokumentáció az interfészeknél
 * megszokott módon az implementáció módjáról szól, viszont bővebb tájékoztatást mind a 
 * használatról, mind az implementálásról a tutotialban lehet olvasni.
 * Fontos megjegyezni, hogy az implementálás során az entity kezelők nem a magasszintű 
 * Entity osztály példányaival, hanem tuple-öket reprezentáló asszociatív tömbökkel dolgoznak
 * ennek megfelelően minthogy ezek nem tartalmazzák a tábláik nevét, így azokat külön kell
 * tárolni. Mind az adatbáziselemek (tuple-ök) beállításához, mind táblájuk nevének beállításához
 * metódusok vannak előírva az adatbázisban, viszont az adatok belső reprezentációja nincs megkötve.
 */
interface EHInterface {
	
	/**
	 * A beszúrás műveletet kell megvalósítania. A beszúrandó adatokat az adatbáziselem határozza 
	 * meg, ennek mindig be kell lennie állítva a metódus meghívása előtt, amennyiben ez mégsem lenne 
	 * így, akkor sem szabad kivételt dobni. A meódus nem kap paramétert, és visszatérésiértke az 
	 * utasítás végrehajtódásának sikerességétől kell függenie. (Hiba esetén hamis, sikeres 
	 * végrehajtás esetén pedig igaz értéket kell visszaadnia.)
	 * 
	 * @return boolean A művelet sikerességét határozza meg.
	 */
	public function insert();
	
	/**
	 * Adatváltoztatás műveletet kell megvalósítania. Ezt teheti UPDATE művelettel, vagy egyszerű 
	 * cserével is. Mindkét megoldás működőképes, tekintve, hogy a metódus meghívása előtt 
	 * rendelkezésre áll az adatbáziselem kiindulási, és célállapota is. Ha a metódus hívás 
	 * előtt ezek az attribútumok mégsem lennének beállítva, akkor ahogyan egyik metódus sem 
	 * ez sem dobhat kivételt. A meódus nem kap paramétert, és visszatérésiértke az 
	 * utasítás végrehajtódásának sikerességétől kell függenie. (Hiba esetén hamis, sikeres 
	 * végrehajtás esetén pedig igaz értéket kell visszaadnia.)
	 * 
	 * @return boolean A művelet sikerességét határozza meg.
	 */
	public function change();
	
	/**
	 * A törlés műveletet kell megvalósítania. A metódus meghívása előtt a törlendő adatbáziselem
	 * be kell legyen állítva. Amennyiben mégsem lenne beállítva, akkor sem szabad kivételt dobnia
	 * a metódsnak. A meódus nem kap paramétert, és visszatérésiértke az 
	 * utasítás végrehajtódásának sikerességétől kell függenie. (Hiba esetén hamis, sikeres 
	 * végrehajtás esetén pedig igaz értéket kell visszaadnia.)
	 * 
	 * @return boolean A művelet sikerességét határozza meg.
	 */
	public function delete();
	
	/**
	 * A lekérdezés műveletet végrehajtó műveletet kell megvalósítania. Az implementálás során a legnagyobb
	 * gondot a where záradék meghatározása jelenti. A metódus háromféleképpen képezheti a where 
	 * záradékot, ez a három mód mind az első paramétertől függ. Az első és legkézenfekvőbb megoldás,
	 * hogy egy egyszerű stringet adunk át, ami a where záradék lesz. Ennek a megodlásnak a 
	 * problémája, hogy csak az adatbázis nyelvének specifikusságait tartalmazó string adható meg.
	 * Ez pedig nem vezet megfelelően magasszintű kódhoz, viszont egyes komplikáltabb esetekben szükség
	 * lehet rá.
	 * A második megoldás, hogy a $where paraméterben egy asszociatív tömböt adunk meg, aminek a kulcsai
	 * és értékei közt megfeleltetünk valamilyen hasonlítóoperátort, ezt természetesen egy másik paraméterben
	 * adjuk meg, és végül definiáljuk a kulcs-érték párok közti logikai kapcsolatokat, szintén egy 
	 * külön változóban. Ez a megoldás már jóval absztraktabb kódot enged meg, viszont korlátozza a 
	 * lehetőségeket. (Ebből kifolyólag már használata nem is javasolt, viszont implementálni még a 
	 * kompatibilitás megörzése érdekében szükséges.)
	 * A harmadik megoldás, hogy a Where osztály példányait kapja meg a metódus, és ezt alakítja át
	 * az adatbázis által értelmezhető formátumúra. Ez utóbbi megoldás a jelenlegi legjobb, így 
	 * ennek helyes implementálására kell megfelelő hangsúlyt helyezni. A Where osztályról és működéséről
	 * bővebben lásd az osztály dokumentációját, illetve a tutorialt.
	 * 
	 * @param mixed $where A where záradékot meghatározó paraméter. Három típusú értéket kaphat
	 * string, tömb, és a Where osztály példányait. A különböző esetek elvárt működéséről lásd fentebb,
	 * illetve a tutorialban.
	 * @param string $logicConn Ha a $where paraméter asszociatív tömb, akkor a kulcs-érték párok
	 * közt értelmezett logikai operátorokat definiálja.
	 * @param string $tester Ha a $where paraméter asszociatív tömb, akkor a kulcsok és az értékek 
	 * közt értelmezett hasonlító operátorokat definiálja.
	 * @param mixed $cols Értéke lehet tömb vagy string, amennyiben string, akkor az alapértékként is
	 * megadott "//dbelementdef\\" érték kell legyen, ezzel a stringgel azt definiáljuk, hogy a 
	 * lekérdezésben résztvevő oszlopokat a beállított adatbáziselem kulcsai definiálják.
	 * Ha pedig az értéke tömb, akkor a tömb elemei definiálják a lekérdezendő oszlopok listáját.
	 * @return array A lekérdezés eredményét reprezentáló tömböt kell visszaadnia, mégpedig úgy, hogy
	 * a tömbben adatbázis elemek szerepeljenek, azaz az eredménytábla tuple-jeit reprezentáló 
	 * asszociatív tömböket. (Ahol az asszociatív tömbök kulcsai az oszlopok neveit az értékek pedig
	 * az egyes kulcsokhoz tartozó aktuális tuple-beli értékeket jelentik.) Amennyiben a lekérdezés
	 * sikertelen, vagy az eredménytáblának nincsenek sorai, akkor egy üres tömbbel kell visszatérnie.
	 */
	public function select($where = "1", $logicConn = "AND", $tester = "=", $cols = "//dbelementdef\\");
	
	/**
	 * TODO: ITT TARTOTTAM!!! (OLVASD VISSZA, HOGY MILYEN STÍLUSÚ AZ EDDIGI DOKSI ÉS CSAK ÚGY FOLYTASD.
	 */
	public function createTable($fields, $id);
	
	public function startTransaction();
	
	public function endTransaction();
	
	public function dropTransaction();
	
	public function isTableExists();
	
	public function setTableName($value);
	
	public function setDBElement($value);
	
	public function setDBElementFrom($value);
	
	public function setDBElementTo($value);
	
	public function setConnectionId($value);
	
	public function getErrors();
	
	public function getWarnings();
	
}
?>