Se arregla el bug que hacia que el cliente levante mal archivos XML grandes.

[z.facultad/75.42/plaqui.git] / docs / manual_proyecto.lyx

diff --git a/docs/manual_proyecto.lyx b/docs/manual_proyecto.lyx
index ea90816f0a9cae8d85123a58439f401117708308..c39f71a0708e453ac91fa31c8ab89edac6f82fd0 100644 (file)
--- a/docs/manual_proyecto.lyx
+++ b/docs/manual_proyecto.lyx
@@ -1,18 +1,23 @@
 #LyX 1.3 created this file. For more info see http://www.lyx.org/
 \lyxformat 221
 #LyX 1.3 created this file. For more info see http://www.lyx.org/
 \lyxformat 221

-\textclass article
+\textclass book

 \language spanish
 \inputencoding auto
 \language spanish
 \inputencoding auto

-\fontscheme default
+\fontscheme palatino

 \graphics default
 \paperfontsize default
 \graphics default
 \paperfontsize default

+\spacing single 

 \papersize Default
 \paperpackage a4
 \papersize Default
 \paperpackage a4

-\use_geometry 0
+\use_geometry 1

 \use_amsmath 0
 \use_natbib 0
 \use_numerical_citations 0
 \paperorientation portrait
 \use_amsmath 0
 \use_natbib 0
 \use_numerical_citations 0
 \paperorientation portrait

+\leftmargin 1.5cm
+\topmargin 1.5cm
+\rightmargin 2.5cm
+\bottommargin 1.5cm

 \secnumdepth 3
 \tocdepth 3
 \paragraph_separation indent
 \secnumdepth 3
 \tocdepth 3
 \paragraph_separation indent


@@ -25,7 +30,14 @@
 
 \layout Title
 
 
 \layout Title
 

-Manual del Proyecto PlaQui
+Manual del Proyecto
+\newline 
+PlaQui
+\layout Author
+
+Taller de Programación I
+\newline 
+Universidad de Buenos Aires

 \layout Standard
 
 
 \layout Standard
 
 


@@ -34,66 +46,702 @@ Manual del Proyecto PlaQui
 \end_inset 
 
 
 \end_inset 
 
 

