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
  79         Esto se estructura como una ruta, por lo que todos los comandos se componen la
  80         menos de 2 <em>directorios</em>, con cero o más argumentos representados a su
  81         ves por archivos o más subdirectorios:
  82         \verbatim /[destino]/[comando]/[argumento 1]/[...]/[argumento N] \endverbatim
  83
  84         Los destinos disponibles son:
  85         - <tt>server</tt>: Comandos para el servidor en sí.
  86         - <tt>connection</tt>: Comandos para las conexiones.
  87         - <tt>transmission</tt>: Comandos para las transmisiones.
  88         - <tt>plant</tt>: Comandos para las plantas.
  89
  90         \subsection page_server_protocolo_general Comandos para el Servidor.
  91                 Los comandos para el servidor, como se vio previamente, comienzan con
  92                 <tt>/server/</tt> seguido de alguna de las siguientes opciones:
  93                 <table>
  94                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
  95                         <tr>
  96                                 <td><tt>info</tt></td>
  97                                 <td>Obtiene información sobre el servidor.</td>
  98                                 <td>Cantidad de plantas, conexiones, transmisiones, versión,
  99                                     uptime, etc.</td>
 100                         </tr>
 101                         <tr>
 102                                 <td><tt>stop</tt></td>
 103                                 <td>Detiene el servidor.</td>
 104                                 <td>Nada.</td>
 105                         </tr>
 106                 </table>
 107
 108         \subsection page_server_protocolo_control Comandos para una Conexión de Control.
 109                 Todos los comandos de transmisiones comienzan con <tt>/connection/</tt>
 110                 y continúan con alguna de las siguientes opciones:
 111                 <table>
 112                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 113                         <tr>
 114                                 <td><tt>list</tt></td>
 115                                 <td>Obtiene una lista de las conexiones de control activas.</td>
 116                                 <td>Lista de conexiones activas (host, puerto, uptime, etc).</td>
 117                         </tr>
 118                         <tr>
 119                                 <td><tt>stop/[host]/[port]</tt></td>
 120                                 <td>Finaliza la conexión de control del host [host] en el puerto
 121                                     [port].</td>
 122                                 <td>Nada.</td>
 123                         </tr>
 124                 </table>
 125                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 126
 127         \subsection page_server_protocolo_transmision Comandos para una Transmisión.
 128                 Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
 129                 y continúan con alguna de las siguientes opciones:
 130                 <table>
 131                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 132                         <tr>
 133                                 <td><tt>list</tt></td>
 134                                 <td>Obtiene una lista de las transmisiones activas.</td>
 135                                 <td>Lista de transmisiones activas (host, puerto, uptime,
 136                                     etc).</td>
 137                         </tr>
 138                         <tr>
 139                                 <td><tt>start/[pl]/[host]/[port]</tt></td>
 140                                 <td>Comienza la transmisión de la planta [pl] al [host]
 141                                     en el puerto [port].</td>
 142                                 <td>Nada.</td>
 143                         </tr>
 144                         <tr>
 145                                 <td><tt>stop/[host]/[port]</tt></td>
 146                                 <td>Finaliza la transmisión al [host] en el puerto
 147                                     [port].</td>
 148                                 <td>Nada.</td>
 149                         </tr>
 150                 </table>
 151                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 152
 153         \subsection page_server_protocolo_planta Comandos para una Planta.
 154                 Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con
 155                 alguna de las siguientes opciones:
 156                 <table>
 157                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 158                         <tr>
 159                                 <td><tt>list</tt></td>
 160                                 <td>Obtiene lista de plantas.</td>
 161                                 <td>Lista de plantas con info mínima de cada una (está
 162                                     corriendo o no, uptime, cantidad de elementos,etc).</td>
 163                         </tr>
 164                         <tr>
 165                                 <td><tt>get/[pl]</tt></td>
 166                                 <td>Obtiene la planta de nombre [pl].</td>
 167                                 <td>El mismo archivo que se crea en el Constructor.</td>
 168                         </tr>
 169                         <tr>
 170                                 <td><tt>set/[pl]/[el]/[pr]/[val]</tt></td>
 171                                 <td>Cambia la propiedad [pr] del elemento [el], asignándole
 172                                     el valor [val] a planta de nombre [pl].</td>
 173                                 <td>Nada.</td>
 174                         </tr>
 175                         <tr>
 176                                 <td><tt>set_frequency/[pl]/[hz]</tt></td>
 177                                 <td>Cambia la frecuencia de refresco de la simulación de la
 178                                     planta de nombre [pl] a [hz] veces por segundo. Si [hz]
 179                                     es cero ("0"), se usa la frecuencia de refresco por
 180                                     omisión del servidor.</td>
 181                                 <td>Nada.</td>
 182                         </tr>
 183                         <tr>
 184                                 <td><tt>start/[pl]</tt></td>
 185                                 <td>Reanuda (o comienza) la simulación de la planta de nombre
 186                                     [pl].</td>
 187                                 <td>Nada.</td>
 188                         </tr>
 189                         <tr>
 190                                 <td><tt>stop/[pl]</tt></td>
 191                                 <td>Pausa la simulación de la planta de nombre
 192                                     [pl].</td>
 193                                 <td>Nada.</td>
 194                         </tr>
 195                         <tr>
 196                                 <td><tt>remove/[pl]</tt></td>
 197                                 <td>Finaliza la simulación de la planta de nombre
 198                                     [pl] eliminandola del servidor.</td>
 199                                 <td>Nada.</td>
 200                         </tr>
 201                 </table>
 202                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 203
 204 \section page_server_respuesta Respuestas del Módulo de Control.
 205         Las respuestas del servidor, como se dijo anteriormente, son respuestas HTTP, cuyo
 206         cuerpo es un archivo XML. Este archivo se compone de un <em>tag</em> XML
 207         <tt>plaqui-response</tt> y tiene como atributos obligatorios <tt>code</tt> (indica
 208         el \ref PlaQui::Server::Response::Code "código de respuesta", para saber si se
 209         realizó bien el comando) y <tt>version</tt> (indica la versión del formato del
 210         archivo XML, para preveer la posibilidad de que cambie en futuras versiones).
 211         También tiene un atributo opcional <tt>description</tt> que permite agregar una
 212         descripción sobre la respuesta, útil para observar respuestas con un navegador u
 213         otro cliente no específico. El <em>tag</em>plaqui-response</em> puede tener un
 214         contenido, en caso de que la respuesta necesite enviar información al cliente
 215         (como al obtener una planta o una lista). El contenido es a su vez XML y en el
 216         caso de la obtención de una planta tiene el mismo formato que el utilizado por el
 217         Constructor.
 218
 219 \section page_server_implementacion Destalles de la implementación.
 220         El servidor se basa en un la clase PlaQui::Server::Runnable que se utiliza para
 221         encapsular un hilo de ejecución. De ella derivan todas las demás clases
 222         importantes del servidor: PlaQui::Server::TCPServer y PlaQui::Server::Connection.
 223         De esta última derivan todas las posibles conexiónes que hay para la comunicación
 224         entre el servidor y el cliente: PlaQui::Server::ControlClient,
 225         PlaQui::Server::ControlServer, PlaQui::Server::Receiver y
 226         PlaQui::Server::Transmitter. Las dos primeras son utilizadas para la conexión
 227         de control y las dos segundas para la transmisión del estado de la planta por
 228         UDP.
 229
 230         El protocolo HTTP se encapsula en la clases PlaQui::Server::HTTPMessage y de ella
 231         derivan PlaQui::Server::HTTPRequest (petición HTTP) y PlaQui::Server::HTTPResponse
 232         (respuesta HTTP). Hay otras clases auxiliares como PlaQui::Server::HTTPError que
 233         encapsula un error HTTP.
 234
 235         Finalmente, para abstraerse del protocolo HTTP que se usa de transporte, se
 236         implementan dos clases: PlaQui::Server::Command y PlaQui::Server::Response que
 237         representan un comando y una respuestas específicos del servidor PlaQui.
 238
 239         A continuación se incluye un diagrama de clases para tener una visión más general
 240         de las clases más importantes utiilzadas en el servidor:
 241                 \image html cliente_servidor.png
 242                 \image latex cliente_servidor.eps "Diagrama de clases." width=14cm
 243
 244 */
 245
 246 /** \namespace PlaQui::Server
 247
 248 Infrastructura cliente-servidor para PlaQui.
 249
 250 Bajo este espacio de nombres (namespace) se encuentran todas las clases para la
 251 comunicación cliente-servidor de PlaQui. Esto no incluye la interfaz gráfica del
 252 cliente.
 253
 254 */
 255