Se agrega un poco mas de documentacion como para cerrar el manual de desarrollo.

[z.facultad/75.42/plaqui.git] / Server / include / plaqui / server / documentacion.h

diff --git a/Server/include/plaqui/server/documentacion.h b/Server/include/plaqui/server/documentacion.h
index ddf5a026e652554bb9d5370b4b3ea45781bf8bfb..ea3c53e5dcb0009111bfd86c513ad401c0ca6973 100644 (file)
--- a/Server/include/plaqui/server/documentacion.h
+++ b/Server/include/plaqui/server/documentacion.h
@@ -1,6 +1,6 @@
 /** \page page_server PlaQui Server
 
 /** \page page_server PlaQui Server
 

-\section page_server_general Descripción General
+\section page_server_general Descripción General.

        El servidor está dividido en 2 módulos que provean 2 servicios diferentes.
 
        \subsection page_server_general_control Módulo de Control.
        El servidor está dividido en 2 módulos que provean 2 servicios diferentes.
 
        \subsection page_server_general_control Módulo de Control.


@@ -23,6 +23,21 @@
                Este módulo está implementado por las clases PlaQui::Server::ControlServer
                y PlaQui::Server::ControlClient.
 
                Este módulo está implementado por las clases PlaQui::Server::ControlServer
                y PlaQui::Server::ControlClient.
 

+               \subsubsection page_server_general_control_http Ventajas del protocolo HTTP.
+                       Las ventajas de montar el protocolo del servidor sobre el protocolo
+                       HTTP son muchas. Las más destacables son las más obvias.
+
+                       Al usar el protocolo HTTP se puede controlar el servidor con
+                       cualquier navegador web. Al ser las respuestas archivos XML es
+                       fácil agregar hojas de estilo XSLT para convertirlas en HTML y
+                       transformar un navegador web con capacidad de procesar hojas XSLT
+                       (como Mozilla) en un cliente casi con las mismas capacidades y
+                       facilidad de uso que uno hecho especialmente para PlaQui.
+
+                       Otra ventaja importante es que muchos lugares sin acceso real a
+                       Internet tienen acceso a un proxy HTTP, por lo que la accesibilidad
+                       del servicio se vuelve muy fácil incluso en redes muy protegidas.
+

        \subsection page_server_general_transmision Módulo de Transmisión.
                Este módulo se encarga de transmitir la simulación en tiempo real por UDP
                (como si fuera un video). Comienza luego de que el módulo de control recibe
        \subsection page_server_general_transmision Módulo de Transmisión.
                Este módulo se encarga de transmitir la simulación en tiempo real por UDP
                (como si fuera un video). Comienza luego de que el módulo de control recibe


@@ -42,7 +57,6 @@
                Este módulo está implementado por las clases PlaQui::Server::Transmitter y
                PlaQui::Server::Receiver.
 
                Este módulo está implementado por las clases PlaQui::Server::Transmitter y
                PlaQui::Server::Receiver.
 

-

 \section page_server_protocolo Comandos del Módulo de Control.
        Todos los comandos son rutas de archivos. En un principio no se van a utilizar
        los <em>query string</em> de los datos pasados por GET ni datos adicionales
 \section page_server_protocolo Comandos del Módulo de Control.
        Todos los comandos son rutas de archivos. En un principio no se van a utilizar
        los <em>query string</em> de los datos pasados por GET ni datos adicionales


@@ -78,8 +92,8 @@
                <table>
                        <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
                        <tr>
                <table>
                        <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
                        <tr>

-                               <td><tt>status</tt></td>
-                               <td>Obtiene estado general del servidor.</td>
+                               <td><tt>info</tt></td>
+                               <td>Obtiene información sobre el servidor.</td>

                                <td>Cantidad de plantas, conexiones, transmisiones, versión,
                                    uptime, etc.</td>
                        </tr>
                                <td>Cantidad de plantas, conexiones, transmisiones, versión,
                                    uptime, etc.</td>
                        </tr>


@@ -107,7 +121,7 @@
                                <td>Nada.</td>
                        </tr>
                </table>
                                <td>Nada.</td>
                        </tr>
                </table>

-               \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
+               \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.

 
        \subsection page_server_protocolo_transmision Comandos para una Transmisión.
                Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
 
        \subsection page_server_protocolo_transmision Comandos para una Transmisión.
                Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>


@@ -121,8 +135,8 @@
                                    etc).</td>
                        </tr>
                        <tr>
                                    etc).</td>
                        </tr>
                        <tr>

-                               <td><tt>start/[plant]/[host]/[port]</tt></td>
-                               <td>Comienza la transmisión de la planta [plant] al [host]
+                               <td><tt>start/[pl]/[host]/[port]</tt></td>
+                               <td>Comienza la transmisión de la planta [pl] al [host]

                                    en el puerto [port].</td>
                                <td>Nada.</td>
                        </tr>
                                    en el puerto [port].</td>
                                <td>Nada.</td>
                        </tr>


@@ -133,7 +147,7 @@
                                <td>Nada.</td>
                        </tr>
                </table>
                                <td>Nada.</td>
                        </tr>
                </table>

-               \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
+               \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.

 
        \subsection page_server_protocolo_planta Comandos para una Planta.
                Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con
 
        \subsection page_server_protocolo_planta Comandos para una Planta.
                Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con


@@ -147,34 +161,94 @@
                                    corriendo o no, uptime, cantidad de elementos,etc).</td>
                        </tr>
                        <tr>
                                    corriendo o no, uptime, cantidad de elementos,etc).</td>
                        </tr>
                        <tr>

-                               <td><tt>get/[planta]</tt></td>
-                               <td>Obtiene la planta de nombre [planta].</td>
+                               <td><tt>get/[pl]</tt></td>
+                               <td>Obtiene la planta de nombre [pl].</td>

                                <td>El mismo archivo que se crea en el Constructor.</td>
                        </tr>
                        <tr>
                                <td>El mismo archivo que se crea en el Constructor.</td>
                        </tr>
                        <tr>

-                               <td><tt>stop/[planta]</tt></td>
-                               <td>Finaliza la simulación de la planta de nombre <planta>.</td>
+                               <td><tt>set/[pl]/[el]/[pr]/[val]</tt></td>
+                               <td>Cambia la propiedad [pr] del elemento [el], asignándole
+                                   el valor [val] a planta de nombre [pl].</td>

                                <td>Nada.</td>
                        </tr>
                        <tr>
                                <td>Nada.</td>
                        </tr>
                        <tr>

-                               <td><tt>set/[planta]/[elem]/[prop]/[val]</tt></td>
-                               <td>Cambia la propiedad [prop] del elemento [elem], asignándole
-                                   el valor [val] a planta de nombre [planta].</td>
+                               <td><tt>set_frequency/[pl]/[hz]</tt></td>
+                               <td>Cambia la frecuencia de refresco de la simulación de la
+                                   planta de nombre [pl] a [hz] veces por segundo. Si [hz]
+                                   es cero ("0"), se usa la frecuencia de refresco por
+                                   omisión del servidor.</td>
+                               <td>Nada.</td>
+                       </tr>
+                       <tr>
+                               <td><tt>start/[pl]</tt></td>
+                               <td>Reanuda (o comienza) la simulación de la planta de nombre
+                                   [pl].</td>
+                               <td>Nada.</td>
+                       </tr>
+                       <tr>
+                               <td><tt>stop/[pl]</tt></td>
+                               <td>Pausa la simulación de la planta de nombre
+                                   [pl].</td>
+                               <td>Nada.</td>
+                       </tr>
+                       <tr>
+                               <td><tt>remove/[pl]</tt></td>
+                               <td>Finaliza la simulación de la planta de nombre
+                                   [pl] eliminandola del servidor.</td>

                                <td>Nada.</td>
                        </tr>
                </table>
                                <td>Nada.</td>
                        </tr>
                </table>

-               \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
+               \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
+
+\section page_server_respuesta Respuestas del Módulo de Control.
+       Las respuestas del servidor, como se dijo anteriormente, son respuestas HTTP, cuyo
+       cuerpo es un archivo XML. Este archivo se compone de un <em>tag</em> XML
+       <tt>plaqui-response</tt> y tiene como atributos obligatorios <tt>code</tt> (indica
+       el \ref PlaQui::Server::Response::Code "código de respuesta", para saber si se
+       realizó bien el comando) y <tt>version</tt> (indica la versión del formato del
+       archivo XML, para preveer la posibilidad de que cambie en futuras versiones).
+       También tiene un atributo opcional <tt>description</tt> que permite agregar una
+       descripción sobre la respuesta, útil para observar respuestas con un navegador u
+       otro cliente no específico. El <em>tag</em>plaqui-response</em> puede tener un
+       contenido, en caso de que la respuesta necesite enviar información al cliente
+       (como al obtener una planta o una lista). El contenido es a su vez XML y en el
+       caso de la obtención de una planta tiene el mismo formato que el utilizado por el
+       Constructor.
+
+\section page_server_implementacion Destalles de la implementación.
+       El servidor se basa en un la clase PlaQui::Server::Runnable que se utiliza para
+       encapsular un hilo de ejecución. De ella derivan todas las demás clases
+       importantes del servidor: PlaQui::Server::TCPServer y PlaQui::Server::Connection.
+       De esta última derivan todas las posibles conexiónes que hay para la comunicación
+       entre el servidor y el cliente: PlaQui::Server::ControlClient,
+       PlaQui::Server::ControlServer, PlaQui::Server::Receiver y
+       PlaQui::Server::Transmitter. Las dos primeras son utilizadas para la conexión
+       de control y las dos segundas para la transmisión del estado de la planta por
+       UDP.
+
+       El protocolo HTTP se encapsula en la clases PlaQui::Sever::HTTPMessage y de ella
+       derivan PlaQui::Sever::HTTPRequest (petición HTTP) y PlaQui::Sever::HTTPResponse
+       (respuesta HTTP). Hay otras clases auxiliares como PlaQui::Sever::HTTPError que
+       encapsula un error HTTP.

 
 

-\section page_server_uso Modo de uso.
-       Para utilizar el servidor es necesario disponer de un archivo XML de planta
-       (por ejemplo, generado por el Constructor).
+       Finalmente, para abstraerse del protocolo HTTP que se usa de transporte, se
+       implementan dos clases: PlaQui::Sever::Command y PlaQui::Sever::Response que
+       representan un comando y una respuestas específicos del servidor PlaQui.

 
 

-       Invocación del servidor:
-       \verbatim ./plaqui-server [planta.xml] [puerto] \endverbatim
+       A continuación se incluye un diagrama de clases para tener una visión más general
+       de las clases más importantes utiilzadas en el servidor:
+               \image html cliente_servidor.png
+               \image latex cliente_servidor.eps "Diagrama de clases." width=14cm

 
 

-       Ambos argumentos son opcionales. El primero, <tt>[planta.xml]</tt>, es la
-       ubicación del archivo con la descripción de la planta a simular (por omisión
-       <tt>prueba.xml</tt>). El segundo, <tt>[puerto]</tt>, es el puerto en el cual
-       se van a atender las peticiones al servidor (por omisión 7522).
+*/
+
+/** \namespace PlaQui::Server
+
+Infrastructura cliente-servidor para PlaQui.
+
+Bajo este espacio de nombres (namespace) se encuentran todas las clases para la
+comunicación cliente-servidor de PlaQui. Esto no incluye la interfaz gráfica del
+cliente.

 
 */
 
 */

+