+\layout Chapter
+
+Integrantes.
+\layout Itemize
+
+Nicolás Dimov (77.624)
+\layout Itemize
+
+Leandro Lucarella (77.891)
+\layout Itemize
+
+Ricardo Markiewicz (78.226)
+\layout Chapter
+
+Programas de Prueba.
+\layout Standard
+
+Los programas de prueba se pueden encontrar en la carpeta 
+\emph on 
+tests
+\emph default 
+, allí se almacenaron los primeros ejecutables con los cuales se experimentó
+ en temas que no se habían visto hasta el momento como 
+\emph on 
+drag&drop
+\emph default 
+, 
+\emph on 
+threads
+\emph default 
+ y 
+\emph on 
+sockets
+\emph default 
+.
+\layout Standard
+
+Con la ayuda de la herramienta subversion no fue necesario ir guardando
+ versiones parciales del proyecto, ya que subversion guarda en un repositorio
+ todas las versiones intermedias por nosotros, a las cuales se puede acceder
+ en cualquier momento.
+ Para obtener una versión particular del proyecto basta ejecutar:
+\layout LyX-Code
+
+svn co -r[rev|{fecha}] http://svn.llucax.hn.org/svn/plaqui/
+\layout Standard
+
+Donde 
+\family typewriter 
+-r
+\family default 
+ toma un parámetro que puede ser el número de revisión que se quiere obtener
+ (
+\family typewriter 
+rev
+\family default 
+) o una fecha ingresada entre llaves (
+\family typewriter 
+{fecha}
+\family default 
+).
+ Por ejemplo para obtener la revisión 1 se puede hacer:
+\layout LyX-Code
+
+svn co -r1 http://svn.llucax.hn.org/svn/plaqui/
+\layout Standard
+
+Y para obtener la versión de la fecha de la pre-entrega se puede hacer:
+\layout LyX-Code
+
+svn co -r'{2003-11-20 18:00}' http://svn.llucax.hn.org/svn/plaqui/
+\layout Standard
+
+Es por esto que nos pareció que no tenía mucho sentido acompañar este manual
+ con una versión particular del repositorio en un momento dado.
+\layout Chapter
+
+Evolución del proyecto.
+\layout Standard
+
+La evolución del proyecto también se documentó a través del subversion,
+ ya que a cada versión que se sube al servidor se la acompaña de un comentario
+ sobre los avances realizados.
+ Para ver el mensaje de cualquier cambio realizado en una revisión 
+\family typewriter 
+X
+\family default 
+ se puede hacer:
+\layout LyX-Code
+
+svn log -rX http://svn.llucax.hn.org/svn/plaqui/
+\layout Standard
+
+Para ver todos los mensajes basta con:
+\layout LyX-Code
+
+svn log -r0:HEAD http://svn.llucax.hn.org/svn/plaqui/
+\layout Standard
+
+Por conveniencia, en el directoria raíz del código fuente entregado en el
+ CD se encuentra un archivo 
+\family typewriter 
+ChangeLog
+\family default 
+ con los mensajes de todas las revisiones del proyecto.
+\layout Standard
+
+A continuación se muestra una gráfica generada con un 
+\emph on 
+script
+\emph default 
+ hecho en Perl (
+\family typewriter 
+log_trace.pl
+\family default 
+, que se adjunta en el CD) que indica la cantidad de 
+\emph on 
+commits
+\emph default 
+ (cambios de versión) que se hicieron día a día, donde cada 
+\family typewriter 
+*
+\family default 
+ representa un 
+\emph on 
+commit
+\emph default 
+.
+\layout LyX-Code
+
+PlaQui - Grafica de Progreso SVN
+\layout LyX-Code
+
+--------------------------------
+\layout LyX-Code
+
+Fech            Commits
+\layout LyX-Code
+
+2003-10-08      **                                                     
+  (luca)
+\layout LyX-Code
+
+2003-10-10      *****                                                  
+  (luca)
+\layout LyX-Code
+
+2003-10-11      ***                                                    
+  (luca)
+\layout LyX-Code
+
+2003-10-12      **********                                             
+  (rmarkie)
+\layout LyX-Code
+
+2003-10-13      *****                                                  
+  (luca)
+\layout LyX-Code
+
+2003-10-14      *                                                      
+  (rmarkie)
+\layout LyX-Code
+
+2003-10-15      ****                                                   
+  (rmarkie|luca)
+\layout LyX-Code
+
+2003-10-16      *****                                                  
+  (rmarkie)
+\layout LyX-Code
+
+2003-10-17      ************                                           
+  (luca)
+\layout LyX-Code
+
+2003-10-18      **********                                             
+  (luca)
+\layout LyX-Code
+
+2003-10-19      *****                                                  
+  (luca)
+\layout LyX-Code
+
+2003-10-20      ****                                                   
+  (rmarkie)
+\layout LyX-Code
+
+2003-10-21      *****                                                  
+  (luca)
+\layout LyX-Code
+
+2003-10-22      ************                                           
+  (luca)
+\layout LyX-Code
+
+2003-10-23      ******                                                 
+  (rmarkie)
+\layout LyX-Code
+
+2003-10-24      ***********                                            
+  (sagar)
+\layout LyX-Code
+
+2003-10-25      *                                                      
+  (sagar)
+\layout LyX-Code
+
+2003-10-26      **                                                     
+  (sagar|luca)
+\layout LyX-Code
+
+2003-10-28      ***                                                    
+  (sagar)
+\layout LyX-Code
+
+2003-10-29      ***                                                    
+  (luca)
+\layout LyX-Code
+
+2003-11-05      ****                                                   
+  (luca)
+\layout LyX-Code
+
+2003-11-06      **********                                             
+  (rmarkie|luca)
+\layout LyX-Code
+
+2003-11-07      ******                                                 
+  (luca)
+\layout LyX-Code
+
+2003-11-08      *******                                                
+  (sagar)
+\layout LyX-Code
+
+2003-11-09      ****                                                   
+  (luca)
+\layout LyX-Code
+
+2003-11-11      ********                                               
+  (sagar|rmarkie)
+\layout LyX-Code
+
+2003-11-12      ****                                                   
+  (sagar)
+\layout LyX-Code
+
+2003-11-13      *************                                          
+  (rmarkie|luca)
+\layout LyX-Code
+
+2003-11-15      *                                                      
+  (rmarkie)
+\layout LyX-Code
+
+2003-11-16      *******                                                
+  (rmarkie)
+\layout LyX-Code
+
+2003-11-17      *************                                          
+  (luca)
+\layout LyX-Code
+
+2003-11-18      **********************                                 
+  (luca)
+\layout LyX-Code
+
+2003-11-19      ***************                                        
+  (sagar|luca)
+\layout LyX-Code
+
+2003-11-20      ***************************                            
+  (rmarkie)
+\layout LyX-Code
+
+2003-11-21      ****                                                   
+  (luca)
+\layout LyX-Code
+
+2003-11-22      **                                                     
+  (luca)
+\layout LyX-Code
+
+2003-11-23      *****************                                      
+  (luca)
+\layout LyX-Code
+
+2003-11-24      *******                                                
+  (rmarkie|luca)
+\layout LyX-Code
+
+2003-11-25      ******                                                 
+  (rmarkie)
+\layout LyX-Code
+
+2003-11-26      ***                                                    
+  (luca)
+\layout LyX-Code
+
+2003-11-27      ****                                                   
+  (rmarkie)
+\layout LyX-Code
+
+2003-11-28      ***                                                    
+  (luca)
+\layout LyX-Code
+
+2003-11-29      *******                                                
+  (luca)
+\layout LyX-Code
+
+2003-11-30      **********************                                 
+  (rmarkie)
+\layout LyX-Code
+
+2003-12-01      *******************************************************
+  (luca)
+\layout LyX-Code
+
+2003-12-02      *****************************************              
+  (luca)
+\layout LyX-Code
+
+( ) = Máximo/s Commiteador/es del Día
+\layout LyX-Code
+
+* == 2 Commit
+\layout LyX-Code
+
+\layout Standard
+
+Los usuarios son:
+\layout Description
+
+sagar Nicolás Dimov
+\layout Description
+
+luca Leandro Lucarella
+\layout Description
+
+rmarkie Ricardo Markiewicz
+\layout Standard
+
+Vale la pena aclarar que en este gráfico no se muestran la cantidad de líneas
+ modificadas, por lo que una gran cantidad de 
+\emph on 
+commits
+\emph default 
+ no significa necesariamente un gran cambio en el repositorio.
+\layout Chapter
+
+División de Tareas.
+\layout Standard
+
+A continuación se menciona, en términos generales la tarea que realizó cada
+ integrante:
+\layout Description
+
+Leandro\SpecialChar ~
+Lucarella PlaQui Server.
+\layout Description
+
+Ricardo\SpecialChar ~
+Markiewicz PlaQui Model y PlaQui Client.
+\layout Description
+
+Nicolás\SpecialChar ~
+Dimov PlaQui Constructor.
+\layout Standard
+
+Obviamente en algunas circunstancias algún integrante aporto al desarrollo
+ de un módulo que no le estaba asignado.
+ La documentación fue realizada y revisada entre todos los integrantes.
+\layout Chapter
+
+Inconvenientes Encontrados.

 \layout Section
 
 \layout Section
 

