17-04-09 pta
19-04-09 pta / update struktury
27-04-09 pta / update struktury
08-05-09 pta
13-09-09 pta
09-03-10 pta

INTERFEJS TEKSTOWY
------------------

./run.sh polecenie parametry

Dane o połączeniu z bazą danych są brane z pliku config.properties a w następnej
kolejności z src/hibernate-commandline.cfg.xml (które zostaje dodane do JAR-a
przy kompilacji) -- patrz punkt Baza danych, uwaga o haśle i połączeniu z bazą.

./run.sh upload <katalog> 
	Przeszukuje <katalog> rekursywnie w poszukiwaniu plików o nazwach *.packet.xml, z nich
	pobiera nazwy plików forest.xml do wrzucenia, po czym wrzuca zdania do systemu
	popaczkowane zgodnie z packet.xml.

./run.sh update <katalog>
	Przeszukuje <katalog> rekursywnie w poszukiwaniu plików *.xml (które są uważane za pliki
	forest.xml) po czym aktualizuje te zdania w systemie (zdania muszą posiadać
	id wersji gramatyki nowsze od ostatniej wgranej wersji).

./run.sh export <katalog>
	Zrzuca wszystkie zrobione zdania do <katalogu> (generowane nazwy plików to
	<sent_id>.xml). Format to forest.xml z atrybutami "chosen" oraz metadanymi.

BAZA DANYCH
---------------------

Uwagi ogólne:

1) Dendrarium nie tworzy bazy danych na starcie (Hibernate ma ustawione "validate")

2) skrypty do tworzenia i usuwania bazy są w katalogu sql/ i sql/generated

3) skrypty do generowania i usuwania bazy są tworzone poleceniem "ant exportddl";
   generowane pliki to sql/generated/drop.sql oraz sql/generated/dendrarium.sql

4) plik import.sql w sql/ nie jest wczytywany przy starcie systemu; musi zostać
   wczytany przez administratora po uruchomieniu dendrarium.sql; są tam ważne
   rzeczy: definicje ról oraz rola admina (plus kilka rzeczy niepotrzebnych, w
   produkcyjnej wersji powinno zostać tyle:

insert into Role (roleId, rolename) values (1, 'admin');
insert into Role (roleId, rolename) values (2, 'superdendrolog');
insert into Role (roleId, rolename) values (3, 'dendrolog');
insert into Role (roleId, rolename) values (4, 'gramatyk');
insert into Dendrologist (username, password, name) values ('admin',
'admin', 'Admin');
insert into UserRoles (Username, RoleId) values ('admin', 1);

5) do pliku dendrarium.properties dodana zostala wlasciwosc "import_on_startup";
   jeżeli wartość to true, wówczas na starcie systemu wrzucone zostają XML-e
   z pliku resources.list. Funkcjonalność wrzucania przy starcie powinna zostać
   niedługo usunięta (w przypadku kiedy sa juz taski na starcie, nic nie jest
   wrzucane, zeby zapobiec bledom)

6) sql-e wrzucamy poleceniem psql -h localhost -U dendrarium --password -f PLIK dendrarium

7) HASŁO do bazy (i dane o połączeniu): 

	* Ustawiamy je poleceniem ALTER ROLE dendrarium WITH PASSWORD 'blaba';
	
	* Dendrarium działające na Tomcacie bierze dane o połączeniu  z pliku context.xml: są dwa
	  takie pliki: w conf/ w katalogu Tomcata (to lepsze miejsce do umieszczenia
	  tej informacji, bo lepiej żeby paczka z programem nie zawierała takich
	  danych) oraz w web/META-INF w katalogu Dendrarium (dobre tylko jeżeli
	  nie mamy uprawnień do konfiguracji Tomcata). Wpis powinien wyglądać jakoś tak:

            <Resource name="jdbc/DendrariumDB" auth="Container" type="javax.sql.DataSource"
               maxActive="100" maxIdle="30" maxWait="10000"
               username="dendrarium" password="dendrarium" driverClassName="org.postgresql.Driver"
               url="jdbc:postgresql://localhost:5432/dendrarium" />
	
	* Dendrarium działające z linii poleceń bierze dane o połączeniu w pierwszej kolejności
	  z pliku config.properties w katalogu, z którego jest uruchamiane. Możliwe właściwości
	  to wszystkie właściwości mogące występować w plikach .cfg.xml Hibernate, na
	  przykład

	    show_sql=false
            hibernate.connection.url=jdbc:postgresql://localhost:5432/dendrarium
            hibernate.connection.username=dendrarium
            hibernate.connection.password=dendrarium
            hibernate.connection.driver_class=org.postgresql.Driver
            hibernate.hbm2ddl.auto=validate

	  Te ustawienia nadpisują ustawienia domyślne, znajdujące się w pliku
	  src/hibernate-commandline.cfg.xml:

	<hibernate-configuration>
	    <session-factory>
	        <property name="show_sql">false</property>
	        <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/dendrarium</property>
	        <property name="hibernate.connection.username">dendrarium</property>
	        <property name="hibernate.connection.password">dendrarium</property>
	        <property name="hibernate.connection.driver_class">org.postgresql.Driver</property>
	
	        <property name="hibernate.hbm2ddl.auto">validate</property>
	        <!-- <property name="hibernate.dialect">org.hibernate.dialect.PostgreSQLDialect</property> -->
	        <property name="cache.provider_class">org.hibernate.cache.HashtableCacheProvider</property>
	        <property name="transaction.flush_before_completion">true</property>
	        <property name="transaction.factory_class">org.hibernate.transaction.JDBCTransactionFactory</property>
		(...)
	    </session-factory>
	</hibernate-configuration>
~                           
	  

Procedura postawienia bazy:

1) Tworzymy w Postgresie użytkownika dendrarium z hasłem dendrarium.

2) Logujemy się jako ten użytkownik i zakładamy bazę:

	$ psql -h localhost -U dendrarium -d template1
	create database dendrarium;

3) Generujemy skrypty sql/generated/ poleceniem (w katalogu głównym Dendrarium)
	
	$ ant exportddl

4) Tworzymy pustą bazę

	$ psql -h localhost -U dendrarium --password -f sql/generated/dendrarium.sql dendrarium

5) Wlewamy rekordy potrzebne do startu (definicje ról itp.)

	$ psql -h localhost -U dendrarium --password -f sql/import.sql dendrarium

6) Informacje o połączeniu (datasource) dla Tomcata powinny być w pliku conf/context.xml
   w katalogu Tomcata. U mnie wpis wygląda tak:

  <Resource name="jdbc/DendrariumDB" auth="Container" type="javax.sql.DataSource"
               maxActive="100" maxIdle="30" maxWait="10000"
               username="dendrarium" password="dendrarium" driverClassName="org.postgresql.Driver"
               url="jdbc:postgresql://localhost:5432/dendrarium" />

   Można też te informacje wrzucić do web/META-INF/context.xml w katalogu Dendrarium.


INSTALACJA TOMCATA 6 + odpalenie Dendrarium (nie wymaga uprawnien roota)
------------------------------------------------------------------------
 
1. Instalujemy Tomcata 6, sciagajac paczke ze strony Apache:

	http://www.apache.net.pl/tomcat/tomcat-6/v6.0.18/bin/apache-tomcat-6.0.18.tar.gz

   i rozpakowujemy, np. w ~/java/tomcat.

2. Kopiujemy mu potrzebne biblioteki z katalogu Dendrarium:

	Dendrarium$ cp lib/asm.jar lib/postgresql-8.3-603.jdbc4.jar ~/java/tomcat/lib

3. Modyfikujemy plik Dendrarium/konfiguracja (jezeli taki plik nie istnieje, tworzymy kopie pliku
   konfiguracja-clean o takiej nazwie), odkomentowujac jesli trzeba czesc dla Tomcata 6 i sprawdzajac
   sciezki.

4. Stawiamy baze danych (opisane w osobnym punkcie).
  
