Se arregla el bug que hacia que el cliente levante mal archivos XML grandes.

[z.facultad/75.42/plaqui.git] / docs / server.txt

diff --git a/docs/server.txt b/docs/server.txt
index 9b17a81ffa5d7d3ab4ef3c6d8496509a9a343631..eaee99a14f135739e8fbbf9f863db92f8942e5a7 100644 (file)
--- a/docs/server.txt
+++ b/docs/server.txt
@@ -1,6 +1,6 @@
 
                          +----------------------------+
 
                          +----------------------------+

-                         | PROPUESTA DE SERVIDOR v0.2 |
+                         | PROPUESTA DE SERVIDOR v0.4 |

                          +----------------------------+
 
                  $Id$
                          +----------------------------+
 
                  $Id$


@@ -51,8 +51,8 @@ problema si consideramos que en pocos milisegundos se recibir
 video en tiempo real).
 
 
 video en tiempo real).
 
 

-Lista de comandos disponibles para el módulo de control:
-========================================================
+Descripción de los comandos para el módulo de control:
+======================================================

 
 Todos los comandos son rutas de archivos. En un principio no se van a utilizar
 los 'query string' de los datos pasados por GET ni datos adicionales pasados
 
 Todos los comandos son rutas de archivos. En un principio no se van a utilizar
 los 'query string' de los datos pasados por GET ni datos adicionales pasados


@@ -60,70 +60,145 @@ por POST. Es decir, de un 'request' HTTP solo se usara la ruta para codificar
 los comandos. Ejemplo: GET /ruta/que/representa/comando?query=string HTTP/1.1
                           '----------------------------'
 Este es el comando que entendera el servidor. La presencia de un 'query string'
 los comandos. Ejemplo: GET /ruta/que/representa/comando?query=string HTTP/1.1
                           '----------------------------'
 Este es el comando que entendera el servidor. La presencia de un 'query string'

-sera ignorada, al igual que datos enviados por POST, silenciosamente (sin
+será ignorada, al igual que datos enviados por POST, silenciosamente (sin

 producir un error).
 
 Todos los comandos son respondidos con una respuesta XML que *siempre* incluye
 un código de éxito/error. Adicionalmente puede devolver más datos en la
 respuesta en cuyo caso se especifica expresamente.
 
 producir un error).
 
 Todos los comandos son respondidos con una respuesta XML que *siempre* incluye
 un código de éxito/error. Adicionalmente puede devolver más datos en la
 respuesta en cuyo caso se especifica expresamente.
 

-Comandos Generales:
--------------------
-Los nombres entre "<" y ">" denotan un argumento.
-
-Comando                      |Descripción           |Respuesta
-----------------------+----------------------+----------------------------------
-/                     |Obtiene estado general|Cantidad de plantas,
-                      |del servidor.         |conexiones, transmisiones,
-                      |                      |versión, uptime, etc.
-----------------------+----------------------+----------------------------------
-/plants               |Obtiene lista de      |Lista de plantas con info mínima
-                      |plantas.              |de cada una (está corriendo o no,
-                      |                      |uptime, cantidad de elementos,etc)
-----------------------+----------------------+----------------------------------
-/plants/<nombre>      |Obtiene la planta de  |El mismo archivo que se crea en el
-                      |nombre <nombre>.      |Constructor.
-----------------------+----------------------+----------------------------------
-/transmissions        |Obtiene una lista de  |Lista de transmisiones activas
-                      |las transmisiones     |(host, puerto, uptime, etc).
-                      |activas.              |
+Comandos en general:
+--------------------
+Los comandos se tiene una estructura general compuesta por 3 elementos:
+- Destino: A quien 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 'directorios' anidados, con cero o más argumentos representados a su
+ves por archivos o más subdirectorios:
+/<destino>/<comando>/<argumento 1>/<argumento 2>/<...>/<argumento N>
+
+Los destinos disponibles serán:
+- server: Comandos para el servidor en sí.
+- plant: Comandos para las plantas.
+- transmission: Comandos para las transmisiones (el módulo de transmisión).
+
+Comandos para el servidor:
+--------------------------
+Los comandos para el servidor, como se vio previamente, comienzan con /server/
+seguido de alguna de las siguientes opciones.
+
+Comando         | Descripción            | Respuesta                                   
+---------+------------------------+---------------------------------------------
+status   | Obtiene estado general | Cantidad de plantas, conexiones,
+         | del servidor.          | transmisiones, versión, uptime, etc.
+---------+------------------------+---------------------------------------------
+stop     | Detiene el servidor.   | Nada.

 
 Comandos para una Planta:
 -------------------------
 
 Comandos para una Planta:
 -------------------------