-Integrantes:
+Servidor.
+\layout Standard
+
+El Servidor trajo varios problemas, en especial en cuanto al manejo de 
+\emph on 
+sockets
+\emph default 
+ y 
+\emph on 
+threads
+\emph default 
+.
+ El uso de señales (para hacer el servidor orientado a eventos) dio también
+ algunos problemas menores.
+\layout Subsection
+
+
+\emph on 
+Threads
+\emph default 
+.
+\layout Standard
+
+El principal problema de los threads fue el no poder saber fácilmente donde
+ se producía un error, en especial cuando el error venía por la falta de
+ un 
+\emph on 
+mutex
+\emph default 
+.
+ En términos generales, cada vez que el server tenía una violación de segmento
+ se debía a la falta de un 
+\emph on 
+mutex
+\emph default 
+.
+\layout Standard
+
+Otro problema eran las excepciones no manejadas dentro del método 
+\family typewriter 
+real_run()
+\family default 
+ (que se ejecuta en su propio 
+\emph on 
+thread
+\emph default 
+).
+ Aunque se incluía un bloque 
+\family typewriter 
+try ; catch
+\family default 
+ en el programa principal, al ocurrir una excepción en un 
+\emph on 
+thread
+\emph default 
+, dicha excepción no 
+\emph on 
+sube
+\emph default 
+ hasta el hilo padre y el programa sale con 
+\family typewriter 
+abort()
+\family default 
+.
+ Es por esto que cada 
+\family typewriter 
+real_run()
+\family default 
+ tiene su propio bloque 
+\family typewriter 
+try ; catch
+\family default 
+ donde pueda surgir una excepción y se incluyó la 
+\family typewriter 
+signal_error()
+\family default 
+ en 
+\family typewriter 
+Runnable
+\family default 
+ para poder avisar de dicho error a quien lo necesite.
+\layout Subsection
+
+
+\emph on 
+Sockets
+\emph default 
+.

 \layout Standard
 
 \layout Standard
 

