+/** \page page_server PlaQui Server
+
+\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 módulo de control se basa en el protocolo TCP y se encarga de listar
+ los archivos de planta disponibles en el servidor, permitiendo cambiar
+ las propiedades de cada uno y conocer su estado en términos generales
+ (si se está simulando o no). Todo lo que sean comandos (abrir una
+ exclusa, parar una bomba, etc) se realizan a través de este módulo.
+ El protocolo utilizado es una implementación limitada e incompleta de
+ HTTP 1.1. Solo se implementan los métodos POST y GET, tomando sólo en
+ cuenta la ruta del archivo a obtener (se ignora el <em>query string</em> de
+ GET y los datos recibidos por POST). Cada comando se representa a través de
+ una ruta a un archivo. Si el comando recibe parámetros, estos parámetros
+ son también representados como componentes de dicha ruta.
+ A cada comando se responde con una respuesta HTTP 1.1 (también a través de
+ una implementación incompleta y limitada). El cuerpo de la respuesta es un
+ archivo XML de texto plano en formato XML que contendrá la información
+ requerida por el comando (ya sea una lista de archivos o una respuesta
+ informando el éxito o error al cambiar las propiedades de una planta).
+ Este módulo está implementado por las clases PlaQui::Server::ControlServer
+ y PlaQui::Server::ControlClient.
+
+ \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
+ una petición de transmisión y continúa transmitiendo (en un principio)
+ hasta que recibe una petición de desconexión.
+ Lo que se envía es un archivo XML con el estado de la planta.
+ El cliente debe validar lo recibido y mostrar todos los <em>frames</em>
+ válidos. Mientras que no se reciban <em>frames</em> válidos se debe mostrar
+ el último válido. Si no se recibiece durante una cantidad de tiempo
+ determinada ningún <em>frame</em> válido, se asume un error en la red.
+ Si por casualidad los datos recibidos son incorrectos pero válidos (por
+ ejemplo, se recibe el comienzo de un <em>frame</em> y el final del siguente),
+ el cliente lo mostrará igual porque no tiene forma de darse cuenta. Esto no
+ es problema si consideramos que en pocos milisegundos se recibirá un nuevo
+ <em>frame</em> válido y correcto (similar a lo que pasa en transmisiones de
+ audio o video en tiempo real).
+ 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
+ recibidos por POST. Es decir, de un <em>request</em> HTTP solo se usara la ruta
+ para codificar los comandos. Por ejemplo, de:
+ \verbatim GET /ruta/que/representa/comando?query=string HTTP/1.1 \endverbatim
+ Sólo se utilizará \verbatim /ruta/que/representa/comando \endverbatim para
+ codificar el comando. El <em>query string</em> y los datos que se reciban por
+ POST serán ignorados silenciosamente (sin producir un error).
+
+ Todos los comandos son respondidos con una respuesta XML que <b>siempre</b>
+ incluye un código de éxito/error. Adicionalmente puede devolver más datos en
+ la respuesta en cuyo caso se especifica expresamente.
+
+ Los comandos se tiene una estructura general compuesta por 3 elementos:
+ - Destino: A quién se le envía el comando.
+ - Comando: El comando en sí (la acción a realizar).
+ - Argumentos: Opciones y datos necesarios para ejecutar el comando.
+ Esto se estructura como una ruta, por lo que todos los comandos se componen la
+ menos de 2 <em>directorios</em>, con cero o más argumentos representados a su
+ ves por archivos o más subdirectorios:
+ /verbatim /[destino]/[comando]/[argumento 1]/[...]/[argumento N] /endverbatim
+
+ Los destinos disponibles son:
+ - <tt>server</tt>: Comandos para el servidor en sí.
+ - <tt>connection</tt>: Comandos para las conexiones.
+ - <tt>transmission</tt>: Comandos para las transmisiones.
+ - <tt>plant</tt>: Comandos para las plantas.
+
+ \subsection page_server_protocolo_general Comandos para el Servidor.
+ Los comandos para el servidor, como se vio previamente, comienzan con
+ <tt>/server/</tt> seguido de alguna de las siguientes opciones:
+ <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>Cantidad de plantas, conexiones, transmisiones, versión,
+ uptime, etc.</td>
+ </tr>
+ <tr>
+ <td><tt>stop</tt></td>
+ <td>Detiene el servidor.</td>
+ <td>Nada.</td>
+ </tr>
+ </table>
+
+ \subsection page_server_protocolo_control Comandos para una Conexión de Control.
+ Todos los comandos de transmisiones comienzan con <tt>/connection/</tt>
+ y continúan con alguna de las siguientes opciones:
+ <table>
+ <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
+ <tr>
+ <td><tt>list</tt></td>
+ <td>Obtiene una lista de las conexiones de control activas.</td>
+ <td>Lista de conexiones activas (host, puerto, uptime, etc).</td>
+ </tr>
+ <tr>
+ <td><tt>stop/[host]/[port]</tt></td>
+ <td>Finaliza la conexión de control del host [host] en el puerto
+ [port].</td>
+ <td>Nada.</td>
+ </tr>
+ </table>
+ \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
+
+ \subsection page_server_protocolo_transmision Comandos para una Transmisión.
+ Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
+ y continúan con alguna de las siguientes opciones:
+ <table>
+ <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
+ <tr>
+ <td><tt>list</tt></td>
+ <td>Obtiene una lista de las transmisiones activas.</td>
+ <td>Lista de transmisiones activas (host, puerto, uptime,
+ etc).</td>
+ </tr>
+ <tr>
+ <td><tt>start/[plant]/[host]/[port]</tt></td>
+ <td>Comienza la transmisión de la planta [plant] al [host]
+ en el puerto [port].</td>
+ <td>Nada.</td>
+ </tr>
+ <tr>
+ <td><tt>stop/[host]/[port]</tt></td>
+ <td>Finaliza la transmisión al [host] en el puerto
+ [port].</td>
+ <td>Nada.</td>
+ </tr>
+ </table>
+ \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan 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
+ alguna de las siguientes opciones:
+ <table>
+ <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
+ <tr>
+ <td><tt>list</tt></td>
+ <td>Obtiene lista de plantas.</td>
+ <td>Lista de plantas con info mínima de cada una (está
+ 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>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>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>Nada.</td>
+ </tr>
+ </table>
+ \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
+
+\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).
+
+ Invocación del servidor:
+ \verbatim ./plaqui-server [planta.xml] [puerto] \endverbatim
+
+ 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).
+
+*/
projects / z.facultad / 75.42 / plaqui.git / commitdiff