+----------------------------+
- | PROPUESTA DE SERVIDOR v0.2 |
+ | PROPUESTA DE SERVIDOR v0.3 |
+----------------------------+
$Id$
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
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.
-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.
+---------+------------------------+---------------------------------------------
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>. |
-----------------------+----------------------+----------------------------------
-/stop |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 <v> a |
+ /<v> |planta de nombre <planta>. |
+
+NOTA: Los nombres entre "<" y ">" denotan un argumento.
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 las |Lista de transmi-
+ |transmisiones activas. |siones activas
+ | |(host, puerto,
+ | |uptime, etc).
+-------------------+-----------------------------------------+------------------
+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. |
+
+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):
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:
projects / z.facultad / 75.42 / plaqui.git / blobdiff