ItEr45S06DocumentacionFormacionItEr44S07: Continuation of architecture section of development guide.

doc/src/technical/guia-desenvolvemento/guia-arquitectura.rst

@@ -5,31 +5,184 @@ Guía de Arquitectura
 Arquitectura basada en capas
 ============================
 
-Enumeracion das capas usadas na aplicación:
+A aplicación Navalplan utiliza unha arquitectura de organización do código baseada en capas. Consiste en organizar o software nunha serie de divisións horizontais lóxicas. Estas divisións horizontais organízanse xerarquicamente de forman que descansa cada unha na capa que ten debaixo. Así ata a capa máis profunda. Nesta estruturación séguense os seguintes preceptos:
+   - Cada capa ten un conxunto de responsabilidades que corresponden a un determinado nivel de abstracción.
+   - Unha capa ofrece servizos a capa de nivel superior.
+   - Unha capa usa os servizos ofertados pola capa de nivel inferior.
 
-   * Capa de interfaz:
+As capas de que consta Navalplan son as seguintes:
-      * Modulo de autenticacion.
+   - Capa de presentación - interfaz web.
-      * Interfaz WEB:
+   - Capa de interfaz servizos web.
-         * Model-View-Controller
+   - Capa de lóxica de negocio.
-         * Capa de servicios conversacionais: XXXModel
+   - Capa de persitencia.
-      * Interfaz de servicios WEB.
-         * Servicios REST.
-   * Capa de loxica de negocio: Entidades e clases auxiliares de comportamento
-   * Capa de persistencia
 
-Tecnoloxías utilizadas e relacion con cada capa
+A continuación se explicará brevemente cada unha destas capas.
-=========================================================
 