-Nicolás Dimov
+El principal problema con los 
+\emph on 
+sockets
+\emph default 
+ fue la imposibilidad (por enunciado) de usar 
+\emph on 
+sockets
+\emph default 
+ no bloqueantes.
+ Esto tuvo particular repercusión en el 
+\family typewriter 
+TCPServer
+\family default 
+, ya que una vez llamado al 
+\family typewriter 
+accept()
+\family default 
+ para aceptar una nueva conexión, esta no retorna hasta que efectivamente
+ se reciba una nueva conexión, haciendo imposible terminar el servidor de
+ otra manera.
+ Para resolver esto, al finalizar el 
+\family typewriter 
+TCPServer
+\family default 
+ se hace una 
+\emph on 
+conexión suicida
+\emph default 
+ para hacer que la llamada a 
+\family typewriter 
+accept()
+\family default 
+ retorne y el servidor pueda ser cerrado limpiamente.
+\layout Subsection
+
+Señales.

 \layout Standard
 
 \layout Standard
 

-Ricardo Markiewicz
+La señales no dieron mayores problemas.
+ El único inconveniente es que complican la depuración del programa, ya
+ que uno no sabe de antemano quien las atenderá y se hace difícil seguir
+ el flujo del mismo.
+\layout Subsection
+
+Falencias.

 \layout Standard
 
 \layout Standard
 

-Leandro Lucarella
+El Server está preparado para servir (y simular) una cantidad indeterminada
+ de plantas.
+ Por problemas de tiempo esto no se llegó a implementar correctamente en
+ el programa, en particular por la complicación que traería implementar
+ dicha función en el cliente.

 \layout Section
 
 \layout Section
 

-Programas de Prueba:
+Constructor.

 \layout Standard
 
 \layout Standard
 

-Los programas de prueba se pueden encontrar en /plaqui/test, ahi se almacenaron
- los primeros ejecutables con los que luego se comenzó el desarrollo.
+A lo largo del desarrollo nos hemos encontrado con diferentes tipos de problemas
+ los cuales pudieron ser solucionados, en su mayoría, de una forma aceptable.
+ 

 \layout Standard
 
 \layout Standard
 