-Todos los comandos de plantas comienzan con /plants/ y reciben un argumento que
-es el nombre de la planta, <nombre>, a la cual enviar el comando.
-Los comandos a continuación comienzan todos con '/plants/<nombre>'.
-
-Comando                      |Descripción           |Respuesta
-----------------------+----------------------+----------------------------------
-/start                |Comienza la simulación|Nada.
-                      |de la planta de nombre|
-                      |<planta>.             |
-----------------------+----------------------+----------------------------------
-/start                |Finaliza la simulación|Nada.
-                      |de la planta de nombre|
-                      |<planta>.             |
-----------------------+----------------------+----------------------------------
-/set/<elem>/<prop>/<v>|Cambia la propiedad   |Nada (a ver si no retorna el valor
-                      |<prop> del elemento   |realmente aceptado).
-                      |<elem>, asignándole   |
-                      |el valor <v>.         |
+Todos los comandos de plantas comienzan con /plant/ y continúan con alguna de
+las siguientes opciones:
+
+Comando               |Descripción                  |Respuesta
+---------------+-----------------------------+----------------------------------
+list           |Obtiene lista de plantas.    |Lista de plantas con info mínima
+               |                             |de cada una (está corriendo o no,
+               |                             |uptime, cantidad de elementos,etc)
+---------------+-----------------------------+----------------------------------
+get/<planta>   |Obtiene la planta de         |El mismo archivo que se crea en el
+               |nombre <planta>.             |Constructor.
+---------------+-----------------------------+----------------------------------
+start/<planta> |Comienza la simulación de la |Nada.
+               |planta de nombre <planta>.   |
+---------------+-----------------------------+----------------------------------
+stop/<planta>  |Finaliza la simulación de la |Nada.
+               |planta de nombre <planta>.   |
+---------------+-----------------------------+----------------------------------
+set/<planta>   |Cambia la propiedad <prop>   |Nada (a ver si no retorna el valor
+ /<elem>       |del elemento <elem>,         |realmente aceptado).
+ /<prop>       |asignándole el valor <val> a |
+ /<val>        |planta de nombre <planta>.   |
+
+NOTA: Los nombres entre "<" y ">" denotan un argumento.

 
 Comandos para una Transmisión:
 ------------------------------
 
 Comandos para una Transmisión:
 ------------------------------

