* JemnyUvodDoTestoveni

Poznámka: Pro testování je možné nastavit u tagu @@dwr:controller@@ debug na *true*. V takovém případě je generována stránka pro testování příslušných metod na adrese @@/dwr/index.html@@. Je ale důležité, aby nasazená aplikace měla tento debug mód nastavena na *false*.

Poznámka: Pro testování je možné nastavit u tagu @@dwr:controller@@ debug na *true*. V takovém případě je generována stránka na pro testování příslušných metod na adrese @@/dwr/index.html@@. Je ale důležité, aby nasazená aplikace měla tento debug mód nastavena na *false*.

Poznámka: Pro testování je možné nastavit u tagu @@dwr:controller@@ debug na *true*. V takovém případě je generována stránka na pro testování na příslušných metod na adrese @@/dwr/index.html@@. Je ale důležité, aby nasazená aplikace měla tento debug mód nastavena na *false*.

Servletovému kontejneru přijde požadavek, který obsahuje informace ve stylu: "Pošli mi potřebná data pro toto URL: http://ip.adresa.servletové.kontejneru:port/spot/sprava/uzivatele". Spring ví, že s daným URL je provázán konkrétní controller (mapování URL na controllery je ve @@spot-servlet.xml@@), který se stará o to, aby byla uživateli poslaná potřebná data. Controller je vždy nadefinován ve své beaně.

V současné době má [[datový model -> EraModel]] okolo 27 tabulek.

Je více méně na vás, jaké IDE si zvolíte. Ať už [[Netbeans -> http://www.netbeans.org]] nebo [[Eclipse -> http://www.eclipse.org]] (případně [[IntelliJ Idea -> http://www.jetbrains.com/idea/]] nebo jiné) nabízí nepřeberné množství různých pluginů, které nám mají usnadnit práci. Dají se nainstalovat pluginy pro práci s [[Mavenem -> JemnyUvodDoMavenu]], [[Springem -> http://www.springsource.org/]] aj. Tato volba je opravdu jen na vás. Vhodné je použití [[Spring Tool Suite -> http://www.springsource.org/sts ]], což je vývojové prostředí založené na Eclipse, které usnadňuje vývoj aplikací s využitím Spring frameworku, Mavenu atd.

[[Podrobnější popis -> PopisStrukturyAplikace]]

Komunikaci mezi klientskou (javascript) a serverovou částí (java) zajišťuje knihovna DWR. Zprovoznění vyžaduje několik kroků, které nejsou úplně intuitivní, proto je zde popíšu.

h4. Nastavení spot-servlet.xml

V controlleru musí existovat metoda, kterou v javascriptu voláme. V níže uvedeném kódu je i ukázka, jak načíst kontext.

h4. Serverová část
V controlleru musí existovat metoda, kterou v javascriptu voláme. Uvádím zde ukázku načtení kontextu.

[@
public String[] ajaxWordEdit(String wordWord, int wordId, int usageId, int stateId) {
/* nacteni web kontextu */
WebContext ctx = WebContextFactory.get();
HttpServletRequest request = ctx.getHttpServletRequest();

...

if ( /* nastala chyba */ ) {
return null;
}

...

String[] infoToDisplay = {word.getWord(), word.getUrl(), state.getValue(), usage.getName()};
return infoToDisplay;
}
@]

Ukázka javascriptové funkce, která volá metodu [@ajaxWordEdit@] controlleru WordShowController a předává jí hodnoty formulářových polí s ID [@wordWord@], [@wordId@], [@usageId@] a [@stateId@]. Poslední parametr je název callback funkce.

Callback funkce je zavolána po přijetí dat od metody controlleru a nebo po vytikání timeoutu. Přijatá data jsou uložená v parametru funkce (zde: wordData). Chybové stavy jsou řešeny vrácením [@null@] z controlleru.

Javascriptové funkce jsou umístěny v adresáři [@webapp/static/js/ajax/@]. Je nutné napsat jednu funkci pro volání metody controlleru na serveru a druhou funkci (callback), která bude přijímat data vrácená controllerem.

Javascriptová funkce, která volá metodu [@ajaxWordEdit@] controlleru WordShowController a předává jí hodnoty formulářových polí s ID [@wordWord, wordId, usageId@] a [@stateId@]. Poslední parametr je název callback funkce.

@]

Callback funkce je zavolána po přijetí dat od metody controlleru a nebo po vytikání timeoutu.

[@

[@
/*
* Tato funkce odesila data controlleru (WordShowController), do metody ajaxWordEdit a ziskava
* zpet data pres callback updateWord, ktery je definovan nize.
*
* */
function ajaxWordEdit() {
WordShowController.ajaxWordEdit(value("wordWord"), value("wordId"), value("usageId"), value("stateId"), ajaxWordEditCallback);
}

/*
* Callback z metody ajaxWordEdit, naplni stranku novymi daty a obnovi stranku.
*
* */
function ajaxWordEditCallback(wordData) {
if (wordData == null) {
alert("Ke změně slova nedošlo. Nastala chyba.");
return false;
} else {
/* zde bude nejaky kod, ktery provede zmenu na strance */
}
}

@]

h4. Javascript
Javascriptové funkce jsou umístěny v adresáři [@webapp/static/js/ajax/@].

h4. Nastavení v spot-servlet.xml

h3. Ajax a knihovna DWR (Direct Web Remoting)
Komunikaci mezi klientskou (javascript) a serverovou částí (java) zajišťuje knihovna DWR. Zprovoznění vyžaduje několik kroků, které nejsou úplně intuitivní, proto je popíšu níže.

h.4 Nastavení v spot-servlet.xml
Zde je nutné určit, který controller bude obsluhovat volání javascriptových funkcí. V tomto případě musí třída WordShowController obsahovat uvedené metody (ajaxWordEdit, ajaxSeeAlsoAdd,...).

[@
<bean id="wordShowController" class="cz.zcu.kiv.spot.controllers.WordShowController">
<property name="dictionaryManager" ref="dictionaryManager" />
<dwr:remote javascript="WordShowController">
<dwr:include method="ajaxWordEdit" />
<dwr:include method="ajaxSeeAlsoAdd" />
<dwr:include method="ajaxCommentAdd" />
<dwr:include method="ajaxCommentDelete" />
<dwr:include method="ajaxTransDelete" />
<dwr:include method="ajaxTransAdd" />
<dwr:include method="ajaxTransEdit" />
</dwr:remote>
</bean>
@]

h3. Ajax pomocí DWR (Direct Web Remoting)

Nejčastější klávesové zkratky, které mohou výrazným způsobem urychlit práci [[(Attach:)eclipse-zkratky.txt]], další zajímavé informace na http://tipy.kiv.zcu.cz

* Pokud budete chtít přidat stránku se statickým obsahem, využijte služeb ''[@StaticPageControlleru@]''. Nastaveni kontrolerů pro poskytování statických stránek a namapováni jednotlivých kontrolerů na URL se nachází v souboru [@spot-servlet.xml@]

* Snažte se psát v rámci možností [[validní HTML -> http://validator.w3.org/]] a [[validní CSS -> http://jigsaw.w3.org/css-validator/]] kód.

!!!!SVN pluginy pro eclipse
* Subclipse - http://subclipse.tigris.org/
* Subversive - http://www.eclipse.org/subversive/

v případě prioblémů zkuste navštívit http://wiki.eclipse.org/SVN_Howto

Netbeans IDE maji plugin pro SVN defaultně zabudovaný.

Nejčastější klávesové zkratky, které mohou výrazným způsobem urychlit práci [[(Attach:)eclipse-zkratky.txt]]

Nastaveni kontrolerů pro poskytování statických stránek a namapováni jednotlivých kontrolerů na URL se nachází v souboru [@spot-servlet.xml@]

S principiálním popisem začnu od pohledu uživatele.
# Tomu přijde do browseru html kód, které umí browser zobrazit.
# HTML kód se odešle ze servletového kontejneru po příchozím requestu.
# Servletový kontejner vytváří tento zmiňovaný kód ze servletů.
# Ty získává dynamicky překladem jsp stránek na servlety.

A teď, po trochu nudném úvodu, se dostáváme ke kořenu věci, tedy k tomu, jakým způsobem nám Spring zajistí propojení celé aplikace.

* ''spot-servlet.xml'' - [[beany -> http://en.wikipedia.org/wiki/Entity_bean]] controllerů a interceptorů, [[beany -> http://en.wikipedia.org/wiki/Entity_bean]] pro namapovaní konkrétních částí URL patřičným controllerům, načtení ''spot.properties'' přes ''[@PropertyPlaceholderConfigurator@]''.

* ''applicationContext.xml'' - [[beany -> http://en.wikipedia.org/wiki/Entity_bean]] pro transakce, DAO objekty, validátory, načtení ''jdbc.properties'' přes ''[@PropertyPlaceholderConfigurator@]'', beana pro messages aplikace a beana business logiky ''[@DictionaryManager@]''.

h3. Implementace

# Dodržujte prosím ImplementacniKonvence.
# Pro snažší zorientování ve třídách a metodách je doporučeno vygenerování [[javadocu -> http://cs.wikipedia.org/wiki/Javadoc]] příkazem @@mvn javadoc:javadoc@@, který se defaultně vygeneruje do [@./target/site/apidocs@]

!!!!Konfigurační soubory

!!!![[MVC - Model-view-controller -> http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller]]

!!!!interceptory
Jenže než přijde ke slovu konkrétní controller, tak v této beaně jsou přiřazeny 2 interceptory v části properties. Takovýto interceptor má na starosti provést implementovaný kód před tím, než předá řízení controlleru ''[@AdminUserController@]''. (Pozn.: tedy v případě,že interceptory jsou implementované ve spotu.
Intercetpory dědí od ''[@HandlerInterceptorAdapter@]'', který má 3 metody:

*''[@preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)@]''
*''[@postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView)@]''
*''[@afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)@]''.

Ve Spotu je implementována pouze metoda ''[@preHandle()@]''.) Beana interceptoru vypadá podobně jako beana controlleru. Například ''[@AuthInterceptor@]'' se stará o jednoduché řízení přístupu k některým URL na základě práv, která mají jednotlivý uživatelé. Pokud průchod interceptorem skončí návratovou hodnotou true, předá se řízení controlleru ''[@AdminUserController@]'', jinak se (v naší implementaci) provede přesměrování na jiné URL a vyhození vyjímky.

!!!!Controllery

!!!![[DAO -> http://en.wikipedia.org/wiki/Data_Access_Object]]

Snažte se prosím tyto rady dodržovat a nevnášejte do aplikace ještě větší [[(Attach:)spot_stress_controll.jpg | zmatek]], než je v ní nyní ;) Dále by bylo více než vhodné třídy, metody a proměnné pojmenovávat anglicky a češtinu používat pouze v komentářích (bez diakritiky).

h3. Datový model

h3. Implementace aplikace

Dodržujte prosím ImplementacniKonvence. Pro snažší zorientování ve třídách a metodách je doporučeno vygenerování [[javadocu -> http://cs.wikipedia.org/wiki/Javadoc]] příkazem @@mvn javadoc:javadoc@@, který se defaultně vygeneruje do [@./target/site/apidocs@]

* Při změně hodnoty v některém [@property souboru@] je nutný restart [[servletového kontejneru -> NasazeniAplikace]], protože tyto hodnoty se načítají pouze při jeho startu.

Tak toto byla asi nejtěžší část celého seznámení se [[SPOTem -> http://spot.zcu.cz]]. Doufám tedy, že jsem vám alespoň objasnil základní princip fungování aplikace. Na principu tohoto příkladu příkladu více méně funguje celá aplikace.

h3. Logování a komentáře

Zkuste psát minimálně dostačující dokumentační komentáře, které budou vašim následovníkům k něčemu a ne k ničemu. Postupem doby se došlo k doporučení používat ke komentářům sice češtinu, ale bez diakritiky. Vývoj [[SPOTu -> http://spot.zcu.cz]] probíhá na operačním systému windows a linux, každý systém používá defaultně jiné kódování a i přes opratrnost v commitech se vyskytují neustále problémy s diakritikou ve zdrojových kódech. Čeština tedy bez diakritiky!

Stejně tak se snažte dodržet použité jmenné konvence a nevnášejte do aplikace ještě větší [[(Attach:)spot_stress_controll.jpg | zmatek]], než je v ní nyní ;) Dále by bylo více než vhodné třídy, metody a proměnné pojmenovávat anglicky a češtinu používat pouze v komentářích (bez diakritiky).

!!! IDE, nastavení kódování projektu

!!!! Linux
Nastavení kódování celého projektu v IDE je velice důležité. Pod operačním systémem linux je automaticky v IDE Netbeans i Eclipse nastaveno kódování projektu (a všech jeho souborů) na [[UTF8 -> http://cs.wikipedia.org/wiki/UTF-8]].

!!!! Windows
V případě použítí MS windows je situace závislá na konkrétním IDE:
* Netbeans - automaticky nastaveno na [[UTF8 -> http://cs.wikipedia.org/wiki/UTF-8]]
* Eclipse - automaticky na [[Cp1250 -> http://cs.wikipedia.org/wiki/Cp1250]], je doporučená změna na [[UTF8 -> http://cs.wikipedia.org/wiki/UTF-8]]. Pravým tlačítkem kliknout na vybraný projekt [@-> Resource -> Text file encoding@] a vybrat [@Other UTF-8@]. Nebo provést změnu globálně pro všechny projekty: nabídka [@Window -> Preferences -> General -> Workspace -> Text file encoding@] a vybrat [@Other UTF-8@].

h3. Tipy a triky
* tipy a triky pro práci s databázi na stránce [[NavrhAplikace -> NavrhAplikace]]

* Pro rychlejší vývoj na localhostu a hlavně zachování věrohodnosti statistik přístupu je doporučeno zakomentovat v [@./src/main/webapp/WEB-INF/jsp/include/header.jsp@]:
** tag [@<link href="http://www.google.com/uds/css/gsearch.css".../>@]
** tag [@<script src="http://www.google.com/uds/api?file=uds.js&amp;v=1.0"...</script>@]
** tag [@<script src="http://www.google.com/uds/api?file=uds.js&amp;v=1.0&amp;key=AB...</script>@]

/scripts - obsahuje jednoduché skripty pro windows(bat) i linux(sh), spuštění aplikace, vytvoření war souboru, vytvoření dokumentace

Je více méně na vás, jaké IDE si zvolíte. Ať už [[Netbeans -> http://www.netbeans.org]] nebo [[Eclipse -> http://www.eclipse.org]] (případně [[IntelliJ Idea -> http://www.jetbrains.com/idea/]] nebo jiné) nabízí nepřeberné množství různých pluginů, které nám mají usnadnit práci. Dají se nainstalovat pluginy pro práci s [[Mavenem -> JemnyUvodDoMavenu]], [[Springem -> http://www.springsource.org/]] aj. Tato volba je opravdu jen na vás.

Tutoriál pro spustění aplikace naleznete na stránce [[NasazeniAplikace -> NasazeniAplikace]]

h3. SVN

Pro týmovou spolupráci je vhodné zprovoznit SVN pro prostředí [[Netbeans -> http://www.netbeans.org]]. Pokud nemáte operační systém Windows Vista 64-bit, u kterého se zprovoznění nepovede, je to velmi jednoduché:
* otevřete [[Netbeans IDE -> http://www.netbeans.org]]

!!!!Odkazy
* http://cs.wikipedia.org/wiki/Subversion
* http://merlin.fit.vutbr.cz/wiki/index.php/SVN_tutoriál

!!!!Nastavení SVN pro [[Netbeans -> http://www.netbeans.org]]

Tutoriál pro spustění aplikace naleznete na stránce [[NasazeniAplikace -> NasazeniAplikace]]

h3. Nastavení IDE

!!!![[Eclipse -> http://www.eclipse.org]]

Pro zdárný běh aplikace je potřeba nakonfigurovat pár [[konfiguračních -> NasazeniAplikace]] souborů pro local:

[@$ sudo apt-get install postgresql #yum install postgresql
$ sudo passwd postgres #Změní heslo uživaleli 'postgres'
$ sudo /etc/init.d/postgresql-* restart #Restartuje server
$ su postgres #Přihlášení jako administrátor databáze

$ createdb postgres #vytvoří databázi nazvanou 'postgres'

Návod instalce je určen pro linux. Práce v ''psql'' konzoli je nezávislá na platformě.

[@$ sudo apt-get install postgresql #yum install postgresql

Návod instalce je určen pro linux. Práce v ''psql''konzoli je nezávislá na platformě.

[@sudo apt-get install postgresql #yum install postgresql
$ sudo passwd postgres #Změní heslo uživaleli 'postgres'
$ sudo /etc/init.d/postgresql-* restart #Restartuje server
$ su postgres #Přihlášení jako administrátor databáze

$ createdb postgres #vytvří databázi nazvanou 'postgres'
$ psql postgres #přihlášení do databáze 'postgres'
postgres=# ALTER USER postgres with password 'postgres'; #nastaví heslo uživateli 'postgres' v databázi na 'postgres'
postgres=# \i spot.sql #provedení příkazů ze souboru, př. nahraje dump databáze projektu

@]

/sudo apt-get install postgresql
\sudo passwd postgres #Změní heslo

h3. Instalace a spuštění postgresql databáze
''sudo apt-get install postgresql''
''sudo passwd postgres #Změní heslo''

/target - defaultní adresář pro vygenerovaný war soubor a vygenerovanou dokumentaci
/site - adresář pro vygenerované stránky projektu
/apidocs - pro javadoc

/logs - sem se mohou(podle nastavení v log4j.properties) zapisovat [[logy -> JemnyUvodDoLogovani]] aplikace

/src - adresář obsahuje všechny zdrojové a [[konfigurační -> NasazeniAplikace]] soubory.

/WEB-INF - adresář jako takový obsahuje [[konfigurační -> NasazeniAplikace]] soubory pro spring + ''web.xml''.

/properties - obsahuje [[konfigurační -> NasazeniAplikace]] properties soubory

* [[Java -> http://java.sun.com/javase/downloads/index.jsp]] 5.0 nebo vyšší
* [[Maven -> http://maven.apache.org/download.html]], ideálně 2.0.x
* [[Postgresql -> http://www.postgresql.org/download/]] 8.1 - na toto pozor! Při mém 1. [[deploy -> NasazeniAplikace]] běžel SPOT nad postgres 7.4 a kvůli mě a mým předchůdcům se překlápěl na 8.1...- a to je více méně vše.

Nyní to záleží na zvycích vývojáře jak to vyřeší se servletovým kontejnerem.
# volbou je využívat pluginu do mavenu jetty, o používání více v dokumentu popisTechnologii.
# volbou je mít "nainstalovaný" servletový kontejner [[Tomcat -> http://tomcat.apache.org ]] a nebo Jetty, na kterých SPOT určitě běží. A poslední možností je používat spouštění aplikace z IDE. Předchůdci vyvíjeli v eclipse a zásadně buildili z něj.


Pro zdárný běh aplikace je potřeba nakonfigurovat pár [[konfiguračních -> NavrhAplikace]] souborů pro local:

A nebo v případě nějaké chyby se do mv vloží ''Object'' reprezentující chybový stav. Tohoto je pak využito v kódu jsp stránek, kdy v případě, že došlo k nějaké chybě se vypíše chybová hláška například "''error.unknow''" na místo toho, aby se vypsala nekompletní data. Řetězec error.unknow je k uložen v souborech ''messages_xx.properties'' v různých [[jazykových -> LokalizaceAplikace]] mutacích.

/sql - obsahuje sql scripty pro vytvoření potřebných [[tabulek a sekvencí -> NavrhAplikace]].

/classes - obsahuje soubory s [[lokalizačními řetězci -> lokalizaceAplikace]].

/test/java/cz/zcu/kiv/spot - adresář obsahující veškeré [[testy -> JemnyUvodDoTestoveni]] aplikace.

Je potřeba mít [[nainstalovaný -> NasazeniAplikace]]:
* [[Java -> http://java.sun.com/javase/downloads/index.jsp]] 5.0 nebo vyšší
* [[Maven -> http://maven.apache.org/download.html]], ideálně 2.0.x
* [[Postgresql -> http://www.postgresql.org/download/]] 8.1 - na toto pozor! Při mém 1. deployi SPOT běžel nad postgres 7.4 a kvůli mě a mým předchůdcům se překlápěl na 8.1 ...

Je více méně na vás, jaké IDE si zvolíte. Ať už NetBeans nebo Eclipse (případně IntelliJ Idea nebo jiné) nabízí nepřeberné množství různých pluginů, které nám mají usnadnit práci. Dají se nainstalovat pluginy pro práci s [[Mavenem -> JemnyUvodDoMavenu]], Springem aj. Tato volba je opravdu jen na vás.

h3. Jemné seznámení s datovým modelem

V současné době má [[datový model -> NavrhAplikace]] okolo 20 tabulek. Avšak v blízké či vzdálenější budoucnosti je v plánu tento stav o pár dalších rozšířit.

S principiálním popisem začnu od pohledu uživatele. Tomu přijde do browseru html kód, které umí browser zobrazit. HTML kód se odešle ze servletového kontejneru po příchozím requestu. Servletový kontejner vytváří tento zmiňovaný kód ze servletů. Ty získává dynamicky překladem jsp stránek na servlety. A teď, po trochu nudném úvodu, se dostáváme ke kořenu věci, tedy k tomu, jakým způsobem nám Spring zajistí propojení celé aplikace.
Servletovému kontejneru přijde požadavek, který obsahuje informace ve stylu: "Pošli mi potřebná data pro toto URL: http://ip.adresa.servletové.kontejneru:port/spot/sprava/uzivatele". Spring ví, že s daným URL je provázán konkrétní controller, který se stará o to, aby byla uživateli poslaná potřebná data. Controller je vždy nadefinován ve své beaně.

dodrzovat ImplementacniKonvence

h4. Zpracování vyjímek
* ExceptionHandling

* JemnyUvodDoLogovani

* JemnyUvodDoTestoveni

Je potřeba mít nainstalovaný:
- Java 5.0 nebo vyšší
- Maven, ideálně 2.0.x
- Postgresql 8.1 - na toto pozor! Při mém 1. deployi SPOT běžel nad postgres 7.4 a kvůli mě a mým předchůdcům se překlápěl na 8.1 ...
- a to je více méně vše. Nyní to záleží na zvycích vývojáře jak to vyřeší se servletovým kontejnerem. 1. volbou je využívat pluginu do mavenu jetty, o používání více v dokumentu popisTechnologii. 2. volbou je mít "nainstalovaný" servletový kontejner Tomcat a nebo Jetty, na kterých SPOT určitě běží. A poslední možností je používat spouštění aplikace z IDE. Předchůdci vyvíjeli v eclipse a zásadně buildili z něj.

Je více méně na vás, jaké IDE si zvolíte. Ať už NetBeans nebo Eclise (případně IntelliJ Idea nebo jiné) nabízí nepřeberné množství různých pluginů, které nám mají usnadnit práci. Dají se nainstalovat pluginy pro práci s Mavenem, Springem aj. Tato volba je opravdu jen na vás.

h3. Jemné seznámení s datovým modelem.

V současné době má datový model 20 tabulek. Avšak v blízké či vzdálenější budoucnosti je v plánu tento stav o pár dalších rozšířit.
TODO pridat datovy model

h3. Lokalizace v JSP
Samostatná stránka věnovaná [[lokalizaci aplikace -> LokalizaceAplikace]] SPOT.

Bylo by více než vhodné, aby jste při práci s třídami, na kterých budete pracovat, k nim rovnou psali alespoň základní testy. Netvrdím, že můj nástřel testů je dostačující, na druhou stranu ho lze použít jako vodítko.

* TestovaciScenare

Zkuste psát minimálně dostačující dokumentační komentáře, které budou vašim následovníkům k něčemu a ne k ničemu. Stejně tak se snažte dodržet použité jmenné konvence a nevnášejte do aplikace ještě větší [[(Attach:)spot_stress_controll.jpg | zmatek]], než je v ní nyní ;) Dále by bylo více než vhodné třídy, metody a proměnné pojmenovávat anglicky a češtinu používat pouze v komentářích.

Pro windows: [[(Attach:)turorial-spot-app-spusteni.zip]] [0,4 MB]

h3. Nastavení SVN pro [[Netbeans -> http://www.netbeans.org]]

Pro týmovou spolupráci je vhodné zprovoznit SVN pro prostředí Netbeans. Pokud nemáte operační systém Windows Vista 64-bit, u kterého se zprovoznění nepovede, je to velmi jednoduché:

Pro windows i pro unix: [[(Attach:)turorial-spot-win32-ide-eclipse.zip]] [1,4 MB]

Pro unix: [[(Attach:)tutorial-spot-unix-ide-netbeans.zip]] [0,7 MB]

h3. Nastavení IDE [[Eclipse -> http://www.eclipse.org]]
[[(Attach:)turorial-spot-win32-ide-eclipse.zip]] [1,4 MB]

h3. Spuštění aplikace
[[(Attach:)turorial-spot-app-spusteni.zip]] [0,4 MB]

Pro týmovou spolupráci je vhodné zprovoznit SVN pro prostředí NetBeans. Pokud nemáte operační systém Windows Vista 64-bit, u kterého se zprovoznění nepovede, je to velmi jednoduché:

h3. Nastavení SVN pro NetBeans

Pro týmovou spolupráci je vhodné zprovoznit SVN pro prostředí NetBeans. Pokud nemáte operační systém Windows Vista 64-bit, u kterého se sprovoznění nepovede, je to velmi jednoduché:
* otevřete NetBeans IDE
* v Menu/Versioning klikněte na Checkout
* ponechejte defaultní nastavení a stiskněte OK
* opakujte bod 2
* nastavte cestu uložiště, jméno a heslo

* LogovaciKonvence

[@<bean id="urlAbcMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping"
abstract="false" singleton="true"

''./src/main/resources/WEB-INF/classes/log4j.properties'' - nastavení cesty, kam se budou zapisovat logy, případně velikost logovacího souboru.

/properties - obsahuje konfigurační properties soubory

* projekt, application
* značka, tag, kategorie
* úzus, usage
* odkaz, link
* typ zdrojů, source usages
* komentář, comment
* uživatel, user

* SPOT - Slovník Překladů Odborné terminologie.
* úzus - například angličtina může mít několik odnoží. Například je rozdíl mezi anglickou a americkou angličtinou. Tyto varianty angličtin pak nazveme úzusy.

Nyní tedy konečně přichází ke slovu ''[@AdminUserController@]''. Tento implementuje rozhraní ''Controller'', který má k naimplementování pouze 1 metodu, tou je ''[@handleRequest(HttpServletRequest request, HttpServletResponse response)@]'', která navrací ''[@ModelAndView(mv)@]''. ''[@ModelAndView@]'' slouží k předávání objektů získaných například z databáze na základě požadavku uživatele. Tyto objekty se pak předají do patřičných jsp stránek a zobrazí uživateli. Patřičné jsp strámky jsou vždy uvedeny uvnitř controlleru. Příklad: [@mv = new ModelAndView("/WEB-INF/jsp/admin/admin-users.jsp")@];

Tento kousek kódu říká, že do daného Listu, se mají uložit všichni uživatelé. ''[@DictionaryManager@]'' je do ''[@AdminUserControlleru@]'' injektován Springem, proto je v controlleru tento setter:

Jenže než přijde ke slovu konkrétní controller, tak v této beaně jsou přiřazeny 2 interceptory v části properties. Takovýto interceptor má na starosti provést implementovaný kód před tím, než předá řízení controlleru ''[@AdminUserController@]''. (Pozn.: tedy v případě,že interceptory jsou implementované ve spotu. Intercetpory dědí od ''[@HandlerInterceptorAdapter@]'', který má 3 metody - ''[@preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)@]'', ''[@postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView)@]'' a ''[@afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)@]''. Ve Spotu je implementována pouze metoda ''[@preHandle()@]''.) Beana interceptoru vypadá podobně jako beana controlleru. Například ''[@AuthInterceptor@]'' se stará o jednoduché řízení přístupu k některým URL na základě práv, která mají jednotlivý uživatelé. Pokud průchod interceptorem skončí návratovou hodnotou true, předá se řízení controlleru ''[@AdminUserController@]'', jinak se (v naší implementaci) provede přesměrování na jiné URL a vyhození vyjímky.

Nyní tedy konečně přichází ke slovu ''[@AdminUserController@]''. Tento implementuje rozhraní ''Controller'', který má k naimplementování pouze 1 metodu, tou je ''[@handleRequest(HttpServletRequest request, HttpServletResponse response)@]'', která navrací ModelAndView(mv)@]''. ''[@ModelAndView@]'' slouží k předávání objektů získaných například z databáze na základě požadavku uživatele. Tyto objekty se pak předají do patřičných jsp stránek a zobrazí uživateli. Patřičné jsp strámky jsou vždy uvedeny uvnitř controlleru. Příklad: [@mv = new ModelAndView("/WEB-INF/jsp/admin/admin-users.jsp")@];
A nebo v případě nějaké chyby se do mv vloží ''Object'' reprezentující chybový stav. Tohoto je pak využito v kódu jsp stránek, kdy v případě, že došlo k nějaké chybě se vypíše chybová hláška například "''error.unknow''" na místo toho, aby se vypsala nekompletní data. Řetězec error.unknow je k uložen v souborech ''messages_xx.properties'' v různých jazykových mutacích.

Tento kousek kódu říká, že do daného Listu, se mají uložit všichni uživatelé. DictionaryManager@]'' je do adminUserControlleru@]'' injektován Springem, proto je v controlleru tento setter:

Zpět k volání [@dictionaryManager.getAllUsers()@]. Podíváme-li se na implementaci rozhraní ''[@DictionaryManager@]'', nalezneme tam tento kód:

Z něho vidíme, že je třeba jít do datové vrstvy aplikace k DAO rozhraním a jejich implementaci. Implementace ''[@UserDaoImpl@]'' je ta třída, která už komunikuje s databází.(Pozn.: S db komunikuje přímo jdbc, ale naše DAO jsou poslední z pohledu aplikace.) Pojďme se podívat jak přesně funguje.

Metoda [@getAllUsers()@] je přehledná. Nejdříve je popsán string, který představuje SQL dotaz nad databází. Následuje return, který navrací volání dotazu sql za použití [@UserRowMapper()@]. ''[@UserRowMapper@]'' je vnitřní privátní třída třídy ''[@UserDaoImpl@]'' a zajišťuje namapování jednotlivých záznamů z tabulky "users" na doménové objekty ''User''.

Cílem je, aby se veškeré zobrazované statické texty načítaly z ''messages_xx.properties'', kde xx představuje danou jazykovou mutaci(cz, en a de). Tyto texty se snadno vypíší například přes [@<fmt:message key="index.jakPrispet.popis" />@], kde ''index.jakPrispet.popis'' je záznam v messages_xx.properties a má přiřazen daný přeložený řetězec, který se vypíše. Volba příslušné jazykové mutace je závislá na aktuální uživatelově volbě.

* ''web.xml'' - kde jinde bych měl začít, když než u tohoto souboru. Jde o vstupní od do každé webové aplikace napsané v Javě. Definují se zde základní listenery, ''context-param'', ''servlet-mapping'', ''taglibs'' a další.

* ''spot-servlet.xml'' - beany controllerů a interceptorů, beany pro namapovaní konkrétních částí URL patřičným controllerům, načtení ''spot.properties'' přes ''[@PropertyPlaceholderConfigurator@]''.

* ''applicationContext.xml'' - beany pro transakce, DAO objekty, validátory, načtení ''jdbc.properties'' přes ''[@PropertyPlaceholderConfigurator@]'', beana pro messages aplikace a beana business logiky ''[@DictionaryManager@]''.

/doc - tento adresář by měl obsahovat dokumentaci...
/logs - sem se mohou(podle nastavení v log4j.properties) zapisovat logy aplikace
/sql - obsahuje sql scripty pro vytvoření potřebných tabulek a sekvencí.
/src - adresář obsahuje všechny zdrojové a konfigurační souboru.
/main
/java/cz/zcu/kiv/spot - adresář, kde se nachází veškeré zdrojové kódy.
/resources/static - adresář s javascripty, potřebnými obrázky a kaskádovými styly.
/WEB-INF - adresář jako takový obsahuje konfigurační soubory pro spring + ''web.xml''.
/classes - obsahuje soubory s lokalizačními řetězci.
/jsp - obsahuje veškeré jsp soubory v daných podadresářích.
/properties - obsahuje velkou část konfiguračních properties souborů
/tld - potřebné tag libraries..
/test/java/cz/zcu/kiv/spot - adresář obsahující veškeré testy aplikace.
/temp - obsahuje vzorové soubory pro import slov ze souboru a je pracovním adresářem při hromadném importu slov.

Pro zdárný běh aplikace je potřeba nakonfigurovat pár souborů pro local:

''./src/main/resources/WEB-INF/properties/jdbc.properties'' - přístup k postgresql(heslo a jméno databáze a uživatele, který k ní má práva)

''./src/main/resources/WEB-INF/classes/log4j.properties'' - nastavit cestu, kam se budou zapisovat logy, případně velikost logovacího souboru.

''./src/main/resources/WEB-INF/classes/spot.properties'' - různé možnosti nastaveni vlastní aplikace.

h3. Logování
Když se dostanete k práci s neokomentovanou třídou, dookomentujte jí. Času je na to třeba minimum a když se nám pak předhodí log ze serveru s tím, že aplikace padá tehdy a tehdy, tak se alespoň bude dát z logu poznat, co se před spadnutím aplikace dělo a také proč spadla. Z toho plyne, ze nebude problém chybu opravit. '''Čtení logu má být jako čtení knihy s příběhem, v každé části by mělo být jasné co se děje.'''

h3. Testování
Bylo by více než vhodné, aby jste při práci s třídami, na kterých budete pracovat, k nim rovnou psali alespoň základní testy. Netvrdím, že můj nástřel testů je dostačující, na druhou stranu ho lze použít jako vodítko.

Pokud budete chtít přidat stránku se statickým obsahem, využijte služeb ''[@StaticPageControlleru@]''.

/main
/java/cz/zcu/kiv/spot - adresář, kde se nachází veškeré zdrojové kódy.
/resources/static - adresář s javascripty, potřebnými obrázky a kaskádovými styly.
/WEB-INF - adresář jako takový obsahuje konfigurační soubory pro spring + ''web.xml''.
/classes - obsahuje soubory s lokalizačními řetězci.
/jsp - obsahuje veškeré jsp soubory v daných podadresářích.
/properties - obsahuje velkou část konfiguračních properties souborů
/tld - potřebné tag libraries..
/test/java/cz/zcu/kiv/spot - adresář obsahující veškeré testy aplikace.

h3. Konfigurace aplikace

Pro zdárný běh aplikace je potřeba nakonfigurovat pár souborů pro local:
./src/main/resources/WEB-INF/properties/jdbc.properties - přístup k postgresql(heslo a jméno databáze a uživatele, který k ní má práva)
./src/main/resources/WEB-INF/classes/log4j.properties - nastavit cestu, kam se budou zapisovat logy, případně velikost logovacího souboru.
./src/main/resources/WEB-INF/classes/spot.properties - různé možnosti nastaveni vlastní aplikace.

h1. Jemný úvod od aplikace

Tento dokument má za cíl sloužit jako pomocník pro "rychlé" zorientování se ve aplikaci a její architektuře.


h3. Co je potřeba mít nainstalované a v jaké verzi
Na tuto část je třeba dát si pozor. Když jsme projekt přebíral já, tak to vypadalo tak, že jsem se sešel s mým předchůdcem a ten mi řekl, že to běží nad Postgresql, používá se tam to to to a to, ale už neřekl nic o verzích. To, že jsme vyvíjel na nejnovějších verzích se mi následně vymstilo při deployi aplikace o půl roku později... Věnujte tedy prosím tomuto dokumentu pozornost a nezapomeňte jej pravidelně aktualizovat.

Je potřeba mít nainstalovaný:
- Java 5.0 nebo vyšší
- Maven, ideálně 2.0.x
- Postgresql 8.1 - na toto pozor! Při mém 1. deployi SPOT běžel nad postgres 7.4 a kvůli mě a mým předchůdcům se překlápěl na 8.1 ...
- a to je více méně vše. Nyní to záleží na zvycích vývojáře jak to vyřeší se servletovým kontejnerem. 1. volbou je využívat pluginu do mavenu jetty, o používání více v dokumentu popisTechnologii. 2. volbou je mít "nainstalovaný" servletový kontejner Tomcat a nebo Jetty, na kterých SPOT určitě běží. A poslední možností je používat spouštění aplikace z IDE. Předchůdci vyvíjeli v eclipse a zásadně buildili z něj.

Pro zdárný běh aplikace je potřeba nakonfigurovat pár souborů pro local:
./src/main/resources/WEB-INF/properties/jdbc.properties - přístup k postgresql(heslo a jméno databáze a uživatele, který k ní má práva)
./src/main/resources/WEB-INF/classes/log4j.properties - nastavit cestu, kam se budou zapisovat logy, případně velikost logovacího souboru.
./src/main/resources/WEB-INF/classes/spot.properties - různé možnosti nastaveni vlastní aplikace.


h3. IDE
Je více méně na vás, jaké IDE si zvolíte. Ať už NetBeans nebo Eclise (případně IntelliJ Idea nebo jiné) nabízí nepřeberné množství různých pluginů, které nám mají usnadnit práci. Dají se nainstalovat pluginy pro práci s Mavenem, Springem aj. Tato volba je opravdu jen na vás.

h3. Jemné seznámení s datovým modelem.
V současné době má datový model 20 tabulek. Avšak v blízké či vzdálenější budoucnosti je v plánu tento stav o pár dalších rozšířit. Pokud se podaří, bude externě dodáno schéma, na kterém bude jasně vidět, co s čím a jak je propojeno.

Bohužel vás asi jen odkážu na komentáře u jednotlivých tabulek a vaši fantazii. Bez ERA modelu, na který nemám čas, toho asi moc nepopíši.


h3. Adresářová struktura
/doc - tento adresář by měl obsahovat dokumentaci...
/logs - sem se mohou(podle nastavení v log4j.properties) zapisovat logy aplikace
/sql - obsahuje sql scripty pro vytvoření potřebných tabulek a sekvencí.
/src - adresář obsahuje všechny zdrojové a konfigurační souboru.
/main
/java/cz/zcu/kiv/spot - adresář, kde se nachází veškeré zdrojové kódy.
/resources/static - adresář s javascripty, potřebnými obrázky a kaskádovými styly.
/WEB-INF - adresář jako takový obsahuje konfigurační soubory pro spring + web.xml.
/classes - obsahuje soubory s lokalizačními řetězci.
/jsp - obsahuje veškeré jsp soubory v daných podadresářích.
/properties - obsahuje velkou část konfiguračních properties souborů
/tld - potřebné tag libraries..
/test/java/cz/zcu/kiv/spot - adresář obsahující veškeré testy aplikace.
/temp - obsahuje vzorové soubory pro import slov ze souboru a je pracovním adresářem při hromadném importu slov.


h3. Jmenné konvence
Tato kapitola je v rámci SPOTu docela problémová. Člověk se v aplikaci může setkat s tím, že jeden termín má i 3 ekvivalentní výrazy. Tomuto bych zde rád věnoval pár řádků. Zde jsou uvedená některá synonyma, na která jsem si vzpomněl:

projekt, application
značka, tag, kategorie
úzus, usage
odkaz, link
typ zdrojů, source usages
komentář, comment
uživatel, user

h4. Význam některých výrazů:

SPOT - Slovník Překladů Odborné terminologie.
úzus - například angličtina může mít několik odnoží. Například je rozdíl mezi anglickou a americkou angličtinou. Tyto varianty angličtin pak nazveme úzusy.


h3. Princip implementace aplikace
* ''web.xml'' - kde jinde bych měl začít, když než u tohoto souboru. Jde o vstupní od do každé webové aplikace napsané v Javě. Definují se zde základní listenery, context-param, servlet-mapping, taglibs a další.

* ''spot-servlet.xml'' - beany controllerů a interceptorů, beany pro namapovaní konkrétních částí URL patřičným controllerům, načtení spot.properties přes PropertyPlaceholderConfigurator.

* ''applicationContext.xml'' - beany pro transakce, DAO objekty, validátory, načtení jdbc.properties a weight-votes.properties přes PropertyPlaceholderConfigurator, beana pro messages aplikace a beana business logiky DictionaryManager.

S principiálním popisem začnu od pohledu uživatele. Tomu přijde do browseru html kód, které umí browser zobrazit. HTML kód se odešle ze servletového kontejneru po příchozím requestu. Servletový kontejner vytváří tento zmiňovaný kód ze servletů. Ty získává dynamicky překladem jsp stránek na servlety. A teď, po trochu nudném úvodu, se dostáváme ke kořenu věci, tedy k tomu, jakým způsobem nám Spring zajistí propojení celé aplikace. Servletovému kontejneru přijde požadavek, který obsahuje informace ve stylu: "Pošli mi potřebná data pro toto URL: http://ip.adresa.servletové.kontejneru:port/spot/sprava/uzivatele". Spring ví, že s daným URL je provázán konkrétní controller, který se stará o to, aby byla uživateli poslaná potřebná data. Controller je vždy nadefinován ve své beaně.

[@<bean id="adminUsersController" class="cz.zcu.kiv.spot.controllers.AdminUsersController">
<property name="dictionaryManager" ref="dictionaryManager" />
<property name="pagingHelper" ref="pagingHelper" />
</bean>@]

Id značí unikátní jméno, pod kterým je daná beana známa ostatním beanám, class je cesta ke controlleru a property říká, že je závislá na těch daných beanách.

Toto provázání je zaznamenáno v beanách v souboru ''spot-servlet.xml''. Konkrétně:

[@<bean id="urlAbcMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping" abstract="false" singleton="true"
lazy-init="default" autowire="default" dependency-check="default">
<property name="interceptors">
<list>
<ref bean="settingInterceptor" />
<ref bean="authInterceptor" />
</list>
</property>
<property name="urlMap">
<map>
.
.
<entry key="/sprava/uzivatele" value-ref="adminUsersController" />
.
.
</map>
</property>
<property name="alwaysUseFullPath" value="true" />
</bean>@]

Jenže než přijde ke slovu konkrétní controller, tak v této beaně jsou přiřazeny 2 interceptory v části properties. Takovýto interceptor má na starosti provést implementovaný kód před tím, než předá řízení controlleru adminUserController. (Pozn.: tedy v případě,že interceptory jsou implementované ve spotu. Intercetpory dědí od HandlerInterceptorAdapter, který má 3 metody - preHandle(HttpServletRequest request, HttpServletResponse response, Object handler), postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) a afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex). Ve Spotu je implementována pouze metoda preHandle().) Beana interceptoru vypadá podobně jako beana controlleru. Například authInterceptor se stará o jednoduché řízení přístupu k některým URL na základě práv, která mají jednotlivý uživatelé. Pokud průchod interceptorem skončí návratovou hodnotou true, předá se řízení controlleru adminUserController, jinak se (v naší implementaci) provede přesměrování na jiné URL a vyhození vyjímky.

Nyní tedy konečně přichází ke slovu AdminUserController. Tento implementuje rozhraní Controller, který má k naimplementování pouze 1 metodu, tou je handleRequest(HttpServletRequest request, HttpServletResponse response), která navrací ModelAndView(mv). ModelAndView slouží k předávání objektů získaných například z databáze na základě požadavku uživatele. Tyto objekty se pak předají do patřičných jsp stránek a zobrazí uživateli. Patřičné jsp strámky jsou vždy uvedeny uvnitř controlleru. Příklad: mv = new ModelAndView("/WEB-INF/jsp/admin/admin-users.jsp");
A nebo v případě nějaké chyby se do mv vloží Object reprezentující chybový stav. Tohoto je pak využito v kódu jsp stránek, kdy v případě, že došlo k nějaké chybě se vypíše chybová hláška například "error.unknow" na místo toho, aby se vypsala nekompletní data. Řetězec error.unknow je k uložen v souborech messages_xx.properties v různých jazykových mutacích.

[@try {
/* Pokud bylo zadane nove heslo */
if (!pass.equals("")) {
user.setNpass(user.getPass());
}
dictionaryManager.saveUser(user);
mv.addObject("completeMsg", "editUser.complete");
}
catch (Exception e) {
logger.error("V aplikaci doslo k nasledujici chybe: " + e);
mv.addObject("errorViewMsg", "error.unknow");
return;
}@]

Tak a nyní se dostáváme k tomu, jak se data z databáze dostanou ke controlleru.

[@List<User> users = dictionaryManager.getAllUsers();@]

Tento kousek kódu říká, že do daného Listu, se mají uložit všichni uživatelé. DictionaryManager je do adminUserControlleru injektován Springem, proto je v controlleru tento setter:

[@public void setDictionaryManager(DictionaryManager dictionaryManager) {
this.dictionaryManager = dictionaryManager;
}@]

Zpět k volání dictionaryManager.getAllUsers(). Podíváme-li se na implementaci rozhraní DictionaryManager, nalezneme tam tento kód:

[@public List<User> getAllUsers() {
return userDao.getAllUsers();
}@]

Z něho vidíme, že je třeba jít do datové vrstvy aplikace k DAO rozhraním a jejich implementaci. Implementace UserDaoImpl je ta třída, která už komunikuje s databází.(Pozn.: S db komunikuje přímo jdbc, ale naše DAO jsou poslední z pohledu aplikace.) Pojďme se podívat jak přesně funguje.

[@public List<User> getAllUsers () {
String sql = "SELECT * FROM users ORDER BY login";
return getJdbcTemplate().query(sql, new UserRowMapper ());
}@]

Metoda getAllUsers() je přehledná. Nejdříve je popsán string, který představuje SQL dotaz nad databází. Následuje return, který navrací volání dotazu sql za použití UserRowMapper(). UserRowMapper je vnitřní privátní třída třídy UserDaoImpl a zajišťuje namapování jednotlivých záznamů z tabulky "users" na doménové objekty User.

[@private class UserRowMapper implements RowMapper {
public Object mapRow(ResultSet rs, int rowNum) throws SQLException {
User user = new User();
user.setId(rs.getInt("users_id"));
user.setLogin(rs.getString("login"));
user.setPass(rs.getString("pass"));
user.setFirstname(rs.getString("firstname"));
user.setLastname(rs.getString("lastname"));
user.setEmail(rs.getString("email"));
user.setEmailpub(rs.getString("email_pub"));
user.setHomepage(rs.getString("homepage"));
user.setDescription(rs.getString("description"));
user.setRights(rs.getInt("rights"));
user.setActive(rs.getInt("active"));
user.setActiveCode("active_code");
return user;
}
}@]

Tak toto byla asi nejtěžší část celého seznámení se SPOTem. Doufám tedy, že jsem vám alespoň objasnil základní princip fungování aplikace. Na principu tohoto příkladu příkladu více méně funguje celá aplikace.


h3. JSP
Cílem je, aby se veškeré zobrazované statické texty načítaly z messages_xx.properties, kde xx představuje danou jazykovou mutaci(cz, en a de). Tyto texty se snadno vypíší například přes <fmt:message key="index.jakPrispet.popis" />, kde index.jakPrispet.popis je záznam v messages_xx.properties a má přiřazen daný přeložený řetězec, který se vypíše. Volba příslušné jazykové mutace je závislá na aktuální uživatelově volbě.


h3. Všeobecně
Zkuste psát minimálně dostačující dokumentační komentáře, které budou vašim následovníkům k něčemu a ne k ničemu. Stejně tak se snažte dodržet použité jmenné konvence a nevnášejte do aplikace ještě větší zmatek, než je v ní nyní ;) Dále by bylo více než vhodné třídy, metody a proměnné pojmenovávat anglicky a češtinu používat pouze v komentářích.

Pokud budete chtít přidat stránku se statickým obsahem, využijte služeb ''StaticPageControlleru''.