-Con la ayuda del repositorio ( Subversion ) no fue demasiado necesario ir
- guardando parcialmente el proyecto, ya que este puede ser accedido en cualquier
-a de sus versiones en cualquier momento del desarrollo.
+Al trabajar con imágenes independientes, las verificaciones sobre cada una
+ de estas, dependen mucho de su posición en el área de trabajo y su orientación.
+ Esto provoca que haya que realizar demasiadas validaciones para los diferentes
+ tipos de verificaciones, y trae apareados problemas en la codificación
+ por el uso de gran cantidad de coordenadas.
+\layout Standard
+
+Otro inconveniente no solucionado, fue que las imágenes de cada elemento
+ que se coloca sobre la grilla se crean tantas veces como elementos de ese
+ tipo haya.
+ La idea en un principio fue crear todas estas imágenes estáticas, de modo
+ que para un elemento de cuatro imágenes, se cargarían en memoria solamente
+ esas cuatro imágenes y luego los elementos iguales apuntarían su imagen
+ actual a la que corresponda.
+ Esto no pudo ser solucionado pues no encontramos la forma de inicializar
+ las imágenes de manera estática, se producían errores en el momento del
+ linkeo.
+\layout Standard
+
+Por problemas de tiempo, hubo algunas implementaciones sobre el Constructor
+ luego de cerrado el tema de la documentación, por ejemplo, el Constructor
+ pregunta si quiere guardar el trabajo antes de salir del programa.
+ Esto no fue documentado.

 \layout Section
 
 \layout Section
 

-Cronograma Real:
-\layout Comment
+Cliente.
+\layout Standard

 
 

-aca va el log !!!
+El principal problema del cliente fueron los 
+\emph on 
+threads
+\emph default 
+.
+ El asunto fue descubrir la forma de hacer que las actualizaciones de refresco
+ de las propiedades y la creación dinámica de objetos sea 
+\emph on 
+thread-safe
+\emph default 
+ para garantizar a la Gtk+ cierta estabilidad.
+ Luego de mucho leer se encontró el 
+\family typewriter 
+Glib::Distpatcher
+\family default 
+, que es un evento asíncrono especialmente diseñado para comunicación entre
+ hilos.

 \layout Section
 
 \layout Section
 

-División de Tareas:
+Modelo.

 \layout Standard
 
 \layout Standard
 

-PlaQui-Server a cargo de Leandro Lucarella.
+El Modelo tenía la complicación de la Union.
+ Este elemento es complicado ya que para poder saber el estado a su salida
+ se necesitaba saber el estado a sus 2 entradas, y esta información llegaba
+ en forma asíncrona.
+ Luego de mucho diseño, análisis de todas las combinaciones posibles entre
+ las entradas se llego a un método que resulto exitoso en la mayoría de
+ las pruebas y fue adoptado como definitivo.

 \layout Standard
 
 \layout Standard
 

-PlaQui-Model y PlaQui-Client a cargo de Ricardo Markiewicz.
+Otro inconveniente fue la suma de colores.
+ El ejemplo dado en el enunciado no era para nada correcto.
+ Para solucionar esto nos pusimos en contacto con Nicolás Reyna, estudiante
+ de diseño industrial en la Universidad de La Plata, quien tiene un conocimiento
+ mayor al nuestro acerca del comportamiento de los colores aditivos y su
+ distribución RGB.
+ En base a sus recomendaciones hicimos las sumas de colores en los distintos
+ objetos.

 \layout Standard
 
 \layout Standard
 

-PlaQui Constructor a cargo de Nicolás Dimov.
-\layout Section
+Por último, al verificarse la validez del conexionado de un archivo XML
+ de planta en el Constructor, el Modelo no vuelve a realizar el chequeo,
+ por lo que si se quiere levantar una planta desde un XML invalido los resultado
+s son impredecibles.
+\layout Chapter

 
 

-Inconvenientes Encontrados:
+Conclusiones.

 \layout Standard
 
 \layout Standard
 

-El servidor termina su ejecución si el XML que se le pasa como argumento
- no es válido.
+Se reforzaron los conocimientos en programación C++ y la programación orientada
+ a objetos.
+ El modelo utilizado aplica fuertemente estos conceptos, motivo por el cual
+ no fue necesario utilizar un grafo para verificar los flujos por el circuito
+ creado.

 \layout Standard
 
 \layout Standard
 