-Todos los comandos de transmisiones comienzan con /transmissions.
-Los comandos a continuación comienzan todos con '/transmissions'.
-Los argumentos entre "[" y "]" son opcionales. De omitirse se usan valores por
-predefinidos.
-
-Comando                        |Descripción                                 |Respuesta
-------------------------+--------------------------------------------+----------
-/start/<host>/[<port>]  |Comienza la transmisión al <host> en el     |Nada.
-                        |puerto al <host> en el puerto <port>.       |
-------------------------+--------------------------------------------+----------
-/stop/[<host>]/[<port>] |Finaliza la transmisiónal <host> en el      |Nada.
-                        |puerto <port>. Si se omite el <host>, se    |
-                        |finalizan todas las transmisiones.          |
+Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
+alguna de las siguientes opciones:
+
+Comando                   |Descripción                              |Respuesta
+-------------------+-----------------------------------------+------------------
+list               |Obtiene una lista de las transmisiones   |Lista de transmi-
+                   |activas.                                 |siones activas 
+                   |                                         |(host, puerto, 
+                   |                                         |uptime, etc).
+-------------------+-----------------------------------------+------------------
+start/<plant>      |Comienza la transmisión de la planta     |Nada.
+ /<host>/<port>    |<plant> al <host> en elpuerto al <host>  |
+                   |en el puerto <port>.                     |
+-------------------+-----------------------------------------+------------------
+stop/<host>/<port> |Finaliza la transmisión al <host> en el  |Nada.
+                   |puerto <port>. Si se omite el <port>, se |
+                   |finalizan todas las transmisiones al     |
+                   |<host>. Si se omite el <host>, se        |
+                   |finalizan todas las transmisiones.       |
+
+Comandos para una Conexión de Control:
+--------------------------------------
+Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
+alguna de las siguientes opciones:
+
+Comando                   |Descripción                              |Respuesta
+-------------------+-----------------------------------------+------------------
+list               |Obtiene una lista de las conexiones de   |Lista de conexio-
+                   |control activas.                         |nes activas (host,
+                   |                                         |puerto, uptime,
+                   |                                         |etc).
+-------------------+-----------------------------------------+------------------
+stop/<host>/<port> |Finaliza la conexión de control del host |Nada.
+                   |<host> en el puerto <port>. Si se omite  |
+                   |el <port> se finalizan todas las         |
+                   |conexiones al <host>. Si se omite también|
+                   |el <host>, se finalizan todas las        |
+                   |conexiones de control.                   |
+
+NOTA: Los nombres entre "<" y ">" denotan un argumento.
+
+
+Descripción de los comandos para el módulo de control:
+======================================================
+
+Todas las respuestas consisten de un archivo XML con esta forma (falta hacer la
+DTD):
+<plaqui version="0.1">
+       <response code="[código]" />
+</plaqui>
+El código es obligatorio e informará si el comando se realizó con éxito y en
+caso de no hacerlo, indicará la razón (los códigos faltan definirlos, pero usar
+un esquema similar a los códigos de HTTP sería un buen comienzo).
+La respuesta también puede tener otros contenidos (listado de plantas,
+conexiónes, transmisiones, descripción de una planta completa, etc). Dichos
+contenidos irán contenidos en el tag response:
+<plaqui version="0.1">
+    <response code= "[código]">
+        <list type="plants">
+            <item id="[id1]">
+                <prop name="[nombre1]" value="[valor1]" />
+                <prop name="[nombre2]" value="[valor2]" />
+                <!-- ... más ... -->
+            </item>
+            <item id="[id2]">
+                <prop name="[nombre1]" value="[valor3]" />
+                <prop name="[nombre2]" value="[valor4]" />
+                <!-- ... más ... -->
+            </item>
+        </list>
+    </response>
+</plaqui>
+
+TODO: Ver si la lista va dentro o fuera del tag <response>, ver si el tag
+      <plaqui> está bien, es útil y correcto.

 
 
 Características adicionales (a desarrollar si el tiempo lo permite):
 
 
 Características adicionales (a desarrollar si el tiempo lo permite):


@@ -158,5 +233,15 @@ Es posible hacer que el comando /transmissions/start sin argumentos comience una
 transmisión por 'broadcast' de la planta para todo aquel que quiera monitorearla
 desde la red en la que se haga el 'broadcast'.
 
 transmisión por 'broadcast' de la planta para todo aquel que quiera monitorearla
 desde la red en la que se haga el 'broadcast'.
 

+Atajos de comandos:
+-------------------
+Se trata de 'alias' de comandos. Por ejemplo que '/' de un estado del server
+(/sever/status), que /plant de una lista de plantas, etc.
+
+Valores por defecto:
+--------------------
+Para los comandos que requieren argumentos se podría asumir valores por defecto
+en caso de faltar alguno.
+

 
 vim: set et ts=4 sw=4 tw=80:
 
 vim: set et ts=4 sw=4 tw=80: