====== Serverul HTTP Apache Tomcat 8.x  ======

[[http://tomcat.apache.org/|Apache Tomcat]] este un server HTTP care oferă funcționalitatea de container pentru Java Servlets, având o arhitectură modulară.

Versiunile 8.x implementează:
  * specificația Java Servlets 3.1;
  * specificația JavaServer Pages 2.3;
  * specificația Expression Language 3.0;
  * specificația WebSocket 1.1.
De asemenea, aplicațiile web dezvoltate folosind serverul web Apache Tomcat trebuie să fie scrise folosind versiunea 7 a limbajului de programare Java.

Documentele JSP (JavaServer Pages) / JSF (JavaServer Faces) sunt convertite în mod automat în clase Java Servlets, în momentul în care aplicația web care le conține este încărcată în contextul acestuia.

Serverul Apache Tomcat operează conform modelului cerere-răspuns. O cerere este transmisă în momentul în care în navigator este solicitată o pagină Internet disponibilă în contextul serverului. Pe baza execuției clasei Java Servlet corespunzătoare, se generează un răspuns ce constă într-un document HTML.

===== Instalare =====

==== Linux ====

Pentru sistemele Linux, serverul Apache Tomcat este disponibil sub forma unei arhive [[http://apache.javapipe.com/tomcat/tomcat-8/v8.0.26/bin/apache-tomcat-8.0.26.zip|.zip]] sau [[http://apache.javapipe.com/tomcat/tomcat-8/v8.0.26/bin/apache-tomcat-8.0.26.tar.gz|.tar.gz]], care este despachetată, urmând ca ulterior instanța să fie configurată.

<code>
student@aipi2015:~$ cd /tmp
student@aipi2015:/tmp$ wget http://apache.javapipe.com/tomcat/tomcat-8/v8.0.26/bin/apache-tomcat-8.0.26.tar.gz
student@aipi2015:/tmp$ tar xzf apache-tomcat-8.0.26.tar.gz
student@aipi2015:/tmp$ sudo mkdir -p /usr/local/tomcat
student@aipi2015:/tmp$ sudo chown -R student /usr/local/tomcat
student@aipi2015:/tmp$ mv apache-tomcat-8.0.26/* /usr/local/tomcat
student@aipi2015:/tmp$ rm -Rf apache-tomcat-8.0.26
student@aipi2015:/tmp$ rm -f apache-tomcat-8.0.26.tar.gz 
</code>

Calea către directorul ''bin'' al serverului HTTP Apache Tomcat va fi precizată în variabila de mediu ''$PATH'', astfel încât executabilele din cadrul acestuia să poată fi apelate mai ușor:

<file text .bashrc>
export TOMCAT_HOME=/usr/local/tomcat
export PATH=$PATH:$TOMCAT_HOME/bin
</file>

De asemenea, valorile din acest fișier trebuie încărcate:

<code>
student@aipi2015:~$ source ~/.bashrc
</code>

==== Windows ====

Pentru sistemele Linux, serverul Apache Tomcat este disponibil atât sub forma unei arhive .zip specifice unui anumit tip de arhitectură ([[http://apache.javapipe.com/tomcat/tomcat-8/v8.0.26/bin/apache-tomcat-8.0.26-windows-x86.zip|32 de biți]] sau [[http://apache.javapipe.com/tomcat/tomcat-8/v8.0.26/bin/apache-tomcat-8.0.26-windows-x64.zip|64 de biți]]), care este despachetată, urmând ca ulterior instanța să fie configurată, cât și sub forma unei [[http://apache.javapipe.com/tomcat/tomcat-8/v8.0.26/bin/apache-tomcat-8.0.26.exe|aplicații care asistă utilizatorul în procesul de instalare]], informațiile legate de configurare fiind preluate în acest moment.

===== Configurare & Utilizare =====

==== Arhitectura ====

În arhitectura Apache Tomcat, structura unui serviciu include un motor, o gazdă, un context şi un cluster. Nivelul cel mai de sus este reprezentat de container, iar nivelul cel mai de jos este reprezentat de cluster.

{{ :utile:apache_tomcat:apache_tomcat_architecture.png?nolink&450 }}

Un serviciu asociază unul sau mai mulţi conectori la motorul serverului. Motorul serverului Apache Tomcat poate rula pe mai multe maşini (virtuale), redirecţionând cererile către cea care este identificată prin adresa IP şi portul specificate în antetele HTTP.

Implicit, motorul folosit de Apache Tomcat este Catalina, pentru care se asociază doi conectori: HTTP şi AJP. 
  * conectorul HTTP/1.1 gestionează comunicaţia dintre client şi server folosind protocolul HTTP (pe portul 8080);
  * conectorul AJP/1.3 (Apache JServ Protocol) funcţionează pe portul 8009 şi gestionează comunicaţia dintre serverul Tomcat şi serverul HTTP Apache;

Un motor poate conţine una sau mai multe gazde. 

La rândul ei, o gazdă poate avea mai multe contexte. 

În mod implicit, Apache Tomcat defineşte o gazdă ''localhost'' şi un director de bază ''webapps'' unde vor fi dezvoltate toate aplicaţiile. 

<note tip>Spațiul de nume din care vor putea fi accesate aplicaţiile este aceeaşi cu numele directorului în care acestea sunt instalate în ''webapps''.</note>

==== Structura ierarhiei de directoare ====

Serverul Apache Tomcat conţine următoarele directoare:
  * ''bin'' – fişiere binare şi script-uri apelate la pornirea / oprirea serverului Apache Tomcat;
  * ''conf'' – include câte un director pentru fiecare motor ce conţine subdirectoare pentru toate gazdele gestionate de acesta și fişiere de configurare care se aplică tuturor aplicaţiilor:
    * fişierul ''catalina.policy'' conţine politicile de securitate aplicabile;
    * fișierele ''catalina.properties'' şi ''logging.properties'' specifică diferite proprietăți;
    * fișierele ''server.xml'', ''web.xml'', ''context.xml'' și ''tomcat-users.xml'' conțin configurări ale serverului, aplicațiilor, contextului și utilizatorilor care pot accesa diferite funcționalități.
  * ''lib'' – conţine bibliotecile comune (pe care le vor folosi toate aplicaţiile):
    * ''servlet-api.jar'' pentru aplicaţii ce folosesc Java Servlets;
    * ''jasper.jar'' / ''jasper-el.jar'' pentru Java Server Pages Expression Language;
  * ''logs'' – conţine jurnalele specifice motorului Catalina, ale gazdelor pe care le gestionează, ale aplicaţiilor ''manager'' / ''host-manager'' şi jurnalul de acces.
  * ''webapps'' – locaţia la care vor fi plasate aplicaţiile care vor putea fi accesate folosind serverul Apache Tomcat;
  * ''work'' – director de lucru care va conţine clasele Java Servlet corespunzătoare documentelor Java Server Faces / Java Server Pages; organizarea sa se face pe motor, gazde configurate în cadrul motorului, aplicaţii;
  * ''temp'' – diferite resurse temporare.

{{ :utile:apache_tomcat:apache_tomcat_structure.png?nolink&150 }}

==== Configurare ====

Pentru a putea utiliza serverul Apache Tomcat, iniţial este necesară specificarea variabilelor de mediu ''JAVA_HOME'' şi ''JRE_HOME'' în cazul în care acestea nu sunt definite deja (în fişierul batch ''bin/setclasspath.bat'' – Windows respectiv ''bin/setclasspath.sh'' – Linux):
  * Windows <code>
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_60\
set JRE_HOME=C:\Program Files\Java\jdk1.8.0_60\jre\
</code>
  * Linux <code bash>
export JAVA_HOME=/usr/local/java/jdk1.8.0_60/
export JRE_HOME=/usr/local/java/jdk1.8.0_60/jre/
</code>

Ulterior, configurarea Apache Tomcat se face din fişierul ''conf/server.xml'', care prezintă o structură similară cu arhitectura serverului.

<note tip>În principiu, nu este necesară modificarea fişierului de configurare ''conf/server.xml'', acesta conţinând toate informaţiile necesare pentru rularea unei aplicaţii cu Apache Tomcat.</note>

Atributele ''unpackWARs'', respectiv ''autoDeploy'' indică dezarhivarea aplicaţiilor dezvoltate ca .war (Web Archive), respectiv instalarea lor automată, pe măsură ce sunt plasate în directorul corespunzător. 

<code xml>
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
</code>

În documentul ''conf/tomcat_users.xml'' se definesc rolurile pentru accesarea diferitelor funcţionalităţi ale Apache Tomcat precum şi utilizatorii care primesc aceste roluri.

<note>Implicit, acest fişier nu conţine nici un fel de roluri şi nici un fel de utilizatori configuraţi. Diferite medii integrate de dezvoltare necesită specificarea unor anumite tipuri de roluri / utilizatori pentru configurarea aplicaţiilor în cadrul Apache Tomcat.</note>

<file xml tomcat_users.xml>
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager-gui" />
  <role rolename="manager-status" />
  <role rolename="manager-script" />
  <role rolename="manager-jmx" />
  <role rolename="admin-gui" />
  <role rolename="admin-script" />
  <user username="admin" password="admin" roles="manager-gui, admin-gui, manager-status, manager-script, admin-script, manager-jmx" />
</tomcat-users>
</file>

Semnificaţia rolurilor  este descrisă mai jos:
  * ''manager-gui'' – oferă acces la o interfaţă grafică cu utilizatorul (accesibilă la %%http://localhost:8080/manager/html%%, respectiv din secţiunea Manager App);
  * ''manager-status'' – pune la dispoziţia utilizatorilor informaţii cu privire la starea serverului (accesibil la %%http://localhost:8080/manager/server%%, respectiv din secţiunea Server Status);
  * ''manager-script'' – este o interfaţă în format text, în care se pot transmite serverului Apache Tomcat comenzi prin intermediul parametrilor din URL %%http://localhost:8080/manager/text/{comanda}?{parametri}%% unde:
    * comanda poate avea valorile:
      * ''list'' (se afişează aplicaţiile dezvoltate în contextul serverului);
      * ''deploy'' – dacă se doreşte dezvoltarea unei aplicaţii;
    * parametri poate indica contextul aplicaţiei în cadrul serverului Apache Tomcat la care se referă o anumită comandă.

<note>Unele medii integrate de dezvoltare solicită specificarea unui utilizator care deţine rolul ''manager-script'' pentru dezvoltarea aplicaţiei în contextul serverului Apache Tomcat.</note>

  * ''manager-jmx'' – oferă acces la interfaţa JMX, accesibilă la %%http://localhost:8080/manager/jmxproxy/?{comanda}={parametri}%% 

<note important>Este recomandat ca unui utilizator să nu i se confere drepturi corespunzătoare mai multor roluri (din motive de securitate).</note>

==== Funcționalitate ====

În momentul în care rulează, serverul Apache Tomcat poate fi accesat din navigator la adresa de Internet http://localhost:8080, având următorul conținut:

{{ :utile:apache_tomcat:apache_tomcat_main_page.png?nolink&700 }}

Din acest context, sunt disponibile legături către:
  * starea serverului (//eng.// Server Status);
  * modulul de gestiune al aplicaţiilor web (//eng.// Manager App) care oferă o listă a aplicaţiilor care au fost configurate în contextul serverului web, afişându-se o serie de informaţii cu privire la acestea precum locaţia în care au fost instalate, versiunea, starea curentă (în execuţie sau nu), numărul de sesiuni deschise; de asemenea, acest utilitar permite realizarea unor operaţii (pornire, oprire, reîncărcare, configurare) precum şi precizarea perioadei de timp (exprimată în minute) după care sesiunile asociate nu vor mai putea fi folosite, în cazul în care aplicaţia nu este accesată;
  * modulul de gestiune al gazdei (//eng.// Host Manager).

==== Dezvoltarea unei aplicații web ====

Orice aplicaţie web dezvoltată folosind serverul Apache Tomcat va trebui plasată în directorul ''webapps''.

Fiecare aplicaţie conţine directoarele:
  * ''WEB-INF'' având în componență fişierele legate de aplicaţie în sine:
    * fişierul de configurare ''web.xml'';
    * celelalte resurse care nu vor fi accesibile clienţilor: 
      * sursele aplicaţiei;
      * clasele corespunzătoare (incluse în directorul ''classes'');
      * bibliotecile accesate de aplicație (plasate în directorul ''lib'').
  * ''META-INF'' conţine informaţiile legate de server – fişierul ''context.xml''.

<note tip>Nu există o denumire "standard" pentru directorul care conţine sursele aplicaţiei, recomandându-se ca acestea să se găsească la o locație distinctă de clasele generate (sugestii de denumiri: ''sources'' sau ''src'').</note>

<note tip>Încărcarea diferitelor biblioteci (din directorul ''lib'') trebuie să se facă explicit (prin apelarea metodei ''Class.forName("..."))'', întrucât serverul Apache Tomcat nu realizează acestă operaţie în mod automat atunci când aplicaţia web este instalată.</note>

{{ :utile:apache_tomcat:apache_tomcat_webapplication.png?nolink&150 }} 

Fişierul de configurare ''web.xml'' descrie numele aplicaţiei web (''servlet-name'') precum şi clasa care conţine servlet-ul implementând practic serviciul web corespunzător (''servlet-class''). Opţional, poate fi specificat un parametru ''load-on-startup'' care, atunci când are valoare pozitivă indică ordinea în care sunt încărcate clasele respectiv, lasă la latitudinea container-ului care conţine servlet-ul să încarce clasele atunci când este necesar, dacă este dată o valoare negativă. O astfel de clasă trebuie plasată obligatoriu în directorul ''classes''.

De asemenea, se va specifica o asociere între numele servletului şi contextul în care acesta va putea fi accesat (proprietatea ''url-pattern'' din cadrul secţiunii ''servlet-mapping''). Pagina Internet care va fi încărcată când se va porni aplicaţia web poate fi specificată în proprietatea ''welcome-file'' din cadrul secţiunii ''welcome-file-list''. În acest caz, se va indica denumirea servletului asociat paginii Internet respective şi nu contextul din care acesta poate fi accesat.

<file xml web.xml>
<web-app>
  <servlet>
    <description></description>
    <display-name>ServletName</display-name>
    <servlet-name>ServletName</servlet-name>
    <servlet-class>ServletClass</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>ServletName</servlet-name>
    <url-pattern>/ServletClass</url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>ServletName</welcome-file>
  </welcome-file-list>
</web-app>
</file>

Pagina Internet asociată servletului ''ServletName'' va fi disponibilă la adresa %%http://localhost:8080/<application_directory>/ServletClass/%%, unde ''application_directory'' reprezintă contextul unde a fost instalată aplicaţia web (corespunzător subdirectorului din ''webapps'').

Pot fi specificate mai multe clase Java Servlet, fiecare dintre acestea gestionând operațiile corespunzătoare unei pagini Internet.

Opţional, se pot construi şi script-uri pentru realizarea operaţiilor necesare configurării aplicaţiei în contextul serverului.
În exemplu, există un director ''scripts'' care conţine fişierele batch ''deploy.bat'' respectiv ''deploy.sh''. Acestea compilează sursele, le mută în directorul ''classes'' şi reiniţializează serverul web Apache Tomcat (opreşte instanţa care rulează şi porneşte o instanţă nouă) astfel încât modificările realizate la nivelul claselor să fie vizibile în cadrul aplicaţiei. În cazul în care serverul web Apache Tomcat nu fusese pornit anterior, va fi generată o excepţie ce nu împiedică însă rularea cu succes a scripturilor.

==== Gestiunea serverului ====

Lansarea în execuţie a serverului Apache Tomcat se face prin intermediul fişierului batch ''bin/startup.bat'' (Windows) respectiv ''bin/startup.sh'' (Linux).

Oprirea serverului web Apache Tomcat se face prin ''bin/shutdown.bat'', respectiv ''bin/shutdown.sh''.

Reiniţializarea serverului web este necesară de fiecare dată dacă se utilizează tehnologia Java Servlets  atunci când se realizează modificări la nivelul paginilor web deoarece clasele sunt "configurate" (//eng.// deployed) împreună cu dependenţele doar în momentul în care Apache Tomcat este lansat în execuţie. În cadrul acestui proces, sunt parcurse toate subdirectoarele din ''webapps'' astfel încât fiecare instanță a unei aplicaţii web în parte este încărcată în contextul serverului web.

<code>
Nov 24, 2014 12:00:00 AM org.apache.catalina.startup.HostConfig deployDirectory
INFO: Deploying web application directory BookStore
</code>

<note tip>Acest mecanism nu este necesar în cazul folosirii tehnologiei Java Server Pages deoarece transformarea în clasele Java Servlets asociate şi compilarea acestora au loc dinamic, atunci când sunt accesate din browser.</note>

==== Interfațarea cu medii integrate de dezvoltare ====

=== Eclipse ===

Se creează o referință către serverul Apache Tomcat 8.0 din mediul de dezvoltare Eclipse Mars IDE for Java EE Developers 4.5 (//Window// → //Preferences// → //Server// → //Runtime Environments//), accesându-se butonul //Add...//.

{{ :utile:apache_tomcat:tomcat_eclipse01.png?nolink&600 }}

Se indică ca tip al mediului de execuție //Apache// → //Apache Tomcat v8.0//.

{{ :utile:apache_tomcat:tomcat_eclipse02.png?nolink&600 }}

Configurarea serverului Apache Tomcat 8.0 presupune precizarea:
  * denumirii sub care acesta va fi identificat;
  * locației în care este instalat;
  * mediului de execuție Java (JRE) cu care va rula.

{{ :utile:apache_tomcat:tomcat_eclipse03.png?nolink&600 }}

În situația în care configurarea a fost realizată corect, referința către serverul Apache Tomcat 8.0 va fi afișată în secțiunea //Server Runtime Environments//.

{{ :utile:apache_tomcat:tomcat_eclipse04.png?nolink&600 }}

Starea serverului precum și diferite operații asupra acestuia ((re)pornire, oprire, publicare aplicații) poate fi realizată prin intermediul unei zone de lucru, vizibilă prin activarea sa (//Window// → //Show View// → //Other...// → //Server// → //Servers//).

{{ :utile:apache_tomcat:tomcat_eclipse05.png?nolink }}

În situația în care nu este creată nici o referință către un alt server, există o legătură pentru configurarea sa (//No servers are available. Click this link to create a new server...//). Altfel, prin operația de click-dreapta pe mouse în zona de lucru, este afișat un meniu contextual de unde este lansată în execuție această acțiune (//New// → //Server//).

{{ :utile:apache_tomcat:tomcat_eclipse06.png?nolink }}

Este selectat tipul de server (//Apache// → //Tomcat v8.0 Server//), moment în care sunt populate adresa la care acesta este disponibil (//Server's host name//, în cazul de față ''localhost''), denumirea instanței (//Server name//) precum și mediul de rulare al serverului (//Server runtime environment//, în această situație, ''Apache Tomcat v8.0'').

{{ :utile:apache_tomcat:tomcat_eclipse07.png?nolink&600 }}

În cazul în care configurația a fost realizată corect, în zona de lucru //Servers// poate fi vizualizată referința către server împreună cu starea acestuia. În momentul în care serverul se află în execuție, sunt afișate aplicațiile dezvoltate în acest context. Prin operația de click-dreapta pe mouse, este accesibil un meniu contextual unde sunt disponibile diferite operații legate de server.

{{ :utile:apache_tomcat:tomcat_eclipse08.png?nolink }}

=== NetBeans ===

Se creează o referință către serverul Apache Tomcat 8.0 din mediul de dezvoltare NetBeans 8.0.2 (//Services// → //Servers// → click-dreapta → //Add Server...//).

{{ :utile:apache_tomcat:tomcat_netbeans01.png?nolink }}

Se indică ca tip de server //Apache// → //Apache Tomcat or TomEE//.

{{ :utile:apache_tomcat:tomcat_netbeans02.png?nolink&600 }}

Configurarea serverului Apache Tomcat 8.0 presupune precizarea:
  * locației în care este instalat;
  * datele de autentificare pentru publicarea aplicației web (nume de utilizator / parola), pentru un utilizator având rolul ''manager'' sau ''manager-script'' (''admin'' / ''admin''); se va bifa opțiunea //Create user if it does not exist//.

{{ :utile:apache_tomcat:tomcat_netbeans03.png?nolink&700 }}

În situația în care configurarea a fost realizată corect, referința către serverul Apache Tomcat 8.0 va fi afișată în secțiunea //Services// → //Servers// (se indică și starea acestuia: pornit / oprit).

{{ :utile:apache_tomcat:tomcat_netbeans04.png?nolink }}