-los otros puntos no se como explicarlos (sockets no bloqueantes etc)
-\layout Section
+El programa de desarrollo de interfaces Glade-2, y las bibliotecas Gtk+
+ y Glademm facilitaron mucho la creación del Cliente y el Constructor, y
+ nos hemos familiarizado con sus prestaciones, para crear aplicaciones visuales.
+ 
+\layout Standard
+
+Contamos con la ayuda del subversion y una lista de correos pudimos trabajar
+ a distancia cómodamente, lo cual facilitó muchísimo las cosas y permitió
+ que los tres integrantes del equipo pudiéramos contar con la totalidad
+ del proyecto en todo momento, pudiendo conocer el trabajo de los demás
+ y al mismo tiempo reportar 
+\emph on 
+bugs
+\emph default 
+ o complementar el trabajo de otro.
+ En todo momento estuvimos actualizados sobre el desarrollo.
+ Cabe mencionar que necesitamos juntarnos solamente una vez para distribuirnos
+ las tareas.
+ El resto del trabajo práctico se realizó a distancia.
+\layout Standard

 
 

-Conclusiones Generales:
+Nos ha parecido muy importante haber hecho todo el trabajo con ayuda de
+ herramientas comunes de desarrollo de Software Libre, las cuales dejaron
+ un producto final de una calidad igual o superior a cualquier otro entorno
+ de desarrollo de aplicaciones, sobre todo las aplicaciones visuales que
+ aprovechan un excelente trabajo de la GTK+ que suma un valor agregado como
+ la posibilidad de cambiar la apariencia de la aplicación a través de 
+\emph on 
+themes
+\emph default 
+, sin costo alguno.
+ Esto también nos permitió hacer un trabajo práctico usando 100% software
+ legal, cosa que incluso grandes empresas no pueden realizar en muchos casos
+ (ni hablar un estudiante).

 \layout Standard
 
 \layout Standard
 

-Se reforzaron los conocimientos en programación C++.
+La documentación online generada con el Doxygen, si es bien utilizado, queda
+ muy completa y es muy fácil realizar una búsqueda con la ayuda de un navegador.
+ Esto puede comprobarse con la documentación online de la biblioteca Gtkmm
+ (
+\family typewriter 
+www.gtkmm.org
+\family default 
+).
+ La documentación en formato HTML del proyecto se encuentra en el CD y en

  
  

+\family typewriter 
+http://www.llucax.hn.org/plaqui/docs/html/
+\family default 
+.
+\layout Standard
+
+Hubo algunas ideas que no pudieron ser implementadas por cuestión de tiempo,
+ y la documentación estaba programada para realizarse en cuatro días, pero
+ tres días antes de la entrega nos enteramos que debíamos entregar el Martes,
+ siendo que nosotros cursábamos los Jueves, lo que redujo el tiempo de documenta
+ción a sólo dos días.
+ Aún así creemos que se logró hacer un trabajo muy completo de documentación,
+ en parte gracias a Doxygen (como se dijo antes) porque a medida que íbamos
+ escribiendo el código lo íbamos documentando en línea.
+\layout Standard
+
+En general estamos muy conformes con el trabajo y la forma en la cuál fue
+ realizado, cumplimos los requisitos pedidos por el enunciado y creemos
+ que lo hicimos de una manera correcta.

 \layout Standard
 
 \layout Standard
 

-Nos familiarizamos con las bibliotecas Gtk+.
+El proyecto completo es entregado en un CD que puede ser leído desde cualquier
+ sistema operativo en cualquier tipo de lectora, pero también es un CD 
+\emph on 
+booteable
+\emph default 
+ con lo cual no es necesario ni siquiera tener un sistema operativo instalado
+ o un disco rígido para poder operar el PlaQui.
+ Basta activar la opción de 
+\emph on 
+booteo
+\emph default 
+ desde el CD en el 
+\emph on 
+BIOS
+\emph default 
+ y colocar el CD.

 \the_end
 \the_end