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 96664cfbd94ed73fa3f4fdab6c93109da3600e1e..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,7 +46,7 @@ Manual del Proyecto PlaQui
 \end_inset 
 
 
 \end_inset 
 
 

-\layout Section
+\layout Chapter

 
 Integrantes.
 \layout Itemize
 
 Integrantes.
 \layout Itemize


@@ -46,18 +58,35 @@ Leandro Lucarella (77.891)
 \layout Itemize
 
 Ricardo Markiewicz (78.226)
 \layout Itemize
 
 Ricardo Markiewicz (78.226)

-\layout Section
+\layout Chapter

 
 Programas de Prueba.
 \layout Standard
 
 
 Programas de Prueba.
 \layout Standard
 

-Los programas de prueba se pueden encontrar en tests, allí se almacenaron
- los primeros ejecutables con los que luego se comenzó el desarrollo.
+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
 \layout Standard
 
 Con la ayuda de la herramienta subversion no fue necesario ir guardando

- parcialmente el proyecto, ya que subversion guarda en un repositorio todas
- las versiones intermedias del proyecto.
+ 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
 
  Para obtener una versión particular del proyecto basta ejecutar:
 \layout LyX-Code
 


@@ -68,7 +97,7 @@ Donde
 \family typewriter 
 -r
 \family default 
 \family typewriter 
 -r
 \family default 

- toma un parametro que puede ser el número de revisión que se quiere obtener
+ toma un parámetro que puede ser el número de revisión que se quiere obtener

  (
 \family typewriter 
 rev
  (
 \family typewriter 
 rev


@@ -84,7 +113,7 @@ rev
 svn co -r1 http://svn.llucax.hn.org/svn/plaqui/
 \layout Standard
 
 svn co -r1 http://svn.llucax.hn.org/svn/plaqui/
 \layout Standard
 

-Y para obtener la versión de la fecha de la preentrega se puede hacer:
+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 LyX-Code
 
 svn co -r'{2003-11-20 18:00}' http://svn.llucax.hn.org/svn/plaqui/


@@ -92,7 +121,7 @@ svn co -r'{2003-11-20 18:00}' http://svn.llucax.hn.org/svn/plaqui/
 
 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.
 
 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 Section
+\layout Chapter

 
 Evolución del proyecto.
 \layout Standard
 
 Evolución del proyecto.
 \layout Standard


@@ -117,14 +146,261 @@ 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
 \layout Standard
 
 Por conveniencia, en el directoria raíz del código fuente entregado en el

- CD se encuentra un archivo ChangeLog con los mensajes de todas las revisiones
- del proyecto.
-\layout Section
+ 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
 
 
 División de Tareas.
 \layout Standard
 

-A continuación se menciona, en terminos generales la tarea que realizó cada
+A continuación se menciona, en términos generales la tarea que realizó cada

  integrante:
 \layout Description
 
  integrante:
 \layout Description
 


@@ -143,22 +419,156 @@ Dimov PlaQui Constructor.
 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.
 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 Section
+\layout Chapter

 
 Inconvenientes Encontrados.
 
 Inconvenientes Encontrados.

+\layout Section
+
+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
 
 \layout Subsection
 

-Servidor:
+
+\emph on 
+Threads
+\emph default 
+.

 \layout Standard
 
 \layout Standard
 

-El servidor termina su ejecución si el XML que se le pasa como argumento
- no es válido.
-\layout Comment
+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

 
 

-los otros puntos no se como explicarlos (sockets no bloqueantes etc)
+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
 
 \layout Subsection
 

-Constructor:
+
+\emph on 
+Sockets
+\emph default 
+.
+\layout Standard
+
+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
+
+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
+
+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
+
+Constructor.

 \layout Standard
 
 A lo largo del desarrollo nos hemos encontrado con diferentes tipos de problemas
 \layout Standard
 
 A lo largo del desarrollo nos hemos encontrado con diferentes tipos de problemas


@@ -166,7 +576,7 @@ A lo largo del desarrollo nos hemos encontrado con diferentes tipos de problemas
  
 \layout Standard
 
  
 \layout Standard
 

-Al tabajar con imágenes independientes, las verificaciones sobre cada una
+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
  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


@@ -180,22 +590,68 @@ Otro inconveniente no solucionado, fue que las im
  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.
  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 pués no encontramos la forma de inicializar
+ 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.
  las imágenes de manera estática, se producían errores en el momento del
  linkeo.

-\layout Subsection
+\layout Standard

 
 

-Cliente:
-\layout Comment
+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

 
 

-La suma de los colores...
- solucionado.
-\layout Comment
+Cliente.
+\layout Standard

 
 

-que mas????
+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
 

-Conclusiones Generales.
+Modelo.
+\layout Standard
+
+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
+
+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
+
+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
+
+Conclusiones.

 \layout Standard
 
 Se reforzaron los conocimientos en programación C++ y la programación orientada
 \layout Standard
 
 Se reforzaron los conocimientos en programación C++ y la programación orientada


@@ -205,6 +661,87 @@ Se reforzaron los conocimientos en programaci
  creado.
 \layout Standard
 
  creado.
 \layout Standard
 

-Las bibliotecas Gtk+ y Glademm facilitaron mucho la creación del Cliente
- y el Constructor, y nos hemos familiarizado con sus prestaciones.
+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
+
+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
+
+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
+
+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