Server/include/plaqui/server/documentacion.h

   1 /** \page page_server PlaQui Server
   2
   3 \section page_server_general Descripción General.
   4         El servidor está dividido en 2 módulos que provean 2 servicios diferentes.
   5
   6         \subsection page_server_general_control Módulo de Control.
   7                 El módulo de control se basa en el protocolo TCP y se encarga de listar
   8                 los archivos de planta disponibles en el servidor, permitiendo cambiar
   9                 las propiedades de cada uno y conocer su estado en términos generales
  10                 (si se está simulando o no). Todo lo que sean comandos (abrir una
  11                 exclusa, parar una bomba, etc) se realizan a través de este módulo.
  12                 El protocolo utilizado es una implementación limitada e incompleta de
  13                 HTTP 1.1. Solo se implementan los métodos POST y GET, tomando sólo en
  14                 cuenta la ruta del archivo a obtener (se ignora el <em>query string</em> de
  15                 GET y los datos recibidos por POST). Cada comando se representa a través de
  16                 una ruta a un archivo. Si el comando recibe parámetros, estos parámetros
  17                 son también representados como componentes de dicha ruta.
  18                 A cada comando se responde con una respuesta HTTP 1.1 (también a través de
  19                 una implementación incompleta y limitada). El cuerpo de la respuesta es un
  20                 archivo XML de texto plano en formato XML que contendrá la información
  21                 requerida por el comando (ya sea una lista de archivos o una respuesta
  22                 informando el éxito o error al cambiar las propiedades de una planta).
  23                 Este módulo está implementado por las clases PlaQui::Server::ControlServer
  24                 y PlaQui::Server::ControlClient.
  25
  26                 \subsubsection page_server_general_control_http Ventajas del protocolo HTTP.
  27                         Las ventajas de montar el protocolo del servidor sobre el protocolo
  28                         HTTP son muchas. Las más destacables son las más obvias.
  29
  30                         Al usar el protocolo HTTP se puede controlar el servidor con
  31                         cualquier navegador web. Al ser las respuestas archivos XML es
  32                         fácil agregar hojas de estilo XSLT para convertirlas en HTML y
  33                         transformar un navegador web con capacidad de procesar hojas XSLT
  34                         (como Mozilla) en un cliente casi con las mismas capacidades y
  35                         facilidad de uso que uno hecho especialmente para PlaQui.
  36
  37                         Otra ventaja importante es que muchos lugares sin acceso real a
  38                         Internet tienen acceso a un proxy HTTP, por lo que la accesibilidad
  39                         del servicio se vuelve muy fácil incluso en redes muy protegidas.
  40
  41         \subsection page_server_general_transmision Módulo de Transmisión.
  42                 Este módulo se encarga de transmitir la simulación en tiempo real por UDP
  43                 (como si fuera un video). Comienza luego de que el módulo de control recibe
  44                 una petición de transmisión y continúa transmitiendo (en un principio)
  45                 hasta que recibe una petición de desconexión.
  46                 Lo que se envía es un archivo XML con el estado de la planta.
  47                 El cliente debe validar lo recibido y mostrar todos los <em>frames</em>
  48                 válidos. Mientras que no se reciban <em>frames</em> válidos se debe mostrar
  49                 el último válido. Si no se recibiece durante una cantidad de tiempo
  50                 determinada ningún <em>frame</em> válido, se asume un error en la red.
  51                 Si por casualidad los datos recibidos son incorrectos pero válidos (por
  52                 ejemplo, se recibe el comienzo de un <em>frame</em> y el final del siguente),
  53                 el cliente lo mostrará igual porque no tiene forma de darse cuenta. Esto no
  54                 es problema si consideramos que en pocos milisegundos se recibirá un nuevo
  55                 <em>frame</em> válido y correcto (similar a lo que pasa en transmisiones de
  56                 audio o video en tiempo real).
  57                 Este módulo está implementado por las clases PlaQui::Server::Transmitter y
  58                 PlaQui::Server::Receiver.
  59
  60 \section page_server_protocolo Comandos del Módulo de Control.
  61         Todos los comandos son rutas de archivos. En un principio no se van a utilizar
  62         los <em>query string</em> de los datos pasados por GET ni datos adicionales
  63         recibidos por POST. Es decir, de un <em>request</em> HTTP solo se usara la ruta
  64         para codificar los comandos. Por ejemplo, de:
  65         \verbatim GET /ruta/que/representa/comando?query=string HTTP/1.1 \endverbatim
  66         Sólo se utilizará \verbatim /ruta/que/representa/comando \endverbatim para
  67         codificar el comando. El <em>query string</em> y los datos que se reciban por
  68         POST serán ignorados silenciosamente (sin producir un error).
  69
  70         Todos los comandos son respondidos con una respuesta XML que <b>siempre</b>
  71         incluye un código de éxito/error. Adicionalmente puede devolver más datos en
  72         la respuesta en cuyo caso se especifica expresamente.
  73
  74         Los comandos se tiene una estructura general compuesta por 3 elementos:
  75         - Destino: A quién se le envía el comando.
  76         - Comando: El comando en sí (la acción a realizar).
  77         - Argumentos: Opciones y datos necesarios para ejecutar el comando.
  78         Esto se estructura como una ruta, por lo que todos los comandos se componen la
  79         menos de 2 <em>directorios</em>, con cero o más argumentos representados a su
  80         ves por archivos o más subdirectorios:
  81         /verbatim /[destino]/[comando]/[argumento 1]/[...]/[argumento N] /endverbatim
  82
  83         Los destinos disponibles son:
  84         - <tt>server</tt>: Comandos para el servidor en sí.
  85         - <tt>connection</tt>: Comandos para las conexiones.
  86         - <tt>transmission</tt>: Comandos para las transmisiones.
  87         - <tt>plant</tt>: Comandos para las plantas.
  88
  89         \subsection page_server_protocolo_general Comandos para el Servidor.
  90                 Los comandos para el servidor, como se vio previamente, comienzan con
  91                 <tt>/server/</tt> seguido de alguna de las siguientes opciones:
  92                 <table>
  93                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
  94                         <tr>
  95                                 <td><tt>info</tt></td>
  96                                 <td>Obtiene información sobre el servidor.</td>
  97                                 <td>Cantidad de plantas, conexiones, transmisiones, versión,
  98                                     uptime, etc.</td>
  99                         </tr>
 100                         <tr>
 101                                 <td><tt>stop</tt></td>
 102                                 <td>Detiene el servidor.</td>
 103                                 <td>Nada.</td>
 104                         </tr>
 105                 </table>
 106
 107         \subsection page_server_protocolo_control Comandos para una Conexión de Control.
 108                 Todos los comandos de transmisiones comienzan con <tt>/connection/</tt>
 109                 y continúan con alguna de las siguientes opciones:
 110                 <table>
 111                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 112                         <tr>
 113                                 <td><tt>list</tt></td>
 114                                 <td>Obtiene una lista de las conexiones de control activas.</td>
 115                                 <td>Lista de conexiones activas (host, puerto, uptime, etc).</td>
 116                         </tr>
 117                         <tr>
 118                                 <td><tt>stop/[host]/[port]</tt></td>
 119                                 <td>Finaliza la conexión de control del host [host] en el puerto
 120                                     [port].</td>
 121                                 <td>Nada.</td>
 122                         </tr>
 123                 </table>
 124                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 125
 126         \subsection page_server_protocolo_transmision Comandos para una Transmisión.
 127                 Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
 128                 y continúan con alguna de las siguientes opciones:
 129                 <table>
 130                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 131                         <tr>
 132                                 <td><tt>list</tt></td>
 133                                 <td>Obtiene una lista de las transmisiones activas.</td>
 134                                 <td>Lista de transmisiones activas (host, puerto, uptime,
 135                                     etc).</td>
 136                         </tr>
 137                         <tr>
 138                                 <td><tt>start/[pl]/[host]/[port]</tt></td>
 139                                 <td>Comienza la transmisión de la planta [pl] al [host]
 140                                     en el puerto [port].</td>
 141                                 <td>Nada.</td>
 142                         </tr>
 143                         <tr>
 144                                 <td><tt>stop/[host]/[port]</tt></td>
 145                                 <td>Finaliza la transmisión al [host] en el puerto
 146                                     [port].</td>
 147                                 <td>Nada.</td>
 148                         </tr>
 149                 </table>
 150                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 151
 152         \subsection page_server_protocolo_planta Comandos para una Planta.
 153                 Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con
 154                 alguna de las siguientes opciones:
 155                 <table>
 156                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 157                         <tr>
 158                                 <td><tt>list</tt></td>
 159                                 <td>Obtiene lista de plantas.</td>
 160                                 <td>Lista de plantas con info mínima de cada una (está
 161                                     corriendo o no, uptime, cantidad de elementos,etc).</td>
 162                         </tr>
 163                         <tr>
 164                                 <td><tt>get/[pl]</tt></td>
 165                                 <td>Obtiene la planta de nombre [pl].</td>
 166                                 <td>El mismo archivo que se crea en el Constructor.</td>
 167                         </tr>
 168                         <tr>
 169                                 <td><tt>set/[pl]/[el]/[pr]/[val]</tt></td>
 170                                 <td>Cambia la propiedad [pr] del elemento [el], asignándole
 171                                     el valor [val] a planta de nombre [pl].</td>
 172                                 <td>Nada.</td>
 173                         </tr>
 174                         <tr>
 175                                 <td><tt>set_frequency/[pl]/[hz]</tt></td>
 176                                 <td>Cambia la frecuencia de refresco de la simulación de la
 177                                     planta de nombre [pl] a [hz] veces por segundo. Si [hz]
 178                                     es cero ("0"), se usa la frecuencia de refresco por
 179                                     omisión del servidor.</td>
 180                                 <td>Nada.</td>
 181                         </tr>
 182                         <tr>
 183                                 <td><tt>start/[pl]</tt></td>
 184                                 <td>Reanuda (o comienza) la simulación de la planta de nombre
 185                                     [pl].</td>
 186                                 <td>Nada.</td>
 187                         </tr>
 188                         <tr>
 189                                 <td><tt>stop/[pl]</tt></td>
 190                                 <td>Pausa la simulación de la planta de nombre
 191                                     [pl].</td>
 192                                 <td>Nada.</td>
 193                         </tr>
 194                         <tr>
 195                                 <td><tt>remove/[pl]</tt></td>
 196                                 <td>Finaliza la simulación de la planta de nombre
 197                                     [pl] eliminandola del servidor.</td>
 198                                 <td>Nada.</td>
 199                         </tr>
 200                 </table>
 201                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 202
 203 \section page_server_respuesta Respuestas del Módulo de Control.
 204         Las respuestas del servidor, como se dijo anteriormente, son respuestas HTTP, cuyo
 205         cuerpo es un archivo XML. Este archivo se compone de un <em>tag</em> XML
 206         <tt>plaqui-response</tt> y tiene como atributos obligatorios <tt>code</tt> (indica
 207         el \ref PlaQui::Server::Response::Code "código de respuesta", para saber si se
 208         realizó bien el comando) y <tt>version</tt> (indica la versión del formato del
 209         archivo XML, para preveer la posibilidad de que cambie en futuras versiones).
 210         También tiene un atributo opcional <tt>description</tt> que permite agregar una
 211         descripción sobre la respuesta, útil para observar respuestas con un navegador u
 212         otro cliente no específico. El <em>tag</em>plaqui-response</em> puede tener un
 213         contenido, en caso de que la respuesta necesite enviar información al cliente
 214         (como al obtener una planta o una lista). El contenido es a su vez XML y en el
 215         caso de la obtención de una planta tiene el mismo formato que el utilizado por el
 216         Constructor.
 217
 218 \section page_server_implementacion Destalles de la implementación.
 219         El servidor se basa en un la clase PlaQui::Server::Runnable que se utiliza para
 220         encapsular un hilo de ejecución. De ella derivan todas las demás clases
 221         importantes del servidor: PlaQui::Server::TCPServer y PlaQui::Server::Connection.
 222         De esta última derivan todas las posibles conexiónes que hay para la comunicación
 223         entre el servidor y el cliente: PlaQui::Server::ControlClient,
 224         PlaQui::Server::ControlServer, PlaQui::Server::Receiver y
 225         PlaQui::Server::Transmitter. Las dos primeras son utilizadas para la conexión
 226         de control y las dos segundas para la transmisión del estado de la planta por
 227         UDP.
 228
 229         El protocolo HTTP se encapsula en la clases PlaQui::Sever::HTTPMessage y de ella
 230         derivan PlaQui::Sever::HTTPRequest (petición HTTP) y PlaQui::Sever::HTTPResponse
 231         (respuesta HTTP). Hay otras clases auxiliares como PlaQui::Sever::HTTPError que
 232         encapsula un error HTTP.
 233
 234         Finalmente, para abstraerse del protocolo HTTP que se usa de transporte, se
 235         implementan dos clases: PlaQui::Sever::Command y PlaQui::Sever::Response que
 236         representan un comando y una respuestas específicos del servidor PlaQui.
 237
 238         A continuación se incluye un diagrama de clases para tener una visión más general
 239         de las clases más importantes utiilzadas en el servidor:
 240                 \image html cliente_servidor.png
 241                 \image latex cliente_servidor.eps "Diagrama de clases." width=14cm
 242
 243 */
 244
 245 /** \namespace PlaQui::Server
 246
 247 Infrastructura cliente-servidor para PlaQui.
 248
 249 Bajo este espacio de nombres (namespace) se encuentran todas las clases para la
 250 comunicación cliente-servidor de PlaQui. Esto no incluye la interfaz gráfica del
 251 cliente.
 252
 253 */
 254