5. Kompilujemy Dendrarium

	Dendrarium$ ant war

... w dist/ zostaje utworzone archiwum Dendrarium.war

	Dendrarium$ ./redeploy.sh                            

... Dendrarium.war zdeployowane na Tomcacie + restart Tomcata

6. Odpalamy Dendrarium w przegladarce

	$ firefox http://localhost:8080/Dendrarium/
 
7. Ogladamy logi, uzywajac polecenia:

	$ ./log.sh

STRUKTURA WAR-a 
---------------

META-INF/
	MANIFEST.MF				"generated by ant"
	context.xml				info dla tomcata
WEB-INF/
	classes/
		dendrarium/
			**/*.java 		to co w dendrarium-ejb/src (+ ELHelper.java)
		hibernate.cfg.xml		odpowiednik persistence.xml
		seam.properties			pusty
		import.sql			inserty do bazy przy starcie
    	dendrarium-taglib.xml 			wlasne fcje w EL
	lib/	
		*.jar				to co w deployed-jars (lub w lib/)
	components.xml				konfiguracja komponentow Seama
	faces-config.xml			konfiguracja JSF
	pages.xml				reguly nawigacji
	web.xml					konfiguracja aplikacji webowej
css/
	*.css
img/
	*.jpg		
js/
	*.js
*.xhtml						strony Facelets


STRUKTURA PROJEKTU
------------------

web/                            strony + obrazki + konfiguracja
	META-INF/                   katalog konfiguracyjny
		context.xml             info dla tomcata
	WEB-INF/                    katalog konfiguracyjny
        templates/
            *.xhtml             definicje własnych tagów Facelets
		components.xml          konfiguracja komponentow Seama
		faces-config.xml        konfiguracja JSF
		pages.xml               reguly nawigacji
		web.xml                 konfiguracja aplikacji webowej
		dendrarium-taglib.xml   wlasne fcje EL i tagi Facelets
	css/
		*.css
	img/
		*.jpg
    info/
        *.html, *.css, ...      manual wygenerowany latex2html
    template.xhtml              główny szablon
	*.xhtml                     strony Facelets

src/						klasy + konfiguracja
	dendrarium/				korzen drzewa pakietow Dendrarium
		**/*.java			zrodla
        dendrarium.properties   plik z konfiguracją dendrarium
	hibernate.cfg.xml		odpowiednik persistence.xml
	seam.properties			pusty
	import.sql				inserty do bazy przy starcie
    log4j.xml               konfiguracja logowania

sql/						skrypty SQL do generacji bazy
	generated/				skrypty wygenerowane przez Hibernate
	import.sql				skrypt z insertami potrzebnymi do startu

build/						katalog kompilacji (ignorowany przez svn)

dist/						katalog docelowy (ignorowany przez svn)

war/						katalog budowy war-a (ignorowany przez svn)

lib/						wszystkie potrzebne biblioteki

nbproject/					wlasne informacje NetBeans
	private/				zalezne od uzytkownika (nie wrzucamy na svn)

build.xml					zmodyfikowany, dodany cel: war
biblioteki-tomcat5.5				informacja dla Anta, ktore biblioteki wchodza do war-a (Tomcat 5.5)
biblioteki-tomcat6				informacja dla Anta, ktore biblioteki wchodza do war-a (Tomcat 6)
konfiguracja					plik z informacjami dla Anta oraz redeploy.sh, log.sh zaleznymi od serwera
redeploy.sh					skrypt wrzucajacy aplikacje na serwer
log.sh						skrypt wyswietlajacy logi

UWAGA ODNOŚNIE NETBEANS
-----------------------

Żeby folder web/ był widoczny w zakładce "Projects" w NetBeans jako "Web Pages",
dodałem go sztucznie jako "test source folder", tj. folder z klasami testów.

Chyba nic złego przez to się nie dzieje (poza tym, że NB wyświetla podfoldery
web/ jako pakiety i czasem oburza sie na nazwę pakietu WEB-INF), a dzięki
temu nie trzeba się przeklikiwać do zakładki "Files".