-   * Framework Spring. Contedor de inyeccion de dependencias usado de forma transversal na aplicación para inyeccion de control
+Capa de presentación - interfaz web
-e para proporcion de varios servicios como:
+-----------------------------------
-      * Xestion das transaccions en Hibernate e a sesión.
+
-      * Spring TestContext para traballar sobre JUnit.
+A capa de interfaz web corresponde coa parte do programa que se encarga de implementar as páxinas HTML/Javascript que permiten aos usuarios realizar as operacións necesarias para planificar a empresa.
-   * Framework ZK. Framework para facer interfaz web.
+
+Dentro da interfaz web se fai uso do patrón MVC (Model-View-Controller) para estruturar cada unha das pantallas.
+
+No patrón MVC distínguense 3 partes estruturais.
+   - **Vista (View)**. A vista inclúe os compoñentes software que se encargan de representar os widgets dos que se compón a
+     interfaz gráfica. No caso dunha aplicación de escritorio os widgets da vista se renderizan pintándose a través das librerías
+     gráficas do sistema operativo. No caso dunha aplicación como ésta, unha aplicación con interfaz web, os widgets se renderizan a
+     través de HTML/Javascript e esta renderización e levada a cabo polo navegador web do usuario que accede a aplicación.
+   - **Modelo (Model)**. O modelo encapsula por unha banda os datos que se xestionan a través da vista e ofrece o controlador
+     operacións para actuar sobre eles. Na arquitectura está representado por clases que teñen xestionado o seu ciclo de vida a través
+     do contedor de inxeción de dependencias que se usa *Spring framework*. Son clases conversacionais que rexistran o estado de
+     interacción do usuario cunha determinada pantalla na que esté operando.
+   - **Controlador (Controller)**. O controlador é o compoñente software - materializado en Navalplan nunha clase de orientación a
+     obxectos - que se encarga de atender as notificacións, peticións procedentes da vista e de solicitar ao modelo que realice as
+     operacións pertinentes acordes coas ordes que o usuario emite ao programa a través da interfaz.
+
+É unha capa que non ten ningunha por enriba, é dicir, interactúa directamente co usuario.
+
+Capa de interfaz de servizos web
+--------------------------------
+
+A capa de servizos web é unha capa paralela a capa de interfaz web que ofrece servicios web REST para ofrecer funcionalidades de exportación/importación de datos dunha instalación da aplicación co exterior. Conténplanse dous tipos de comunicacións a través de servizos web:
+   - **Integración con outras aplicacións**. Quedarían englobados aquí os ERP que desexen interactuar con Navalplan.
+   - **Integración con outras instalacións de Navalplan**. Dúas instalacións de Navalplan en sendas empresas permiten interactuar
+     para a subcontratación de pedidos e o reporte de avances dos mesmos.
+
+
+Capa de lóxica de negocio
+-------------------------
+
+A capa de lóxica de negocio atópase por debaixo da capa de interfaz web e dos servizos web. É unha capa que está constituida por clases que capturan as regras existentes no dominio da aplicación - planificación de empresas do naval -. Nela existen dous tipos de clases:
+   - **Entidades**. Son clases que representan conceptos que teñen persistencia no dominio. Quere dicir esto que representan datos
+     que se van almacenar. Ademáis, levan asociado comportamento que ten que ver cos datos que representa a entidade.
+   - **Clases de comportamento**. Nalgúns caso pode haber clases que teñen únicamente comportamento e non datos. Esto se deseña na
+     arquitectura cando se quere reutilizar o comportamento entre varias entidades ou cando desacoplalo da entidade proporciona maior
+     flexibilidade e esta é requerida.
+
+Aplícase, por tanto, na arquitectura o patrón de deseño *Domain Model* [1]_. Básicamente consiste en que sexan os obxectos do dominio os que capturen o comportamento de maneira que a reutilización deste comportamento se leva a cabo a través destes obxectos. Como estes obxectos son usados polas capas superiores e teñen o comportamento embebido neles conséguese esta reutilización independentemente do servicio no cal se usan. Esto evita que se cometan erros e se duplique código.
+
+
+.. [1] Patterns of enterprise application architecture. Martin Fowler.
+
+Capa de persistencia
+--------------------
+
+A capa de persistencia atópase por debaixo da capa de lóxica de negocio e é a encargada da gravación das entidades na base de datos. Na aplicación utilízase unha solución ORM - Object Relational Mapping - para o mapeo das clases que representan os obxectos do dominio a súa representación en táboas de bases de datos relacionais. Esta solución ORM se encarga tanto de convertir a entidades as consultas que se lanzan sobre o sistema de persistencia como de facer a tradución das entidades ás filas correspondentes das táboas da base de datos.
+
+A solución arquitectónica usada na capa de persistencia permite que o programa se poida executar sobre diferentes bases de datos.
+
+Non se inclúen directamente sentencias SQL no código do programa, senón que en base a unha linguaxe propia do ORM se traducen as sentencias SQL adecuadas a cada sistema xestor de base de datos.
+
+O ORM utilizado é Hibernate.
+
+Tecnoloxías usadas e relación con cada capa
+===========================================
+
+
+Spring Framework
+----------------
+
+Spring Framework principalmente é un framework que proporciona un contedor de inxección de depedencias que permite a implementación do patrón de deseño IoC [2]_.
+
+Resumidamente este principio de deseño permite desacoplar, é dicir, facer independentes, unhas parte dun programa de outras. Facendo independentes unhas partes de outras propicia que a arquitectura do programa permita cousas como cambiar unha determinada implementación por outra e que as cousas sigan a funcionar. Por exemplo, Navalplan permite a sustitución do ORM que implementa agora mesmo a persistencia, Hibernate, por outro ORM ou outra solución de almacenamento como usar directamente JDBC.
+
+A través do contedor de inxección de dependencias tamén se permite xestionar o ciclo de vida dos obxectos que se crean recorrendo ao contedor - *beans* de Spring -. Por exemplo, pódese configurar que un *bean* teña ámbito *Singleton* [3]_ ou ben que se devolva unha nova instancia da clase do *bean* cada vez que se solicita unha nova referencia ao contedor.
+
+Ademáis de cómo contedor lixeiro de inxección de dependencias Spring Framework úsase na aplicación con outras finalidades:
+
+   - **Cómo xestor das transaccións para Hibernate**. Utilízase Spring para a xestión das transacción a través do ORM que se usa na
+     arquitectura Hibernate. De maneira declarativa a través de Spring se abren e xestionan as sesións de persistencia de Hibernate e
+     se manexan as transaccións das operacións coa base de datos.
+   - **Como planificador de tarefas**. Hai determinadas operacións que hai que executar periódicamente durante a execución da aplicación e, para elo, a través de Spring faise uso do *scheduler Quartz* [4]_.
+   - **Nos tests de unidade Spring TestContext**. Para a realización das probas de unidade úsase o framework *JUnit*. Agora ben, non se fai directamente senón a través da sección de Spring denominada como *Spring TestContext*. Con esta parte permítese utilizar *JUnit* de forma declarativa sen anotacións e, incluso, ser agnósticos de JUnit xa que permite que sexa sustituido por outro framework como *TestNG*.
+
+.. [2] Inversion de control
+.. [3] Ver http://en.wikipedia.org/wiki/Singleton_pattern
+.. [4] Ver http://www.opensymphony.com/quartz/
+
+Framework ZK
+------------
+
+Na interfaz web para proporcionar a experiencia de usuario desexada elixiouse o uso do framework ZK. ZK é un framework Java/Javascript construido sobre a especificación de Servlets. Desta maneira, para desplegar a aplicación web necesítase un contedor de Servlets.
+
+ZK defínese como un framework orientado a eventos baseado en compoñentes que ten por obxectivo permitir a programación de interfaces ricos na web. ZK está composto por un motor AJAX orientado a eventos, un conxunto de compoñentes XUL [5]_ ou XHTML e unha linguaxe de etiquetas denominada ZUML - *ZK User interface Modeling Language* - que permite especificar como se compoñen as distintas páxinas dunha aplicación web mediante a escritura de ficheiros ZUML.
+
+A filosofía de traballo co framework ZK consiste en representar a aplicación a través de compoñentes ricos XUL e XHTML e en manipular
+estes compoñentes a través da captura dos eventos que son disparados froito da interacción do usuario coa aplicación. Isto consiste en
+trasladar o modelo de programación levado a cabo nas aplicacións de escritorio á web. AJAX é usado como medio de comunicación entre os
+eventos lanzados froito da interacción de usuario e o contedor de Servlets. A utilización de AJAX por parte do framework para levar a cabo esta comunicación é transparente para o programador, o cal permite incrementar a produtividade ao verse o programador libre de non ter que xestionar todos estes eventos a través da tecnoloxía AJAX. Desta maneira, co framework ZK simplifícase o desenvolvemento de aplicacións ricas AJAX dos modos seguintes:
+
+   - O motor orientado a eventos permite utilizar o modelo de programación intuitivo do escritorio e levalo a web. Os compoñentes XUL e XHTML proporcionan ao usuario bloques para a construción de interfaces web reutilizables e que fan esta labor vistosa e produtiva.
+   - A utilización do linguaxe de etiquetas ZUML permite ao desenvolvedor especificar como son as pantallas da aplicación web dunha maneira comparable a como se pode especificar como é unha páxina HTML estática.
+
+Ademais de presentar todas as vantaxes anteriores para o desenvolvedor de cara o resultado co usuario, unha característica que debe ser apreciada é a capacidade do framework de proporcionar interfaces ricas que, sen lugar a dúbidas, aumentan a experiencia do usuario en varios frontes:
+
+   - Por unha banda, os compoñentes XUL e XHTML son compoñentes baseados en AJAX e con Javascript que manipula o DOM. Isto permite que os cambios que hai nunha páxina se efectúen manipulando o HTML e non tendo que recargar toda a páxina, o cal fai que o tempo de resposta e a experiencia do usuario mellore considerablemente.
+   - A través de Javascript tanto os compoñentes proporcionados polo framework, como os que pode implementar o desenvolvedor, poden proporcionar efectos e formas de interacción dinámicos que fan a experiencia máis produtiva e intuitiva. Por exemplo, pódese citar o efecto de arrastrar e soltar, elementos dinámicos á hora de despregar listados, mostrar elementos, etc...
+   - ZK está baseado en HTML e Javascript e soporta os principais navegadores do mercado. Debido a isto ten como vantaxe este framework que pode ser accedida a súa funcionalidade avanzada usando un navegador estándar.
+
+Esquema de funcionamento AJAX
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Agora explicarase moi brevemente a través dunha figura como ZK implementa o comportamento descrito, como transparentemente ao
+usuario e coa utilización de Ajax leva o modelo baseado en eventos do escritorio á web.
+
+.. figure:: images/zk_architecture.png
+   :scale: 75
+   :align: center
+
+   Diagrama de arquitectura de ZK framework.
+
+Pódense observar no diagrama 3 partes:
+   - ZK Loader. É conxunto de Servlet Java que se encarga de responder as peticións normais HTTP do navegador web.
+   - ZK AU Engine. Conxunto de Servlets que se encarga de recibir/responder as peticións Ajax.
+   - ZK Client Engine. Código Javascript que se encarga de actualizar o DOM e capturar os eventos do usuario.
+
+O mecanismo representado é o seguinte:
+   1. O ZK Loader interpreta unha petición entrante e xera a correspondente páxina HTML, incluíndo HTML, CSS, código Javascript usando compoñentes ZK no lado do servidor.
+   2. O ZK Loader envía unha páxina HTML ao cliente e ao ZK Client Engine. O ZK Client Engine reside na parte do cliente para monitorizar os eventos Javascript enviados polo browser.
+   3. Se calquera evento Javascript é lanzado, o ZK Client Engine envía estes eventos, a través de peticións Ajax, ao ZK AU Engine.
+   4. O ZK AU Engine recibe as peticións AJAX, actualiza as propiedade dos compoñentes ZK e envía a resposta Ajax de volta a parte cliente.
+   5. O ZK Client Engine recibe a resposta e actualiza os cambios indicados na árbore DOM do browser.
+
+O uso de ZK abrangue únicamente á capa de presentación - interfaz web - de maneira que é fai que a aplicación sexa independente deste framework en capas inferiores.
+
+Unha característica arquitectónica de ZK remarcable é que un framework centrado no servidor. Esta frase significa que os widgets que conforman as páxinas dunha aplicación web existen como obxectos na parte servidora (contedor de Servlets) e é o propio framework o que xestiona toda a complexidade de por en comunicación o navegador de usuario coa parte servidora. A captura de eventos no navegador, o seu transporte ata o servidor, a comunicación dos cambios que se fagan no servidor nun widget ata o navegador e a modificación do DOM para reflexar estes cambios é feito de forma transparente polo framework ZK.
+
+Esto fai que sexa fácil aplicar o patrón MVC, explicado con anterioridade. En particular ZK ocúpase exclusivamente da parte de vista e interven un pouco na parte do controlador. O programador toma o control dende o controlador ata o modelo. O diagrama seguinte explica como se materializa con ZK o patrón MVC.
+
+.. figure:: images/mvc_zk.png
+   :scale: 75
+   :align: center
+
+   Patrón MVC aplicado en ZK framework
+
+A parte de vista, a cargo de ZK, como se ve, está formada por dúas partes: A parte servidora, e a parte HTML/Javascript. A parte servidora está constituida por obxectos Java que representan os widgets presentes no navegador nunha determinada páxina e a parte de HTML/Javascript é a renderización do widget a través de elementos HTML e JS.
+
+
+.. [5] XUL. XML-based User interface Language. Aplicación de XML para describir unha interfaz de usuario. É usada por Firefox.
+
+Timeplot
+--------
+
+
+
+TODO
+----
+      * Ferramentas externas: Cutycap
+      * JFreeChart.
+      * YUI. Libreria Javascript para compoñentes.
+      * JasperReports para informes.
+      * Jgrapht. Grafo de tarefas.
    * Servicios web REST.
-      * Apache CXF. Para
+      * JAX-RS API.
-
+      * Apache CXF.
-
+   * Framework Spring security. Para autenticación.
-
+   * Hibernate Validator para validacións.
+   * Framework auxiliares:
+      * JODA
+      * Gettext para internacionalizacion.
+      * Apache Math.
 
 Relación das capas cos paquetes e módulos do proxecto
 =====================================================